升级到 Azure 认知搜索 .NET SDK 版本 10Upgrade to Azure Cognitive Search .NET SDK version 10

如果你使用的是 9.0 或更低版本的 Azure 搜索 .NET SDK,本文可帮助你升级应用程序,以使用版本 10。If you're using version 9.0 or older of the Azure Search .NET SDK, this article will help you upgrade your application to use version 10.

Azure 搜索在版本 10 中重命名为 Azure 认知搜索,但命名空间和包名不变。Azure Search is renamed to Azure Cognitive Search in version 10, but namespaces and package names are unchanged. 以前的 SDK 版本(9.0 及更低版本)仍使用以前的名称。Previous versions of the SDK (9.0 and earlier) continue to use the former name. 若要详细了解如何使用 SDK(包括示例),请参阅如何从 .NET 应用程序使用 Azure 认知搜索For more information about using the SDK, including examples, see How to use Azure Cognitive Search from a .NET Application.

版本 10 中增加了多项功能和 bug 修复,其功能级别与最新的 REST API 版本 2019-05-06 相同。Version 10 adds several features and bug fixes, bringing it to the same functional level as the most recent release of the REST API version 2019-05-06. 如果某项更改会中断现有的代码,我们将逐步引导你解决相关的问题In cases where a change breaks existing code, we'll walk you through the steps required to resolve the issue.


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

搜索服务实例支持多个 REST API 版本,包括最新的版本。Your 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.

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

Azure 认知搜索 .NET SDK 版本 10 面向 REST API 的最新正式版 (2019-05-06),其中包含以下更新:Version 10 of the Azure Cognitive Search .NET SDK targets the latest generally available version of the REST API (2019-05-06) with these updates:

升级步骤Steps to upgrade

  1. 按以下方式更新 Microsoft.Azure.Search 的 NuGet 引用:使用 NuGet 包管理器控制台,或者在 Visual Studio 中右键单击项目引用,然后选择“管理 NuGet 程序包...”。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.

  2. 在 NuGet 已下载新的程序包及其依赖项后,请重新生成项目。Once NuGet has downloaded the new packages and their dependencies, rebuild your project.

  3. 如果生成失败,则需要修复每个生成错误。If your build fails, you will need to fix each build error. 有关如何解决每个潜在生成错误的详细信息,请参阅版本 10 中的中断性变更See Breaking changes in version 10 for details on how to resolve each potential build error.

  4. 在修复了任何生成错误或警告后,可以对应用程序进行更改,以利用新功能(如果愿意)。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 中的新功能的详细信息,请参阅版本 10 中的新增功能New features in the SDK are detailed in What's new in version 10.

版本 10 中的中断性变更Breaking changes in version 10

除重新生成应用程序以外,版本 10 中还有几项可能需要更改代码的中断性变更。There are several breaking changes in version 10 that may require code changes in addition to rebuilding your application.


以下更改列表并不详尽。The list of changes below is not exhaustive. 某些更改可能不会导致生成错误,但在技术上是中断性的,因为它们会破坏与依赖于早期版本 Azure 认知搜索.NET SDK 程序集的程序集的二进制兼容性。Some changes will likely not result in build errors, but are technically breaking since they break binary compatibility with assemblies that depend on earlier versions of the Azure Cognitive Search .NET SDK assemblies. 属于此类别的重大更改也会随建议一起列出。Significant changes that fall under this category are also listed along with recommendations. 升级到版本 10 时请重新生成应用程序,以免出现任何二进制兼容性问题。Please rebuild your application when upgrading to version 10 to avoid any binary compatibility issues.

整形程序技能允许嵌套的上下文合并Shaper skill allows nested context consolidation

整形程序技能现在允许合并嵌套上下文中的输入。Shaper skill can now allow input consolidation from nested contexts. 为了实现此更改,我们修改了 InputFieldMappingEntry,这样,只需指定 Source 属性,或者同时指定 SourceContextInputs 属性,即可将其实例化。To enable this change, we modified InputFieldMappingEntry so that it can be instantiated by specifying just a Source property, or both the SourceContext and Inputs properties.

你很有可能不需要进行任何代码更改;但请注意,只允许这两种组合中的一种。You will most likely not need to make any code changes; however note that only one of these two combinations is allowed. 这意味着:This means:

  • 创建只初始化 SourceInputFieldMappingEntry 是有效操作。Creating an InputFieldMappingEntry where only Source is initialized is valid.
  • 创建只初始化 SourceContextInputsInputFieldMappingEntry 是有效操作。Creating an InputFieldMappingEntry where only SourceContext and Inputs are initialized is valid.
  • 涉及这三个属性的所有其他组合是无效的。All other combinations involving those three properties are invalid.

如果你决定开始利用此新功能,请确保在实施该更改之前,先将所有客户端更新为使用版本 10。If you decide to start making use of this new capability, make sure all your clients are updated to use version 10 first, before rolling out that change. 否则,客户端(使用较旧版本的 SDK)对整形程序技能做出的更新可能导致验证错误。Otherwise, there is a possibility that an update by a client (using an older version of the SDK) to the Shaper skill may result in validation errors.

有关错误和警告的详细信息Details about errors and warnings

ItemErrorItemWarning 模型(分别用于封装索引器执行期间发生的错误和警告的详细信息)已经过修改,现在包含三个旨在帮助调试索引器的新属性。ItemError and ItemWarning models that encapsulate details of errors and warnings (respectively) that occur during an indexer execution have been modified to include three new properties with the objective to aid in debugging the indexer. 这些属性为:These properties are:

  • Name:错误来源的名称。Name: The name of the source at which the error originated.
  • Details:有关错误或警告的其他详细信息。Details: Additional verbose details about the error or warning.
  • DocumentationLink:针对具体错误或警告的故障排除指南的链接。DocumentationLink: A link to a troubleshooting guide for the specific error or warning.


我们已开始组织错误和警告的内容,以尽可能地包含这些有用的信息。We have started to structure our errors and warnings to include these useful details whenever possible. 我们正努力确保在所有错误和警告中提供这些详细信息,但这项工作正在进行,并且不一定总会填充这些附加的详细信息。We are working to make sure that for all errors and warnings these details are present, but it is a work in progress and these additional details may not always be populated.

后续步骤Next steps

  • 我们欢迎你对 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 Cognitive Search]".