升级到 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.

Note

如果你使用的是版本 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.

Note

以下更改列表并不详尽。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.

自定义 Web API 技能定义Custom Web API skill definition

版本 9 和更低版本中错误地指定了自定义 Web API 技能的定义。The definition of the Custom Web API skill was incorrectly specified in version 9 and older.

WebApiSkill 的模型将 HttpHeaders 指定为包含字典的对象属性。 The model for WebApiSkill specified HttpHeaders as an object property that contains a dictionary. 以这种方式创建带有 WebApiSkill 构造的技能集会导致异常,因为 REST API 会将请求视为格式不当。Creating a skillset with a WebApiSkill constructed in this manner would result in an exception because the REST API would consider the request badly formed. 此问题已得到更正,HttpHeaders 现在会设置为 WebApiSkill 模型本身上的顶级字典属性 - 请求被视为来自 REST API 的有效请求。This issue has been corrected, by making HttpHeaders a top-level dictionary property on the WebApiSkill model itself - which is considered a valid request from the REST API.

例如,如果你以前尝试按如下所示实例化 WebApiSkillFor example, if you previously attempted to instantiate a WebApiSkill as follows:


var webApiSkill = new WebApiSkill(
            inputs, 
            outputs,
            uri: "https://contoso.example.org")
{
    HttpHeaders = new WebApiHttpHeaders()
    {
        Headers = new Dictionary<string, string>()
        {
            ["header"] = "value"
        }
    }
};

将它更改为以下代码可以避免 REST API 出现验证错误:change it to the following, to avoid the validation error from the REST API:


var webApiSkill = new WebApiSkill(
            inputs, 
            outputs,
            uri: "https://contoso.example.org")
{
    HttpHeaders = new Dictionary<string, string>()
    {
        ["header"] = "value"
    }
};

整形程序技能允许嵌套的上下文合并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.

Note

即使已将底层 InputFieldMappingEntry 模型修改为允许从嵌套上下文合并,但只能在整形程序技能的定义内使用该模型。Even though the underlying InputFieldMappingEntry model has been modified to allow consolidation from nested contexts, it's use is only valid within the definition of a Shaper skill. 在其他技能中使用此功能会在运行时导致验证错误(尽管在编译时是正常的)。Using this capability in other skills, while valid at compile time, will result in a validation error at runtime.

可以按名称识别技能Skills can be identified by a name

技能集中的每个技能现在包含一个新属性 Name,可以在代码中初始化该属性,以帮助识别该技能。Each skill within a skillset now has a new property Name, which can be initialized in your code to help identify the skill. 这是可选的操作 - 如果未指定(如果未进行显式代码更改,则默认不会指定),将使用技能集中技能的从 1 开始的索引,为该技能分配一个带有“#”前缀字符的默认名称。This is optional - when unspecified (which is the default, if no explicit code change was made), it is assigned a default name using the 1-based index of the skill in the skillset, prefixed with the '#' character. 例如,在以下技能集定义中(对简洁起见,已跳过大部分初始化步骤):For example, in the following skillset definition (most initializations skipped for brevity):

var skillset = new Skillset()
{
    Skills = new List<Skill>()
    {
        new SentimentSkill(),
        new WebApiSkill(),
        new ShaperSkill(),
        ...
    }
}

SentimentSkill 分配了名称 #1,为 WebApiSkill 分配了名称 #2,为 ShaperSkill 分配了名称 #3,依此类推。SentimentSkill is assigned a name #1, WebApiSkill is assigned #2, ShaperSkill is assigned #3 and so on.

如果选择按自定义名称识别技能,请务必先将客户端的所有实例更新到 SDK 版本 10。If you choose to identify skills by a custom name, make sure to update all instances of your clients to version 10 of the SDK first. 否则,可能会出现这种问题:使用较旧 SDK 版本的客户端将技能的 Name 属性设置为 null,从而导致客户端回退到默认命名方案。Otherwise, there is a possibility that a client using an older version of the SDK could null out the Name property of a skill, causing the client to fall back on the default naming scheme.

有关错误和警告的详细信息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. 例如,错误中可能会提到附加的技能集中的特定技能。For example, it could refer to a particular skill in the attached skillset.
  • Details:有关错误或警告的其他详细信息。Details: Additional verbose details about the error or warning.
  • DocumentationLink:针对具体错误或警告的故障排除指南的链接。DocumentationLink: A link to a troubleshooting guide for the specific error or warning.

Note

我们已开始组织错误和警告的内容,以尽可能地包含这些有用的信息。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