升级到 Azure 搜索 .NET SDK 版本 9

2021-09-16

如果使用的是版本 7.0-preview 或更高版本的 Azure 搜索 .NET SDK，本文将帮助你升级应用程序以使用版本 9。

注释

如果要使用版本 8.0-preview 评估尚未正式发布的功能，还可以按照本文中的说明从以前的版本升级到 8.0-preview。

有关 SDK 的更常规演练，包括示例，请参阅如何通过 .NET 应用程序使用 Azure 搜索。

Azure 搜索 .NET SDK 版本 9 包含早期版本中的许多更改。其中一些是破坏性变更，但它们只需对代码进行相对轻微的修改。有关如何更改代码以使用新 SDK 版本的说明，请参阅升级步骤。

注释

如果使用的是版本 4.0-preview 或更早版本，则应先升级到版本 5，然后再升级到版本 9。有关说明，请参阅升级到 Azure 搜索 .NET SDK 版本 5 。

Azure 搜索服务实例支持多个 REST API 版本，包括最新的版本。当版本不再是最新版本时，可以继续使用版本，但我们建议迁移代码以使用最新版本。使用 REST API 时，必须通过 API 版本参数在每个请求中指定 API 版本。使用 .NET SDK 时，所使用的 SDK 版本决定了 REST API 的相应版本。如果使用较旧的 SDK，即使服务已升级以支持较新的 API 版本，也可以继续运行该代码，且不会发生任何更改。

版本 9 中的新增功能

Azure 搜索 .NET SDK 版本 9 面向 2019-05-06 版本的 Azure 搜索 REST API，具有以下功能：

AI 扩充是能够从图像、Blob 和其他非结构化数据源中提取文本 - 扩充内容，使其在 Azure 搜索索引中更具可搜索性。
支持复杂类型允许在 Azure 搜索索引中对几乎任何嵌套 JSON 结构建模。
自动完成提供了建议 API 的替代方案，用于实现“边输入边搜索”功能。自动完成“完成”用户当前键入的单词或短语。
JsonLines 分析模式（Blob 索引的一部分）为每个 JSON 实体创建一个搜索文档，该文档由换行符分隔。

版本 8.0-preview 中的新预览功能

Azure 搜索 .NET SDK 的 8.0 预览版本针对 API 版本 2017-11-11 的预览版。此版本包括版本 9 的所有相同功能，以及：

用于服务端静态加密的客户管理的加密密钥是一项新的预览功能。除了由Microsoft管理的内置静态加密外，还可以应用额外的加密层，其中你是密钥的唯一所有者。

升级步骤

首先，在 Visual Studio 中，更新项目中的 Microsoft.Azure.Search 的 NuGet 引用，可以通过使用 NuGet 包管理器控制台，或者右键单击项目中的引用并选择“管理 NuGet 包...” 。

NuGet 下载新包及其依赖项后，请重新生成项目。根据代码的结构，它可能会成功重建。如果是这样，你就可以上路了！

如果生成失败，则需要修复每个生成错误。请查看版本 9 的重大更改，以了解如何解决每个潜在的构建错误的详细信息。

你可能会看到与过时的方法或属性相关的其他编译警告。这些警告将包含有关如何使用的说明，而不是弃用的功能。例如，如果应用程序使用该 DataSourceType.DocumentDb 属性，则应收到一条警告，指出“此成员已弃用。请改用 CosmosDb。

修复任何生成错误或警告后，可以更改应用程序以利用新功能（如果需要）。 SDK 中的新功能详见版本 9 中的新增功能。

版本 9 中的重大更改

版本 9 中有几个重大更改，除了重新构建应用程序外，还可能需要更改代码。

注释

下面的更改列表并不详尽。某些更改可能不会导致生成错误，但在技术上会引起不兼容，因为它们破坏了与依赖于较早版本的 Azure 搜索 .NET SDK 程序集的二进制兼容性。下面未列出此类更改。请在升级到版本 9 时重新生成应用程序，以避免任何二进制兼容性问题。

不可变属性

多个模型类的公共属性现在不可变。如果需要创建自定义类的实例进行测试，可以使用新的参数化构造函数：

AutocompleteItem
DocumentSearchResult
DocumentSuggestResult
FacetResult
SearchResult
SuggestResult

对字段的更改

类 Field 现已更改，它还可以表示复杂字段。

以下 bool 属性现在可为 null：

IsFilterable
IsFacetable
IsSearchable
IsSortable
IsRetrievable
IsKey

