升级到 Azure 搜索 .NET SDK 版本 5

如果使用版本 4.0-preview 或更高版本的 .NET SDK，本文将帮助你升级应用程序以使用版本 5。

要获得有关 SDK 的更全面的演练，包括示例，可以参阅 #B0 从 .NET 应用程序中使用 Azure 搜索的方法 #A1。

Azure 搜索 .NET SDK 版本 5 包含早期版本中的一些更改。 这些大多是次要的，因此更改代码只需要最少的努力。 请参阅 升级步骤，以获取将代码更改为使用新 SDK 版本的说明。

注释

如果使用的是版本 2.0-preview 或更早版本，则应先升级到版本 3，然后再升级到版本 5。 有关说明 ，请参阅升级到 Azure 搜索 .NET SDK 版本 3 。

Azure 搜索服务实例支持多个 REST API 版本，包括最新的版本。 当版本不再是最新版本时，可以继续使用版本，但我们建议迁移代码以使用最新版本。 使用 REST API 时，必须通过 API 版本参数在每个请求中指定 API 版本。 使用 .NET SDK 时，所使用的 SDK 版本决定了 REST API 的相应版本。 如果使用较旧的 SDK，即使服务已升级以支持较新的 API 版本，也可以继续运行该代码，且不会发生任何更改。

版本 5 中的新增功能

Azure 搜索 .NET SDK 版本 5 旨在与 Azure 搜索 REST API 的最新可用正式版本对接，特别是 API 版本日期为 2017-11-11。 这样，就可以从 .NET 应用程序使用 Azure 搜索的新功能，包括：

  • 同义词。
  • 现在可以以编程方式访问索引器执行历史记录中的警告（有关详细信息，请参阅 WarningIndexerExecutionResult中的属性）。
  • 对 .NET Core 2 的支持。
  • 新包结构仅支持使用所需的 SDK 部分（有关详细信息，请参阅 版本 5 中的中断性变更 ）。

升级步骤

首先，在 Visual Studio 中，更新项目中的 Microsoft.Azure.Search 的 NuGet 引用，可以通过使用 NuGet 包管理器控制台，或者右键单击项目中的引用并选择“管理 NuGet 包...” 。

NuGet 下载新包及其依赖项后，请重新生成项目。 根据代码的结构，它可能会成功重建。 如果是这样，你就可以上路了！

如果生成失败，应会看到生成错误，如下所示：

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

下一步是修复此生成错误。 有关导致错误的原因以及如何修复此错误的详细信息，请参阅 版本 5 的重大变更。

请注意，由于 Azure 搜索 .NET SDK 打包更改，必须重新生成应用程序才能使用版本 5。 这些更改在 版本 5 的重大更改中进行了详细介绍。

你可能会看到与过时的方法或属性相关的其他编译警告。 这些警告将包含有关如何使用的说明，而不是弃用的功能。 例如，如果应用程序使用 IndexingParametersExtensions.DoNotFailOnUnsupportedContentType 该方法，则应收到一条警告，指出“此行为默认已启用，因此不再需要调用此方法。

修复任何生成错误或警告后，可以更改应用程序以利用新功能（如果需要）。 有关 SDK 新功能的详细信息，请参阅 版本 5 的新增内容。

版本 5 的重大变更

新包结构

版本 5 中最大的重大变更是 Microsoft.Azure.Search 程序集及其内容已被划分为四个单独的程序集，它们现在被作为四个单独的 NuGet 包分发：

  • Microsoft.Azure.Search：这是一个元包，其中包含所有其他 Azure 搜索包作为依赖项。 如果要从早期版本的 SDK 升级，只需升级此包并重新构建即可开始使用新版本。
  • Microsoft.Azure.Search.Data：如果使用 Azure 搜索开发 .NET 应用程序，并且只需查询或更新索引中的文档，请使用此包。 如果还需要创建或更新索引、同义词映射或其他服务级别资源，请改用 Microsoft.Azure.Search 包。
  • Microsoft.Azure.Search.Service：如果要在 .NET 中开发自动化来管理 Azure 搜索索引、同义词映射、索引器、数据源或其他服务级别资源，请使用此包。 如果只需要查询或更新索引中的文档，请改用 Microsoft.Azure.Search.Data 包。 如果需要 Azure 搜索的所有功能，请改用 Microsoft.Azure.Search 包。
  • Microsoft.Azure.Search.Common：Azure 搜索 .NET 库所需的常见类型。 不应直接在应用程序中使用此包;它仅用于用作依赖项。

此更改在技术上破坏了兼容性，因为许多类型在不同的程序集之间进行迁移。 这就是为什么需要重新生成应用程序才能升级到 SDK 版本 5 的原因。

在版本 5 中，除了需要重新构建应用程序之外，还有一些其他破坏性更改可能需要更改代码。

更改为建议器

构造函数Suggester不再具有enum参数SuggesterSearchMode。 此枚举只有一个值，因此是冗余的。 如果由于此原因而看到生成错误，只需删除对参数的 SuggesterSearchMode 引用。

删除了已过时的成员

你可能会看到与早期版本中标记为已过时的方法或属性相关的生成错误，随后在版本 5 中删除。 如果遇到此类错误，下面介绍了如何解决这些错误：

  • 如果使用此方法 IndexingParametersExtensions.IndexStorageMetadataOnly ，请改用 SetBlobExtractionMode(BlobExtractionMode.StorageMetadata) 。
  • 如果使用此方法 IndexingParametersExtensions.SkipContent ，请改用 SetBlobExtractionMode(BlobExtractionMode.AllMetadata) 。

已删除预览功能

如果要从版本 4.0-preview 升级到版本 5，请注意，已删除对 Blob 索引器的 JSON 数组和 CSV 分析支持，因为这些功能仍处于预览状态。 具体而言，已删除类的 IndexingParametersExtensions 以下方法：

  • ParseJsonArrays
  • ParseDelimitedTextFiles

如果应用程序依赖于这些功能，则无法升级到 Azure 搜索 .NET SDK 版本 5。 可以继续使用版本 4.0-preview。 但是，请记住，我们不建议在生产环境的应用程序中使用预览版 SDK。 预览功能仅用于评估，可能会更改。

结论

如果需要有关使用 Azure 搜索 .NET SDK 的更多详细信息，请参阅 .NET 使用指南。

欢迎你对 SDK 的反馈。 如果遇到问题，请随时向我们寻求帮助，Stack Overflow。 如果找到 Bug，可以在 Azure .NET SDK GitHub 存储库中提出问题。 请确保在问题标题前添加“[Azure Search]”前缀。

感谢你使用 Azure 搜索！

  • Last updated on