升级到 Azure 搜索 .NET SDK 版本 5Upgrade to Azure Search .NET SDK version 5

如果你使用的是 4.0-preview 版或更早版本的 .NET SDK,本文可帮助你升级应用程序,以使用版本 5。If you're using version 4.0-preview or older of the .NET SDK, this article will help you upgrade your application to use version 5.

有关包括示例的 SDK 的更多常规演练,请参阅如何使用 .NET 应用程序中的 Azure 搜索For a more general walkthrough of the SDK including examples, see How to use Azure Search from a .NET Application.

Azure 搜索 .NET SDK 的版本 5 包含了某些针对早期版本进行的更改。Version 5 of the Azure Search .NET SDK contains some changes from earlier versions. 这些更改主要涉及次要版本,因此更改代码的工作量并不是太大。These are mostly minor, so changing your code should require only minimal effort. 有关如何更改代码以使用新版 SDK 的说明,请参阅升级步骤See Steps to upgrade for instructions on how to change your code to use the new SDK version.

备注

如果使用的是版本 2.0-preview 或更早版本,则应先升级到版本 3,再升级到版本 5。If you're using version 2.0-preview or older, you should upgrade to version 3 first, and then upgrade to version 5. 有关说明,请参阅升级到 Azure 搜索 .NET SDK 版本 3See Upgrading to the Azure Search .NET SDK version 3 for instructions.

Azure 搜索服务实例支持多个 REST API 版本,包括最新的版本。Your Azure Search service instance supports several REST API versions, including the latest one. 可以不使用最新版本,但是我们建议迁移代码,以便使用最新版本。You can continue to use a version when it is no longer the latest one, but we recommend that you migrate your code to use the newest version. 使用 REST API 时,必须在每个请求中通过 api-version 参数指定 API 版本。When using the REST API, you must specify the API version in every request via the api-version parameter. 使用 .NET SDK 时,使用的 SDK 版本确定对应的 REST API 版本。When using the .NET SDK, the version of the SDK you're using determines the corresponding version of the REST API. 如果使用较旧的 SDK,即使已升级服务以支持较新的 API 版本,也可以继续运行代码,而不进行任何更改。If you are using an older SDK, you can continue to run that code with no changes even if the service is upgraded to support a newer API version.

版本 5 中的新增功能What's new in version 5

Azure 搜索 .NET SDK 的版本 5 针对 Azure 搜索 REST API 的最新正式发布版本,具体来说就是 2017-11-11。Version 5 of the Azure Search .NET SDK targets the latest generally available version of the Azure Search REST API, specifically 2017-11-11. 这使得可在 .NET 应用程序中使用 Azure 搜索的新功能,如下所示:This makes it possible to use new features of Azure Search from a .NET application, including the following:

  • 同义词Synonyms.
  • 现可以编程方式访问索引器执行历史记录中的警告(有关更多详细信息,请参阅 .NET 引用IndexerExecutionResultWarning 属性)。You can now programmatically access warnings in indexer execution history (see the Warning property of IndexerExecutionResult in the .NET reference for more details).
  • 支持 .NET Core 2。Support for .NET Core 2.
  • 新的包结构支持使用仅需要的 SDK 的部件(有关详细信息,请参阅版本 5 中的重大更改)。New package structure supports using only the parts of the SDK that you need (see Breaking changes in version 5 for details).

升级步骤Steps to upgrade

首先,按以下方法操作更新 Microsoft.Azure.Search 的 NuGet 引用:使用 NuGet 包管理器控制台,或者在 Visual Studio 中右键单击项目引用,然后选择“管理 NuGet 程序包...”。First, update your NuGet reference for Microsoft.Azure.Search using either the NuGet Package Manager Console or by right-clicking on your project references and selecting "Manage NuGet Packages..." in Visual Studio.

在 NuGet 已下载新的程序包及其依赖项后,请重新生成项目。Once NuGet has downloaded the new packages and their dependencies, rebuild your project. 项目重新生成可能会成功,具体取决于代码的结构。Depending on how your code is structured, it may rebuild successfully. 如果成功,一切准备就绪!If so, you're ready to go!

