升级到 Azure AI 搜索 .NET SDK 版本 11

如果搜索解决方案基于 Azure SDK for .NET 构建，则本文将帮助你将代码从早期版本的 Microsoft.Azure.Search 迁移到版本 11（新 Azure.Search.Documents 客户端库）。 版本 11 是完全重新设计的客户端库，由 Azure SDK 开发团队发布（以前的版本由 Azure AI Searchdevelopment 团队制作）。

版本 10 中的所有功能都会在版本 11 中实现。 关键不同点包括：

• 一个程序包 (Azure.Search.Documents)，而不是四个
• 三个客户端而不是两个客户端：SearchClient、SearchIndexClient、SearchIndexerClient
• 一系列 API 的命名差异，以及简化了某些任务的小的结构差异

客户端库的更改日志包含更新的项化列表。 可在本文中查看汇总的版本。

Azure AI 搜索产品文档中的所有 C# 代码示例和代码片段已修改为使用新的Azure.Search.Documents 客户端库。

为什么升级？

升级的好处总结如下：

• 新功能仅添加到 Azure.Search.Documents。 以前的版本 Microsoft.Azure.Search 现已停用。 对已弃用的库的更新仅限于高优先级 bug 修复。

• 与其他 Azure 客户端库一致。 Azure.Search.Documents 依赖于 Azure.Core 和 System.Text.Json，并遵循常见任务（如客户端连接和授权）的传统方法。

Microsoft.Azure.Search 已正式退役。 如果使用旧版本，我们建议升级到下一个更高版本，连续重复该过程，直到达到版本 11 和 Azure.Search.Documents。 增量升级策略可更轻松地查找和修复阻塞问题。 有关指导，请参阅以前的版本文档。

包比较

版本 11 合并并简化了包管理，以便减少要管理的数量。

版本 10 及早期版本	版本 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Azure.Search.Documents 包

客户端比较

下表映射了两个版本的客户端库（适用情况下）。

客户端操作	Microsoft.Azure.Search (v10)	Azure.Search.Documents (v11)
面向索引的文档集合（查询和数据导入）	SearchIndexClient	SearchClient
面向索引相关的对象（索引、分析器、同义词映射	SearchServiceClient	SearchIndexClient
面向索引器相关的对象（索引器、数据源、技能组）	SearchServiceClient	SearchIndexerClient（新增）

命名和其他 API 差异

除了客户端差异以外（前面已提到，因此在此处省略），还重命名了多个其他 API，在某些情况下对其进行了重新设计。 下面几节汇总了类名的差异。 此列表并非详尽无遗，但它确实按任务将 API 更改进行了分组，这对于特定代码块的修订很有帮助。 有关 API 更新的详细列表，请参阅 GitHub 上 Azure.Search.Documents 的更改日志。

身份验证和加密

版本 10	版本 11 等效项
SearchCredentials	AzureKeyCredential
EncryptionKey（未记录在 API 参考中。对此 API 的支持在 v10 中已转换为正式版，但仅在预览 SDK 中可用）	SearchResourceEncryptionKey

索引、分析器、同义词映射

版本 10	版本 11 等效项
Index	SearchIndex
字段	SearchField
DataType	SearchFieldDataType
ItemError	SearchIndexerError
Analyzer	LexicalAnalyzer（另外，AnalyzerName 对应于 LexicalAnalyzerName）
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer（另外，StandardTokenizerV2 对应于 LuceneStandardTokenizerV2）
TokenInfo	AnalyzedTokenInfo
分词器	LexicalTokenizer（另外，TokenizerName 对应于 LexicalTokenizerName）
SynonymMap.Format	无。 删除了对 Format 的引用。

简化了字段定义：SearchableField、SimpleField、ComplexField 是用于创建字段定义的新 API。

索引器、数据源、技能组

版本 10	版本 11 等效项
索引器	SearchIndexer
DataSource	SearchIndexerDataSourceConnection
Skill	SearchIndexerSkill
技能集	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