这是因为在复杂字段的情况下，这些属性现在必须是null。如果你有读取这些属性的代码，则必须准备好处理 null。请注意，Field 的所有其他属性一直以来都是可空的，并且仍将如此，而在复杂字段的情况下，其中一些属性也会表现为 null，具体如下：

Analyzer
SearchAnalyzer
IndexAnalyzer
SynonymMaps

无参数构造函数Field已变为internal。从现在起，每次 Field 构造时都需要显式名称和数据类型。

简化的批处理和结果类型

在版本 7.0-preview 及更早版本中，封装文档组的各种类结构化为并行类层次结构：

DocumentSearchResult 和 DocumentSearchResult<T> 继承自 DocumentSearchResultBase
DocumentSuggestResult 和 DocumentSuggestResult<T> 继承自 DocumentSuggestResultBase
IndexAction 和 IndexAction<T> 继承自 IndexActionBase
IndexBatch 和 IndexBatch<T> 继承自 IndexBatchBase
SearchResult 和 SearchResult<T> 继承自 SearchResultBase
SuggestResult 和 SuggestResult<T> 继承自 SuggestResultBase

没有泛型类型参数的派生类型旨在用于“动态类型化场景”，并假定使用Document类型。

从版本 8.0 开始，已删除基类和非泛型派生类。对于动态类型化方案，可以使用 IndexBatch<Document>， DocumentSearchResult<Document>等等。

已删除 ExtensibleEnum

ExtensibleEnum已删除基类。从它派生的所有类现在都是结构，例如 AnalyzerName， DataType例如 DataSourceType 。他们 Create 的方法也已被删除。只需删除对 Create 的调用，因为这些类型可以从字符串隐式转换。如果这导致编译器错误，您可以通过强制转换显式调用转换运算符，以消除类型歧义。例如，可以更改如下所示的代码：

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", AnalyzerName.Create("my_email_analyzer")) { IsSearchable = true }
    },
    ...
}

更改为：

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", (AnalyzerName)"my_email_analyzer") { IsSearchable = true }
    },
    ...
}

为了保持可选性，保存这些类型可选值的属性现在被显式定义为可空类型。

已删除 FacetResults 和 HitHighlights

FacetResults类和HitHighlights类已被删除。分面结果现在被标记为IDictionary<string, IList<FacetResult>>，命中突出显示为IDictionary<string, IList<string>>。解决此更改引入的生成错误的快速方法是在使用已删除类型的每个文件的顶部添加 using 别名。例如：

using FacetResults = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<Models.FacetResult>>;
using HitHighlights = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<string>>;

更改为 SynonymMap

构造函数SynonymMap不再具有enum参数SynonymMapFormat。此枚举只有一个值，因此是冗余的。如果由于此原因而看到生成错误，只需删除对参数的 SynonymMapFormat 引用。

其他模型类更改

属性AutocompleteModeAutocompleteParameters不再可为 null。如果有将此属性 null分配给的代码，只需将其删除，该属性将自动初始化为默认值。

现在，由于该构造函数是自动生成的，其参数顺序 IndexAction 已发生更改。建议使用工厂方法IndexAction.UploadIndexAction.Merge等，而不是使用构造函数。

已删除预览功能

如果要从版本 8.0-preview 升级到版本 9，请注意，已删除使用客户管理的密钥进行加密，因为此功能仍处于预览状态。具体而言，已删除Index和SynonymMap的EncryptionKey属性。

如果应用程序对此功能有硬依赖关系，则无法升级到 Azure 搜索 .NET SDK 版本 9。可以继续使用版本 8.0-preview。但是，请记住，我们不建议在生产环境的应用程序中使用预览版 SDK。预览功能仅用于评估，可能会更改。

注释

如果使用 SDK 版本 8.0 预览版创建了加密索引或同义词映射，仍可使用它们并使用 SDK 版本 9 修改其定义，而不会对其加密状态产生不利影响。 SDK 版本 9 不会将 encryptionKey 属性发送到 REST API，因此 REST API 不会更改资源的加密状态。

数据检索中的行为更改

如果您正在使用返回Document实例的“动态类型化”Search、Suggest或Get API，请注意，它们现在将空的 JSON 数组反序列化为object[]而不是string[]。

结论

如果需要有关使用 Azure 搜索 .NET SDK 的更多详细信息，请参阅 .NET作说明。

欢迎你对 SDK 的反馈。如果遇到问题，请随时请求我们在 Stack Overflow 上寻求帮助。如果发现 bug，可以在 Azure .NET SDK GitHub 存储库中提出问题。请确保在问题标题前添加“[Azure Search]”前缀。

感谢你使用 Azure 搜索！

通过