如果生成失败,应该会看到如下所示的生成错误:If your build fails, you should see a build error like the following:

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

下一步是修复生成错误。The next step is to fix this build error. 有关出错原因和修复方法的详细信息,请参阅版本 5 中的重大更改See Breaking changes in version 5 for details on what causes the error and how to fix it.

请注意,由于更改了 Azure 搜索 .NET SDK 的包,必须重新生成应用程序才能使用版本 5。Please note that due to changes in the packaging of the Azure Search .NET SDK, you must rebuild your application in order to use version 5. 有关这些更改的详细信息,请参阅版本 5 中的重大更改These changes are detailed in Breaking changes in version 5.

可能会看到与已过时方法或属性有关的其他生成警告。You may see additional build warnings related to obsolete methods or properties. 这些警告将包含有关使用哪些功能来替换已弃用功能的说明。The warnings will include instructions on what to use instead of the deprecated feature. 例如,如果应用程序使用 IndexingParametersExtensions.DoNotFailOnUnsupportedContentType 方法,则出现一个警告“此行为现在默认启用,因此不再需要调用此方法。”For example, if your application uses the IndexingParametersExtensions.DoNotFailOnUnsupportedContentType method, you should get a warning that says "This behavior is now enabled by default, so calling this method is no longer necessary."

在修复了任何生成错误或警告后,可以对应用程序进行更改,以利用新功能(如果愿意)。Once you've fixed any build errors or warnings, you can make changes to your application to take advantage of new functionality if you wish. 有关 SDK 中的新功能的详细信息,请参阅版本 5 中的新增功能New features in the SDK are detailed in What's new in version 5.

版本 5 中的重大更改Breaking changes in version 5

新的包结构New Package Structure

版本 5 中最本质的重大更改是 Microsoft.Azure.Search 程序集及其内容已被分成四个独立的程序集,现在以四个独立的 NuGet 包进行分发:The most substantial breaking change in version 5 is that the Microsoft.Azure.Search assembly and its contents have been divided into four separate assemblies that are now distributed as four separate NuGet packages:

  • Microsoft.Azure.Search:这是一个元数据包,其中包含所有其他 Azure 搜索包作为依赖项。Microsoft.Azure.Search: This is a meta-package that includes all the other Azure Search packages as dependencies. 如果从 SDK 的早期版本进行升级,只需升级此包,重新生成就可开始使用新版本。If you're upgrading from an earlier version of the SDK, simply upgrading this package and re-building should be enough to start using the new version.
  • Microsoft.Azure.Search.Data:如果使用 Azure 搜索开发 .NET 应用程序,则使用此包,并且只需查询或更新索引中的文档。Microsoft.Azure.Search.Data: Use this package if you're developing a .NET application using Azure Search, and you only need to query or update documents in your indexes. 如果还需要创建或更新索引、同义词映射或其他服务级资源,请改用 Microsoft.Azure.Search 包。If you also need to create or update indexes, synonym maps, or other service-level resources, use the Microsoft.Azure.Search package instead.
  • Microsoft.Azure.Search.Service:如果在 .NET 中开发自动化以管理 Azure 搜索索引、同义词映射、索引器、数据源或其他服务级资源,请使用此包。Microsoft.Azure.Search.Service: Use this package if you're developing automation in .NET to manage Azure Search indexes, synonym maps, indexers, data sources, or other service-level resources. 如果只需要查询或更新索引中的文档,请改用 Microsoft.Azure.Search.Data 包。If you only need to query or update documents in your indexes, use the Microsoft.Azure.Search.Data package instead. 如果需要 Azure 搜索的所有功能,请改用 Microsoft.Azure.Search 包。If you need all the functionality of Azure Search, use the Microsoft.Azure.Search package instead.
  • Microsoft.Azure.Search.Common:Azure 搜索 .NET 库需要的常见类型。Microsoft.Azure.Search.Common: Common types needed by the Azure Search .NET libraries. 不应在应用程序中直接使用此包;它只是用作依赖项。You should not need to use this package directly in your application; It is only meant to be used as a dependency.