数据导入

版本 10	版本 11 等效项
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

查询请求和响应

版本 10	版本 11 等效项
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult 或 SearchResults，具体取决于结果是单个文档还是多个文档。
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter（构造 OData 筛选器表达式的新类）

JSON 序列化

默认情况下，Azure SDK 使用 System.Text.Json 进行 JSON 序列化，依赖这些 API 的功能来处理以前通过原生 SerializePropertyNamesAsCamelCaseAttribute 类实现的文本转换，该类在新库中没有对应的类。

若要将属性名称序列化为 camelCase，可以使用 JsonPropertyNameAttribute（类似于此示例）。

另外，你还可以设置 JsonSerializerOptions 中提供的 JsonNamingPolicy。 下面的 System.Text.Json 代码示例摘自 Microsoft.Azure.Core.Spatial 自述文件，它演示了如何使用 camelCase，无需将每个属性特性化：

// Get the Azure AI Search service endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

如果使用 Newtonsoft.Json 进行 JSON 序列化，则可以通过使用类似的特性或通过使用 JsonSerializerSettings 上的属性来传入全局命名策略。 有关与上一个示例等效的示例，请参阅 Newtonsoft.Json 自述文件中的反序列化文档示例。

v11 内

Azure AI 搜索客户端库的每个版本都面向 REST API 的一个对应版本。 REST API 被视为服务的基础，而各个 SDK 用于包装 REST API 的版本。 作为 .NET 开发人员，查看更详细的 REST API 文档可以帮助更深入地了解特定对象或操作。 版本 11 对应于 2020-06-30 搜索服务规范。

版本 11.0 完全支持以下对象和操作：

• 索引创建和管理
• 同义词映射创建和管理
• 索引器创建和管理
• 索引器数据源创建和管理
• 技能组创建和管理
• 所有查询类型和语法

版本 11.1 附加内容（更改日志详细信息）：

• FieldBuilder（在 11.1 中添加）
• 序列化程序属性（在 11.1 中添加），用于支持自定义序列化

版本 11.2 附加内容（更改日志详细信息）：

• EncryptionKey 属性已添加索引器、数据源和技能组

• IndexingParameters.IndexingParametersConfiguration 属性支持

• FieldBuilder 本机支持地理空间类型。 SearchFilter 可以在没有显式程序集依赖项的情况下编码来自 Azure.Spatial 的几何类型。

  还可以继续显式声明对 Microsoft.Spatial 的依赖关系。 此方法示例可用于 System.Text.Json 和 Newtonsoft.Json。

版本 11.3 附加内容（更改日志详细信息）：

• KnowledgeStore
• 添加了对 SearchDocument、SearchFilter 和 FieldBuilder 中的 Azure.Core.GeoJson 类型的支持。
• 添加了基于 EventSource 的日志记录。 事件源名称为 Azure-Search-Documents。 当前的事件集侧重于优化 SearchIndexingBufferedSender 的批大小。
• 添加了 CustomEntityLookupSkill 和 DocumentExtractionSkill。 在 LanguageDetectionSkill 中添加了 DefaultCountryHint。

升级前

• 已更新快速入门、教程和 C# 示例，以使用 Azure.Search.Documents 包。 建议在开始迁移练习之前先查看示例和演练，以了解新 API。

• 如何使用 Azure.Search.Documents 介绍了最常使用的 API。 即使是 Azure AI 搜索的知识丰富的用户，也可能希望在迁移之前查看此新库简介。

升级步骤

以下步骤通过遍历第一组必需任务（特别是在客户端引用方面）开始执行代码迁移。

1. 在 Visual Studio 中，右键单击你的项目引用并选择“管理 NuGet 包...”，以安装 Azure.Search.Documents 包。

