通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

  • 项目

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

版本 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（新增）

注意

请注意，SearchIndexClient 存在于这两个版本中，但针对不同的操作。 在版本 10 中，SearchIndexClient 创建索引和其他对象。 在版本 11 中，SearchIndexClient 适用于现有索引，以具有查询和数据输入 API 的文档集合为目标。 为了避免在更新代码时产生混淆，请注意更新客户端引用时的顺序。 按照升级步骤中的顺序进行操作应当有助于缓解任何字符串替换问题。

命名和其他 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 附加内容（更改日志详细信息）：

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

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

升级前

  • 已更新快速入门、教程和 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 值排序，则应查看该代码并可在不再需要时将其删除。

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

后续步骤