升级到 Azure 认知搜索 .NET SDK 版本 10

如果你使用的是 9.0 或更低版本的 .NET SDK，本文可帮助你升级应用程序，以使用版本 10。

Azure 搜索在版本 10 中重命名为 Azure 认知搜索，但命名空间和包名不变。 以前的 SDK 版本（9.0 及更低版本）仍使用以前的名称。 若要详细了解如何使用 SDK（包括示例），请参阅如何从 .NET 应用程序使用 Azure 认知搜索。

版本 10 中增加了多项功能和 bug 修复，使其功能级别与 REST API 版本 2019-05-06 相同。 如果某项更改会中断现有的代码，我们将逐步引导你解决相关的问题。

备注

如果你使用的是版本 8.0-preview 或更低版本，应先升级到版本 9，再升级到版本 10。 有关说明，请参阅升级到 Azure 搜索 .NET SDK 版本 9。

搜索服务实例支持多个 REST API 版本，包括最新的版本。 可以不使用最新版本，但是我们建议迁移代码，以便使用最新版本。 使用 REST API 时，必须在每个请求中通过 api-version 参数指定 API 版本。 使用 .NET SDK 时，使用的 SDK 版本确定对应的 REST API 版本。 如果使用较旧的 SDK，即使已升级服务以支持较新的 API 版本，也可以继续运行代码，而不进行任何更改。

版本 10 中的新增功能

Azure 认知搜索 .NET SDK 版本 10 面向 REST API 2019-05-06，其中包含以下更新：

升级步骤

  1. 按以下方式更新 Microsoft.Azure.Search 的 NuGet 引用：使用 NuGet 包管理器控制台，或者在 Visual Studio 中右键单击项目引用，然后选择“管理 NuGet 程序包...”。

  2. 在 NuGet 已下载新的程序包及其依赖项后，请重新生成项目。

  3. 如果生成失败，则需要修复每个生成错误。 有关如何解决每个潜在生成错误的详细信息，请参阅版本 10 中的中断性变更。

  4. 在修复了任何生成错误或警告后，可以对应用程序进行更改，以利用新功能（如果愿意）。 有关 SDK 中的新功能的详细信息，请参阅版本 10 中的新增功能。

版本 10 中的中断性变更

除重新生成应用程序以外，版本 10 中还有几项可能需要更改代码的中断性变更。

备注

以下更改列表并不详尽。 某些更改可能不会导致生成错误，但在技术上是中断性的，因为它们会破坏与依赖于早期版本 Azure 认知搜索.NET SDK 程序集的程序集的二进制兼容性。 属于此类别的重大更改也会随建议一起列出。 升级到版本 10 时请重新生成应用程序，以免出现任何二进制兼容性问题。

自定义 Web API 技能定义

版本 9 和更低版本中错误地指定了自定义 Web API 技能的定义。

WebApiSkill 的模型将 HttpHeaders 指定为包含字典的对象属性。 以这种方式创建带有 WebApiSkill 构造的技能集会导致异常，因为 REST API 会将请求视为格式不当。 此问题已得到更正，HttpHeaders 现在会设置为 WebApiSkill 模型本身上的顶级字典属性 - 请求被视为来自 REST API 的有效请求。

例如，如果你以前尝试按如下所示实例化 WebApiSkill：


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

将它更改为以下代码可以避免 REST API 出现验证错误：


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

整形程序技能允许嵌套的上下文合并

整形程序技能现在允许合并嵌套上下文中的输入。 为了实现此更改，我们修改了 InputFieldMappingEntry，这样，只需指定 Source 属性，或者同时指定 SourceContext 和 Inputs 属性，即可将其实例化。

你很有可能不需要进行任何代码更改；但请注意，只允许这两种组合中的一种。 这意味着：

  • 创建只初始化 Source 的 InputFieldMappingEntry 是有效操作。
  • 创建只初始化 SourceContext 和 Inputs 的 InputFieldMappingEntry 是有效操作。
  • 涉及这三个属性的所有其他组合是无效的。

如果你决定开始利用此新功能，请确保在实施该更改之前，先将所有客户端更新为使用版本 10。 否则，客户端（使用较旧版本的 SDK）对整形程序技能做出的更新可能导致验证错误。

备注

即使已将底层 InputFieldMappingEntry 模型修改为允许从嵌套上下文合并，但只能在整形程序技能的定义内使用该模型。 在其他技能中使用此功能会在运行时导致验证错误（尽管在编译时是正常的）。

可以按名称识别技能

技能集中的每个技能现在包含一个新属性 Name，可以在代码中初始化该属性，以帮助识别该技能。 这是可选的操作 - 如果未指定（如果未进行显式代码更改，则默认不会指定），将使用技能集中技能的从 1 开始的索引，为该技能分配一个带有“#”前缀字符的默认名称。 例如，在以下技能集定义中（对简洁起见，已跳过大部分初始化步骤）：

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

为 SentimentSkill 分配了名称 #1，为 WebApiSkill 分配了名称 #2，为 ShaperSkill 分配了名称 #3，依此类推。

如果选择按自定义名称识别技能，请务必先将客户端的所有实例更新到 SDK 版本 10。 否则，可能会出现这种问题：使用较旧 SDK 版本的客户端将技能的 Name 属性设置为 null，从而导致客户端回退到默认命名方案。

有关错误和警告的详细信息

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

  • Name：错误来源的名称。 例如，错误中可能会提到附加的技能集中的特定技能。
  • Details：有关错误或警告的其他详细信息。
  • DocumentationLink：针对具体错误或警告的故障排除指南的链接。

备注

我们已开始组织错误和警告的内容，以尽可能地包含这些有用的信息。 我们正努力确保在所有错误和警告中提供这些详细信息，但这项工作正在进行，并且不一定总会填充这些附加的详细信息。

后续步骤