2. 将用于 Microsoft.Azure.Search 的 using 指令替换为以下 using 语句：

   using Azure;
   using Azure.Search.Documents;
   using Azure.Search.Documents.Indexes;
   using Azure.Search.Documents.Indexes.Models;
   using Azure.Search.Documents.Models;
   

3. 对于需要 JSON 序列化的类，请将 using Newtonsoft.Json 替换为 using System.Text.Json.Serialization。

4. 修订客户端身份验证代码。 在以前的版本中，你会使用客户端对象上的属性（例如，SearchServiceClient.Credentials 属性）设置 API 密钥。 在当前版本中，请使用 AzureKeyCredential 类将密钥作为凭据传递，以便在需要时可以更新 API 密钥，而无需创建新的客户端对象。

   客户端属性已精简，仅剩 Endpoint、ServiceName 和 IndexName（如果适用）。 下面的示例使用系统 Uri 类提供终结点，并使用 Environment 类来读取密钥值：

   Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
   AzureKeyCredential credential = new AzureKeyCredential(
      Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
   SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
   

5. 为索引器相关对象添加新的客户端引用。 如果使用的是索引器、数据源或技能组，请将客户端引用更改为 SearchIndexerClient。 此客户端是版本 11 中的新客户端，之前没有。

6. 请修改集合和列表。 在新的 SDK 中，所有列表都是只读的，这是为了避免在列表刚好包含 NULL 值时出现下游问题。 代码更改是为了向列表中添加项。 例如，可以按如下所示添加字符串，而不是为 Select 属性指定字符串：

   var options = new SearchOptions
    {
       SearchMode = SearchMode.All,
       IncludeTotalCount = true
    };
   
    // Select fields to return in results.
    options.Select.Add("HotelName");
    options.Select.Add("Description");
    options.Select.Add("Tags");
    options.Select.Add("Rooms");
    options.Select.Add("Rating");
    options.Select.Add("LastRenovationDate");
   

   Select、Facets、SearchFields、SourceFields、ScoringParameters 和 OrderBy 都是现在需要重新构造的列表。

7. 为查询和数据导入更新客户端引用。 应将 SearchIndexClient 的实例更改为 SearchClient。 为了避免名称混乱，请确保在继续下一步之前捕获所有实例。

8. 为索引、同义词映射和分析器对象更新客户端引用。 应将 SearchServiceClient 的实例更改为 SearchIndexClient。

9. 对于你的代码的剩余部分，请更新类、方法和属性以使用新库的 API。 可以从命名差异部分来开始了解，但也可以查看更改日志。

   如果在查找等效 API 时遇到困难，建议你在 https://github.com/MicrosoftDocs/azure-docs/issues 上记录问题，以便我们可以改进文档或调查问题。

10. 重新生成解决方案。 在修复了任何生成错误或警告后，可以对应用程序进行其他更改，以利用新功能。

中断性变更

考虑到对库和 API 的全面更改，升级到版本 11 是一项重大升级，你的代码将不再后向兼容版本 10 及更低版本。从这个意义上说，这是一项中断性变更。 若要全面了解差异，请参阅 Azure.Search.Documents 的更改日志。

就服务版本更新而言，版本 11 中的代码更改与现有功能（而不仅仅是 API 重构）相关，你会发现以下行为更改：

• BM25 排名算法将以前的排名算法替换为更新的技术。 新服务自动使用此算法。 对于现有服务，必须将参数设置为使用新算法。

• 在此版本中，NULL 值的排序结果发生了变化，如果排序是 asc，则 NULL 值首先出现；如果排序是 desc，则 NULL 值最后出现。 如果你编写了代码来处理如何对 NULL 值排序，则应查看该代码并可在不再需要时将其删除。

由于这些行为变更，你可能会在排名结果中看到轻微的变化。

后续步骤

• 如何在 C# .NET 应用程序中使用 Azure.Search.Documents
• 教程：向 Web 应用添加搜索
• Azure.Search.Documents 包
• GitHub 上的示例
• Azure.Search.Document API 参考