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

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

要获得有关 SDK 的更全面的演练，包括示例，可以参阅 #B0 从 .NET 应用程序中使用 Azure 搜索的方法 #A1。

Azure 搜索 .NET SDK 版本 3 包含早期版本中的一些更改。这些大多是次要的，因此更改代码只需要最少的努力。请参阅升级步骤，以获取将代码更改为使用新 SDK 版本的说明。

注释

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

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

版本 3 中的新增功能

Azure Search .NET SDK 的第 3 版针对的是 Azure Search REST API 的最新一般可用版本，特别是 2016-09-01 版本。这样，就可以从 .NET 应用程序使用 Azure 搜索的许多新功能，包括：

自定义分析器
Azure Blob 存储和Azure 表存储的索引器支持
通过字段映射进行索引器自定义
启用 ETag 的支持，以便安全地并发更新索引定义、索引器和数据源
支持通过修饰模型类并使用新的 FieldBuilder 类，以声明方式生成索引字段定义。
支持 .NET Core 和 .NET 可移植配置文件 111

升级步骤

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

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

如果生成失败，应会看到生成错误，如下所示：

Program.cs(31,45,31,86): error CS0266: Cannot implicitly convert type 'Microsoft.Azure.Search.ISearchIndexClient' to 'Microsoft.Azure.Search.SearchIndexClient'. An explicit conversion exists (are you missing a cast?)

下一步是修复此生成错误。有关导致错误的原因以及如何修复此错误的详细信息，请参阅版本 3 中的重大更改。

你可能会看到与过时的方法或属性相关的其他编译警告。这些警告将包含有关如何使用的说明，而不是弃用的功能。例如，如果应用程序使用该 IndexingParameters.Base64EncodeKeys 属性，则应收到一条警告，指出 "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead."

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

版本 3 中的重大变更

在版本 3 中，有少量的重大变更，除了重新生成应用程序，可能还需要更改代码。

Indexes.GetClient 返回类型

该方法 Indexes.GetClient 具有新的返回类型。以前，它返回SearchIndexClient，但在版本 2.0-preview 中更改为ISearchIndexClient，该更改将延续到版本 3。这是为了支持希望通过返回 GetClient 的模拟实现来模拟 ISearchIndexClient 方法进行单元测试的客户。

示例

如果代码如下所示：

SearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

可以将其更改为这样以修复任何构建错误：

ISearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

AnalyzerName、DataType 等不再隐式转换为字符串

Azure 搜索 .NET SDK 中有许多类型派生自 ExtensibleEnum。以前，这些类型都可隐式转换为类型 string。但是，在这些类的 Object.Equals 实现中发现了一个 bug，为了修复该 bug，需要禁用这种隐式转换。仍允许显式转换为 string 。

示例

如果代码如下所示：

var customTokenizerName = TokenizerName.Create("my_tokenizer"); 
var customTokenFilterName = TokenFilterName.Create("my_tokenfilter"); 
var customCharFilterName = CharFilterName.Create("my_charfilter"); 
 
var index = new Index();
index.Analyzers = new Analyzer[] 
{ 
    new CustomAnalyzer( 
        "my_analyzer",  
        customTokenizerName,  
        new[] { customTokenFilterName },  
        new[] { customCharFilterName }), 
};

可以将其更改为这样以修复任何构建错误：

const string CustomTokenizerName = "my_tokenizer"; 
const string CustomTokenFilterName = "my_tokenfilter"; 
const string CustomCharFilterName = "my_charfilter"; 
 
var index = new Index();
index.Analyzers = new Analyzer[] 
{ 
    new CustomAnalyzer( 
        "my_analyzer",  
        CustomTokenizerName,  
        new TokenFilterName[] { CustomTokenFilterName },  
        new CharFilterName[] { CustomCharFilterName })
};

删除了已过时的成员

你可能会看到与版本 2.0-preview 中标记为已过时的方法或属性相关的生成错误，随后在版本 3 中删除。如果遇到此类错误，下面介绍了如何解决这些错误：

如果使用此构造函数： ScoringParameter(string name, string value)请改用此构造函数： ScoringParameter(string name, IEnumerable<string> values)
如果使用ScoringParameter.Value属性，请改用ScoringParameter.Values属性或ToString方法。
如果使用SearchRequestOptions.RequestId属性，请改用ClientRequestId属性。

已删除预览功能

如果要从版本 2.0-preview 升级到版本 3，请注意，已删除对 Blob 索引器的 JSON 和 CSV 分析支持，因为这些功能仍处于预览状态。具体而言，已删除类的 IndexingParametersExtensions 以下方法：

ParseJson
ParseJsonArrays
ParseDelimitedTextFiles

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

结论

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

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

感谢你使用 Azure 搜索！

Last updated on 2021-09-16