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

• 09/10/2020
• • a
  • v

如果你使用的是 9.0 或更低版本的 .NET SDK，本文可帮助你升级应用程序，以使用版本 10。If you're using version 9.0 or older of the .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 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.

版本 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 REST API 2019-05-06 with these updates:

• 引入了两项新技能 - 条件技能和文本翻译技能。Introduction of two new skills - Conditional skill and Text Translation skill.
• 重新组织了整形程序技能输入的结构，以适应嵌套上下文的合并。Shaper skill inputs have been restructured to accommodate consolidation from nested contexts. 有关详细信息，请参阅此示例 JSON 定义。For more information, see this example JSON definition.
• 添加了两个新的字段映射函数：Addition of two new field mapping functions:
  • urlEncodeurlEncode
  • urlDecodeurlDecode
• 在某些情况下，索引器执行状态中显示的错误和警告可以提供有助于调试的更多详细信息。On certain occasions, errors and warnings that show up in indexer execution status can have additional details that help in debugging. IndexerExecutionResult 已更新，以反映此行为。IndexerExecutionResult has been updated to reflect this behavior.
• 可以选择性地通过指定 name 属性来识别技能集中定义的单个技能。Individual skills defined within a skillset can optionally be identified by specifying a name property.
• ServiceLimits 显示复杂类型的限制，IndexerExecutionInfo 显示相关的索引器限制/配额。ServiceLimits shows limits for complex types and IndexerExecutionInfo shows pertinent indexer limits/quotas.

升级步骤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.

自定义 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.

例如，如果你以前尝试按如下所示实例化 WebApiSkill：For 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 属性，或者同时指定 SourceContext 和 Inputs 属性，即可将其实例化。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:

• 创建只初始化 Source 的 InputFieldMappingEntry 是有效操作。Creating an InputFieldMappingEntry where only Source is initialized is valid.
• 创建只初始化 SourceContext 和 Inputs 的 InputFieldMappingEntry 是有效操作。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.

可以按名称识别技能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

ItemError 和 ItemWarning 模型（分别用于封装索引器执行期间发生的错误和警告的详细信息）已经过修改，现在包含三个旨在帮助调试索引器的新属性。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.

后续步骤Next steps

• 更改整形程序技能很有可能会对新代码或现有代码造成影响。Changes to the Shaper skill have the most potential impact on new or existing code. 接下来，请务必重新访问这个演示输入结构的示例：整形程序技能 JSON 定义示例As a next step, be sure to revisit this example illustrating the input structure: Shaper skill JSON definition example
• 浏览 AI 扩充概述。Go through the AI enrichment overview.
• 我们欢迎你对 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]".