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

项目
09/16/2021

如果使用的是版本 2.0-preview 或更早版本的 Azure 搜索 .NET SDK，本文有助于升级应用程序，以便使用版本 3。

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

版本 3 的 Azure 搜索 .NET SDK 包含了某些针对早期版本进行的更改。这些更改主要涉及次要版本，因此更改代码的工作量并不是太大。有关如何更改代码以使用新版 SDK 的说明，请参阅升级步骤。

注意

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

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

版本 3 中的新增功能

版本 3 的 Azure 搜索 .NET SDK 针对 Azure 搜索 REST API 的最新正式发布版本，具体来说就是 2016-09-01。这使得可以在 .NET 应用程序中使用 Azure 搜索的许多新功能，如下所示：

自定义分析器
Azure Blob 存储和 Azure 表存储索引器支持
通过字段映射实现的索引器自定义
用于支持安全并发更新索引定义、索引器和数据源的 ETag 支持
支持通过修饰模型类并使用新的 FieldBuilder 类，以声明方式构建索引字段定义。
对 .NET Core 和 .NET Portable Profile 111 的支持

升级步骤

首先，按以下方法操作更新 Microsoft.Azure.Search 的 NuGet 引用：使用 NuGet 包管理器控制台，或者在 Visual Studio 中右键单击项目引用，然后选择“管理 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。这是为了支持想要通过返回 ISearchIndexClient 的模拟实现，来模拟测试单元的 GetClient 方法的客户。

示例

如果代码如下所示：

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，请注意，JSON 和 CSV 对 Blob 索引器的分析支持已删除，因为这些功能仍处于预览状态。具体而言，IndexingParametersExtensions 类的以下方法已删除：

ParseJson
ParseJsonArrays
ParseDelimitedTextFiles

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

结束语

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

我们欢迎你对 SDK 提供反馈。如果遇到问题，请随时通过 Stack Overflow 向我们寻求帮助。如果找到 Bug，可以在 Azure .NET SDK GitHub 存储库中提出问题。务必在问题标题上加前缀“[Azure 搜索]”。

感谢使用 Azure 搜索！

通过