Обновление до пакета SDK для .NET для поиска Azure версии 9

Если вы используете пакет SDK для поиска Azure для .NET версии 7.0 или более поздней версии, эта статья поможет обновить приложение до версии 9.

Более общее пошаговое руководство по пакету SDK с примерами, см. статью Использование службы "Поиск Azure" в приложении .NET.

Версия 9 пакета SDK для Поиска Azure для .NET содержит множество изменений из предыдущих версий. Некоторые из них могут быть критическими изменениями, но, скорее всего, потребуют только небольших корректировок в вашем коде. Инструкции по обновлению кода для использования новой версии пакета SDK см. в разделе "Действия по обновлению".

Новые возможности версии 9

Версия 9 пакета SDK для .NET для поиска Azure предназначена для версии 2019-05-06 REST API службы поиска Azure со следующими функциями:

• Обогащение искусственного интеллекта — это возможность извлекать текст из изображений, больших двоичных объектов и других неструктурированных источников данных— обогащение содержимого, чтобы сделать его более доступным для поиска в индексе поиска Azure.
• Поддержка сложных типов позволяет моделировать практически любую вложенную структуру JSON в индексе поиска Azure.
• Автозавершение предоставляет альтернативу API Предложения для реализации поведения поиска в процессе ввода. Автозавершение "завершает" слово или фразу, которую пользователь в настоящее время вводит.
• Режим синтаксического анализа JsonLines, часть индексирования BLOB-объектов, создает один документ поиска для сущности JSON, разделенной новой строкой.

Новые функции предварительной версии 8.0-preview

Версия 8.0-preview пакета SDK для поиска Azure для .NET нацелена на версию API 2017-11-11-Preview. Эта версия включает все те же функции версии 9, а также:

• Ключи шифрования, управляемые клиентом для шифрования на стороне службы, являются новой функцией предварительной версии. Помимо встроенного шифрования, управляемого корпорацией Майкрософт, можно применить дополнительный уровень шифрования, где вы являетесь единственным владельцем ключей.

Действия по обновлению

Сначала обновите ссылку NuGet для Microsoft.Azure.Search с помощью консоли диспетчера пакетов NuGet или щелкните правой кнопкой мыши ссылки на проекты и выберите пункт "Управление пакетами NuGet..." в Visual Studio.

После того как NuGet скачает новые пакеты и их зависимости, пересоберите проект. В зависимости от того, как структурирован ваш код, он может успешно перестроиться. Если да, вы готовы пойти!

Если сборка завершается ошибкой, необходимо исправить каждую ошибку сборки. Подробные сведения об устранении каждой потенциальной ошибки сборки см. в статье о критических изменениях в версии 9 .

Вы можете увидеть дополнительные предупреждения сборки, связанные с устаревшими методами или свойствами. Предупреждения будут содержать инструкции по использованию вместо нерекомендуемой функции. Например, если ваше приложение использует DataSourceType.DocumentDb свойство, должно появиться предупреждение с текстом: "Этот элемент устарел". Вместо этого используйте CosmosDb.

После исправления ошибок сборки или предупреждений вы можете внести изменения в приложение, чтобы воспользоваться новыми функциями, если вы хотите. Новые функции пакета SDK подробно описаны в новых возможностях версии 9.

Критические изменения в версии 9

В версии 9 есть несколько критических изменений, которые могут потребовать изменения кода в дополнение к перестроению приложения.

Неизменяемые свойства

Общедоступные свойства нескольких классов моделей теперь неизменяемы. Если необходимо создать пользовательские экземпляры этих классов для тестирования, можно использовать новые параметризованные конструкторы:

• AutocompleteItem
• DocumentSearchResult
• DocumentSuggestResult
• FacetResult
• SearchResult
• SuggestResult

Изменения в поле

Класс Field изменился теперь, когда он может представлять сложные поля.

bool Следующие свойства теперь могут иметь значение NULL:

• IsFilterable
• IsFacetable
• IsSearchable
• IsSortable
• IsRetrievable
• IsKey

Это связано с тем, что эти свойства теперь должны находиться null в случае сложных полей. Если у вас есть код, который считывает эти свойства, он должен быть готов к обработке null. Обратите внимание, что все остальные свойства Field всегда были и продолжают иметь значение NULL, и некоторые из них также будут иметь null значение в случае сложных полей, в частности:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Конструктор Field без параметров стал internal. Теперь каждый Field требует явного имени и типа данных во время построения.

Упрощенные типы пакетов и результатов

