Обновление до пакета SDK для .NET для Службы поиска Azure версии 3

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

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

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

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

Версия 3 пакета SDK для .NET для поиска Azure предназначена для последней общедоступной версии REST API поиска Azure, в частности 2016-09-01. Это позволяет использовать множество новых функций поиска Azure из приложения .NET, в том числе следующие:

• Пользовательские анализаторы
• Поддержка индексатора хранилища BLOB-объектов Azure и хранилища таблиц Azure
• Настройка индексатора с помощью сопоставлений полей
• Поддержка ETags для обеспечения безопасного параллельного обновления определений индексов, индексаторов и источников данных
• Поддержка создания определений полей индекса декларативно путем декорирования класса модели и использования нового FieldBuilder класса.
• Поддержка .NET Core и переносимого профиля .NET 111

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

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

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

Если сборка завершается сбоем, вы увидите ошибку сборки, как показано ниже:

Program.cs(31,45,31,86): error CS0266: Cannot implicitly convert type 'Microsoft.Azure.Search.ISearchIndexClient' to 'Microsoft.Azure.Search.SearchIndexClient'. An explicit conversion exists (are you missing a cast?)

Следующим шагом является исправление этой ошибки сборки. См. Критические изменения в версии 3 для подробностей о причинах ошибки и способах ее устранения.

Вы можете увидеть дополнительные предупреждения сборки, связанные с устаревшими методами или свойствами. Предупреждения будут содержать инструкции по использованию вместо нерекомендуемой функции. Например, если ваше приложение использует свойство IndexingParameters.Base64EncodeKeys, вы должны получить предупреждение, которое гласит "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead.".

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

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

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

Тип возвращаемого значения Indexes.GetClient

Метод Indexes.GetClient имеет новый тип возвращаемого значения. Ранее возвращалось SearchIndexClient, но это было изменено на ISearchIndexClient в версии 2.0-preview, и это изменение перенесено в версию 3. Это необходимо для поддержки клиентов, которые хотят замокировать метод GetClient для модульных тестов, возвращая замокированную реализацию ISearchIndexClient.

Пример

Если код выглядит следующим образом:

SearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

Вы можете изменить его на это, чтобы устранить ошибки сборки:

ISearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

AnalyzerName, DataType и другие больше неявно преобразуются в строки

В пакете SDK для поиска Azure для .NET существует множество типов, производных от ExtensibleEnum. Ранее эти типы были все неявно преобразованы в тип string. Однако в реализации Object.Equals этих классов была обнаружена ошибка, и для её исправления требовалось отключить это неявное преобразование. Явное преобразование string в это значение по-прежнему разрешено.

Пример

Если код выглядит следующим образом:

var customTokenizerName = TokenizerName.Create("my_tokenizer"); 
var customTokenFilterName = TokenFilterName.Create("my_tokenfilter"); 
var customCharFilterName = CharFilterName.Create("my_charfilter"); 
 
var index = new Index();
index.Analyzers = new Analyzer[] 
{ 
    new CustomAnalyzer( 
        "my_analyzer",  
        customTokenizerName,  
        new[] { customTokenFilterName },  
        new[] { customCharFilterName }), 
}; 

Вы можете изменить его на это, чтобы устранить ошибки сборки:

const string CustomTokenizerName = "my_tokenizer"; 
const string CustomTokenFilterName = "my_tokenfilter"; 
const string CustomCharFilterName = "my_charfilter"; 
 
var index = new Index();
index.Analyzers = new Analyzer[] 
{ 
    new CustomAnalyzer( 
        "my_analyzer",  
        CustomTokenizerName,  
        new TokenFilterName[] { CustomTokenFilterName },  
        new CharFilterName[] { CustomCharFilterName })
}; 

Удалены устаревшие элементы

Вы можете увидеть ошибки сборки, связанные с методами или свойствами, которые были помечены как устаревшие в версии 2.0-preview и затем удалены в версии 3. При возникновении таких ошибок здесь показано, как устранить их:

• Если вы использовали этот конструктор: ScoringParameter(string name, string value)используйте следующий: ScoringParameter(string name, IEnumerable<string> values)
• Если вы использовали ScoringParameter.Value свойство, используйте свойство ScoringParameter.Values или метод ToString вместо него.
• Если вы использовали SearchRequestOptions.RequestId свойство, используйте ClientRequestId его вместо этого.

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

Если вы обновляете версию 2.0-preview до версии 3, помните, что поддержка синтаксического анализа JSON и CSV для индексаторов BLOB-объектов была удалена, так как эти функции по-прежнему находятся в предварительной версии. В частности, были удалены следующие методы IndexingParametersExtensions класса:

• ParseJson
• ParseJsonArrays
• ParseDelimitedTextFiles

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

Заключение

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

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

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