由于许多类型在程序集之间移动,所以从技术上来说这是重大更改。This change is technically breaking since many types were moved between assemblies. 这就是为什么需要重新生成应用程序才能升级到 SDK 的版本 5。This is why rebuilding your application is necessary in order to upgrade to version 5 of the SDK.

除重新生成应用程序之外,版本 5 中只有少量可能需要更改代码的其他重大更改。There a small number of other breaking changes in version 5 that may require code changes in addition to rebuilding your application.

对建议器的更改Change to Suggesters

Suggester 构造函数不再为 SuggesterSearchMode 提供 enum 参数。The Suggester constructor no longer has an enum parameter for SuggesterSearchMode. 此枚举只有一个值,因此是多余的。This enum only had one value, and was therefore redundant. 如果因此看到生成错误,只需删除对 SuggesterSearchMode 参数的引用即可。If you see build errors as a result of this, simply remove references to the SuggesterSearchMode parameter.

删除了过时成员Removed obsolete members

可能会看到与更早版本中标记为已过时的方法或属性相关的生成错误,这些方法或属性随后已在版本 5 中删除。You may see build errors related to methods or properties that were marked as obsolete in earlier versions and subsequently removed in version 5. 如果遇到此类错误,可按下面所述解决它们:If you encounter such errors, here is how to resolve them:

  • 如果使用 IndexingParametersExtensions.IndexStorageMetadataOnly 方法,请改用 SetBlobExtractionMode(BlobExtractionMode.StorageMetadata)If you were using the IndexingParametersExtensions.IndexStorageMetadataOnly method, use SetBlobExtractionMode(BlobExtractionMode.StorageMetadata) instead.
  • 如果使用 IndexingParametersExtensions.SkipContent 方法,请改用 SetBlobExtractionMode(BlobExtractionMode.AllMetadata)If you were using the IndexingParametersExtensions.SkipContent method, use SetBlobExtractionMode(BlobExtractionMode.AllMetadata) instead.

删除了预览功能Removed preview features

如果要从版本 4.0-preview 升级到版本 5,请注意,JSON 数组和 CSV 对 Blob 索引器的分析支持已删除,因为这些功能仍处于预览状态。If you are upgrading from version 4.0-preview to version 5, be aware that JSON array and CSV parsing support for Blob Indexers has been removed since these features are still in preview. 具体而言,IndexingParametersExtensions 类的以下方法已删除:Specifically, the following methods of the IndexingParametersExtensions class have been removed:

  • ParseJsonArrays
  • ParseDelimitedTextFiles

如果应用程序硬依赖于这些功能,则将无法升级到 Azure 搜索 .NET SDK 的版本 5。If your application has a hard dependency on these features, you will not be able to upgrade to version 5 of the Azure Search .NET SDK. 可继续使用版本 4.0-preview。You can continue to use version 4.0-preview. 但是,请记住,我们不建议在生产应用程序中使用预览版 SDKHowever, please keep in mind that we do not recommend using preview SDKs in production applications. 预览功能仅用于评估,并且可能会更改。Preview features are for evaluation only and may change.

结束语Conclusion

如果需要有关如何使用 Azure 搜索 .NET SDK 的更多详细信息,请参阅 .NET 操作指南If you need more details on using the Azure Search .NET SDK, see the .NET How-to.

我们欢迎你对 SDK 提供反馈。We welcome your feedback on the SDK. 如果遇到问题,请随时通过 Stack Overflow 向我们寻求帮助。If you encounter problems, feel free to ask us for help on Stack Overflow. 如果找到 Bug,可以在 Azure .NET SDK GitHub 存储库中提出问题。If you find a bug, you can file an issue in the Azure .NET SDK GitHub repository. 务必在问题标题上加前缀“[Azure 搜索]”。Make sure to prefix your issue title with "[Azure Search]".

感谢使用 Azure 搜索!Thank you for using Azure Search!