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

Если вы используете версию 4.0-preview пакета SDK .NET или более раннюю версию, сведения в этой статье помогут вам обновить приложение для использования версии 5.

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

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

Примечание

Если вы используете версию 2.0-preview или более раннюю, то сначала следует установить версию 3 и только затем обновить ее до версии 5. Инструкции приведены в разделе Обновление пакета SDK службы поиска Azure для .NET до версии 3.

Экземпляр службы поиска Azure поддерживает несколько версий REST API, включая последнюю. Можно продолжать использовать версию, которая больше не является последней, но рекомендуется выполнить перенос кода, чтобы использовать последнюю версию. При использовании REST API необходимо указывать версию API в каждом запросе с помощью параметра api-version. При использовании пакета SDK для .NET версия пакета SDK, которую вы используете, определяет соответствующую версию REST API. Если вы используете устаревшую версию пакета SDK, можно продолжать выполнять этот код без изменений, даже если служба обновлена для поддержки более новой версии API.

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

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

• Синонимы.
• Теперь вы можете осуществлять программный доступ к предупреждениям в журнале выполнения индексатора (дополнительные сведения см. в описании свойства Warning для IndexerExecutionResult в справочнике по .NET).
• Поддержка .NET Core 2.
• Новая структура пакета поддерживает использование только необходимых вам частей пакета SDK (подробные сведения см. в разделе Критические изменения в версии 5).

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

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

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

В противном случае отобразится сообщение об ошибке сборки следующего вида.

The name 'SuggesterSearchMode' does not exist in the current context

Далее необходимо устранить эту ошибку сборки. Сведения о причинах ошибки и способах ее устранения см. в разделе Критические изменения в версии 5.

Обратите внимание, что из-за изменений в упаковке пакета SDK службы поиска Azure для .NET необходимо перестроить приложение для использования версии 5. Эти изменения описаны в разделе Критические изменения в версии 5.

Могут появиться дополнительные предупреждения о сборке, связанные с устаревшими методами или свойствами. В предупреждениях будет указано, что следует использовать вместо устаревшей функции. Например, если приложение использует метод IndexingParametersExtensions.DoNotFailOnUnsupportedContentType, должно появиться предупреждение: "This behavior is now enabled by default, so calling this method is no longer necessary". (Теперь это поведение включено по умолчанию, поэтому вызывать этот метод больше не требуется.)

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

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

Новая структура пакета

Самым значительным критическим изменением в версии 5 является то, что сборка Microsoft.Azure.Search и ее содержимое разделены на четыре отдельных сборки, которые теперь распространяются в виде четырех отдельных пакетов NuGet.

• Microsoft.Azure.Search: это метапакет, содержащий все остальные пакеты службы поиска Azure в виде зависимостей. При обновлении с более ранней версии пакета SDK достаточно просто обновить и перестроить этот пакет, чтобы приступить к использованию новой версии.
• Microsoft.Azure.Search.Data: используйте этот пакет, если вы разрабатываете приложение .NET с помощью службы поиска Azure и вам необходимо только запрашивать и обновлять документы в индексах. Если требуется также создавать или обновлять индексы, карты синонимов и другие ресурсы уровня службы, используйте пакет Microsoft.Azure.Search.
• Microsoft.Azure.Search.Service: используйте этот пакет, если вы разрабатываете автоматизацию в .NET для управления индексами, картами синонимов, индексаторами, источниками данных службы поиска Azure или другими ресурсами уровня службы. Если требуется только запрашивать и обновлять документы в индексах, используйте пакет Microsoft.Azure.Search.Data. Чтобы использовать все функциональные возможности службы поиска Azure, используйте пакет Microsoft.Azure.Search.
• Microsoft.Azure.Search.Common: общие типы, необходимые библиотекам .NET службы поиска Azure. Этот пакет не нужно использовать непосредственно в приложении. Он предназначен только для применения в качестве зависимости.

Это изменение является технически критическим, так как многие типы были перемещены между сборками. Именно поэтому необходимо перестроить приложение, чтобы выполнить обновление до версии 5 пакета SDK.

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

Изменение средств подбора

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

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

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

• Если вы использовали метод IndexingParametersExtensions.IndexStorageMetadataOnly, используйте SetBlobExtractionMode(BlobExtractionMode.StorageMetadata) вместо него.
• Если вы использовали метод IndexingParametersExtensions.SkipContent, используйте SetBlobExtractionMode(BlobExtractionMode.AllMetadata) вместо него.

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

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

• ParseJsonArrays
• ParseDelimitedTextFiles

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

Заключение

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

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

Благодарим вас за использование поиска Azure!