В версии 7.0-preview и более ранних версиях различные классы, инкапсулирующие группы документов, были структурированы в параллельные иерархии классов:

• DocumentSearchResult и DocumentSearchResult<T> наследуется от DocumentSearchResultBase
• DocumentSuggestResult и DocumentSuggestResult<T> наследуется от DocumentSuggestResultBase
• IndexAction и IndexAction<T> наследуется от IndexActionBase
• IndexBatch и IndexBatch<T> наследуется от IndexBatchBase
• SearchResult и SearchResult<T> наследуется от SearchResultBase
• SuggestResult и SuggestResult<T> наследуется от SuggestResultBase

Производные типы без параметра универсального типа должны использоваться в сценариях динамического типа и предполагать использование Document типа.

Начиная с версии 8.0-preview базовые классы и не универсальные классы были удалены. Для динамически типизированных сценариев можно использовать IndexBatch<Document>и DocumentSearchResult<Document>т. д.

Удалён ExtensibleEnum

Базовый ExtensibleEnum класс удален. Все классы, производные от него, теперь представляют собой структуры, например AnalyzerNameDataType, и DataSourceType например. Их Create методы также были удалены. Вы можете просто удалить вызовы Create , так как эти типы неявно преобразуются из строк. Если это приводит к ошибкам компилятора, вы можете явно вызвать оператор преобразования путем приведения к неопределенным типам. Например, можно изменить код следующим образом:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", AnalyzerName.Create("my_email_analyzer")) { IsSearchable = true }
    },
    ...
}

следующим образом:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", (AnalyzerName)"my_email_analyzer") { IsSearchable = true }
    },
    ...
}

Свойства, содержащие необязательные значения этих типов, теперь явно типизированы как nullable, чтобы оставаться необязательными.

Удалены facetResults и HitHighlights

Удалены FacetResults классы и HitHighlights классы. Результаты аспектов теперь типизированы как IDictionary<string, IList<FacetResult>>, а выделения находок как IDictionary<string, IList<string>>. Быстрый способ устранить ошибки сборки, представленные этим изменением, — добавить using псевдонимы в верхней части каждого файла, использующего удаленные типы. Рассмотрим пример.

using FacetResults = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<Models.FacetResult>>;
using HitHighlights = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<string>>;

Изменение на Синонимную карту

Конструктор SynonymMap больше не имеет enum параметра для SynonymMapFormat. Это перечисление имело только одно значение и поэтому было избыточным. Если в результате этого возникают ошибки сборки, просто удалите ссылки на SynonymMapFormat параметр.

Другие изменения класса модели

Свойство AutocompleteModeAutocompleteParameters больше не может иметь значение NULL. Если у вас есть код, которому присваивается это свойство null, его можно просто удалить, и свойство будет автоматически инициализировано в значение по умолчанию.

Порядок параметров конструктора IndexAction изменился теперь, когда этот конструктор создается автоматически. Вместо использования конструктора рекомендуется использовать методы фабрики, такие как IndexAction.Upload, IndexAction.Merge, и так далее.

Удалены предварительные версии функций

При обновлении с версии 8.0-preview до версии 9 следует учитывать, что шифрование с помощью ключей, управляемых клиентом, было удалено, так как эта функция по-прежнему находится в предварительной версии. В частности, EncryptionKey свойства Index и SynonymMap были удалены.

Если приложение имеет жесткую зависимость от этой функции, вы не сможете обновить до версии 9 пакета SDK для поиска Azure .NET. Вы можете продолжать использовать версию 8.0-preview. Однако следует помнить, что мы не рекомендуем использовать предварительные пакеты SDK в рабочих приложениях. Предварительные версии функций предназначены только для оценки и могут изменяться.

Изменение поведения в извлечении данных

Если вы используете "динамически типизированные" Search, Suggest или Get API, возвращающие экземпляры типа Document, следует учитывать, что теперь они десериализируют пустые массивы JSON в object[] вместо string[].

Заключение

Дополнительные сведения об использовании пакета SDK для .NET для поиска Azure см. в руководстве по .NET.

Мы приветствуем ваши отзывы о пакете SDK. Если вы столкнулись с проблемами, вы можете попросить нас обратиться за помощью в Stack Overflow. При обнаружении ошибки можно зарегистрировать проблему в репозитории GitHub пакета SDK .NET для Azure. Обязательно добавьте префикс "[Поиск Azure]" к названию проблемы.

Благодарим вас за использование службы "Поиск Azure"