升级到 Azure 搜索 .NET SDK 版本 3Upgrade to Azure Search .NET SDK version 3

如果使用的是版本 2.0-preview 或更早版本的 Azure 搜索 .NET SDK,本文有助于升级应用程序,以便使用版本 3。If you're using version 2.0-preview or older of the Azure Search .NET SDK, this article will help you upgrade your application to use version 3.

有关包括示例的 SDK 的更多常规演练,请参阅如何使用 .NET 应用程序中的 Azure 搜索For a more general walkthrough of the SDK including examples, see How to use Azure Search from a .NET Application.

版本 3 的 Azure 搜索 .NET SDK 包含了某些针对早期版本进行的更改。Version 3 of the Azure Search .NET SDK contains some changes from earlier versions. 这些更改主要涉及次要版本,因此更改代码的工作量并不是太大。These are mostly minor, so changing your code should require only minimal effort. 有关如何更改代码以使用新版 SDK 的说明,请参阅升级步骤See Steps to upgrade for instructions on how to change your code to use the new SDK version.

备注

如果使用的是版本 1.0.2-preview 或更早版本,则应该先升级到版本 1.1,再升级到版本 3。If you're using version 1.0.2-preview or older, you should upgrade to version 1.1 first, and then upgrade to version 3. 有关说明,请参阅升级到 Azure 搜索 .NET SDK 版本 1.1See Upgrading to the Azure Search .NET SDK version 1.1 for instructions.

Azure 搜索服务实例支持多个 REST API 版本,包括最新的版本。Your Azure Search service instance supports several REST API versions, including the latest one. 可以不使用最新版本,但是我们建议迁移代码,以便使用最新版本。You can continue to use a version when it is no longer the latest one, but we recommend that you migrate your code to use the newest version. 使用 REST API 时,必须在每个请求中通过 api-version 参数指定 API 版本。When using the REST API, you must specify the API version in every request via the api-version parameter. 使用 .NET SDK 时,使用的 SDK 版本确定对应的 REST API 版本。When using the .NET SDK, the version of the SDK you're using determines the corresponding version of the REST API. 如果使用较旧的 SDK,即使已升级服务以支持较新的 API 版本,也可以继续运行代码,而不进行任何更改。If you are using an older SDK, you can continue to run that code with no changes even if the service is upgraded to support a newer API version.

版本 3 中的新增功能What's new in version 3

版本 3 的 Azure 搜索 .NET SDK 针对 Azure 搜索 REST API 的最新正式发布版本,具体来说就是 2016-09-01。Version 3 of the Azure Search .NET SDK targets the latest generally available version of the Azure Search REST API, specifically 2016-09-01. 这使得可以在 .NET 应用程序中使用 Azure 搜索的许多新功能,如下所示:This makes it possible to use many new features of Azure Search from a .NET application, including the following:

  • 自定义分析器Custom analyzers
  • Azure Blob 存储Azure 表存储索引器支持Azure Blob Storage and Azure Table Storage indexer support
  • 通过字段映射实现的索引器自定义Indexer customization via field mappings
  • 用于支持安全并发更新索引定义、索引器和数据源的 ETag 支持ETags support to enable safe concurrent updating of index definitions, indexers, and data sources
  • 支持通过修饰模型类并使用新的 FieldBuilder 类,以声明方式构建索引字段定义。Support for building index field definitions declaratively by decorating your model class and using the new FieldBuilder class.
  • 对 .NET Core 和 .NET Portable Profile 111 的支持Support for .NET Core and .NET Portable Profile 111

升级步骤Steps to upgrade

首先,按以下方法操作更新 Microsoft.Azure.Search 的 NuGet 引用:使用 NuGet 包管理器控制台,或者在 Visual Studio 中右键单击项目引用,然后选择“管理 NuGet 程序包...”。First, update your NuGet reference for Microsoft.Azure.Search using either the NuGet Package Manager Console or by right-clicking on your project references and selecting "Manage NuGet Packages..." in Visual Studio.

在 NuGet 已下载新的程序包及其依赖项后,请重新生成项目。Once NuGet has downloaded the new packages and their dependencies, rebuild your project. 项目重新生成可能会成功,具体取决于代码的结构。Depending on how your code is structured, it may rebuild successfully. 如果成功,一切准备就绪!If so, you're ready to go!

如果生成失败,应该会看到如下所示的生成错误:If your build fails, you should see a build error like the following:

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?)

下一步是修复生成错误。The next step is to fix this build error. 有关出错原因和修复方法的详细信息,请参阅版本 3 中的重大更改See Breaking changes in version 3 for details on what causes the error and how to fix it.

可能会看到与已过时方法或属性有关的其他生成警告。You may see additional build warnings related to obsolete methods or properties. 这些警告将包含有关使用哪些功能来替换已弃用功能的说明。The warnings will include instructions on what to use instead of the deprecated feature. 例如,如果应用程序使用了 IndexingParameters.Base64EncodeKeys 属性,应该会收到显示 "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead." 的警告For example, if your application uses the IndexingParameters.Base64EncodeKeys property, you should get a warning that says "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead."

在修复了任何生成错误后,可以对应用程序进行更改,以利用新功能(如果愿意)。Once you've fixed any build errors, you can make changes to your application to take advantage of new functionality if you wish. 有关 SDK 中的新功能的详细信息,请参阅版本 3 中的新增功能New features in the SDK are detailed in What's new in version 3.

版本 3 中的重大更改Breaking changes in version 3

除重新生成应用程序之外,版本 3 中只有少量可能需要更改代码的重大更改。There a small number of breaking changes in version 3 that may require code changes in addition to rebuilding your application.

Indexes.GetClient 返回类型Indexes.GetClient return type

Indexes.GetClient 方法具有新的返回类型。The Indexes.GetClient method has a new return type. 以前,它返回 SearchIndexClient,但在版本 2.0-preview 中已将此项更改为 ISearchIndexClient,而该更改将传递给版本 3。Previously, it returned SearchIndexClient, but this was changed to ISearchIndexClient in version 2.0-preview, and that change carries over to version 3. 这是为了支持想要通过返回 ISearchIndexClient 的模拟实现,来模拟测试单元的 GetClient 方法的客户。This is to support customers that wish to mock the GetClient method for unit tests by returning a mock implementation of ISearchIndexClient.

示例Example

如果代码如下所示:If your code looks like this:

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

若要修复任何生成错误,可以更改为如下所示的代码:You can change it to this to fix any build errors:

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

AnalyzerName、DataType 等不再隐式转换为字符串AnalyzerName, DataType, and others are no longer implicitly convertible to strings

Azure 搜索 .NET SDK 中有许多派生自 ExtensibleEnum 的类型。There are many types in the Azure Search .NET SDK that derive from ExtensibleEnum. 以前,这些类型都隐式转换为 string 类型。Previously these types were all implicitly convertible to type string. 但是,在这些类的 Object.Equals 实现中发现了 bug,修复 bug 需要禁止此隐式转换。However, a bug was discovered in the Object.Equals implementation for these classes, and fixing the bug required disabling this implicit conversion. 仍允许显式转换为 stringExplicit conversion to string is still allowed.

示例Example

如果代码如下所示:If your code looks like this:

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 }), 
}; 

若要修复任何生成错误,可以更改为如下所示的代码:You can change it to this to fix any build errors:

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 })
}; 

删除了过时成员Removed obsolete members

可能会看到与版本 2.0-preview 中标记为已过时的方法或属性相关的生成错误,这些方法或属性随后已在版本 3 中删除。You may see build errors related to methods or properties that were marked as obsolete in version 2.0-preview and subsequently removed in version 3. 如果遇到此类错误,可按下面所述解决它们:If you encounter such errors, here is how to resolve them:

  • 如果使用此构造函数:ScoringParameter(string name, string value),请改为使用这个:ScoringParameter(string name, IEnumerable<string> values)If you were using this constructor: ScoringParameter(string name, string value), use this one instead: ScoringParameter(string name, IEnumerable<string> values)
  • 如果使用 ScoringParameter.Value 属性,请改为使用 ScoringParameter.Values 属性或 ToString 方法。If you were using the ScoringParameter.Value property, use the ScoringParameter.Values property or the ToString method instead.
  • 如果使用 SearchRequestOptions.RequestId 属性,请改为使用 ClientRequestId 属性。If you were using the SearchRequestOptions.RequestId property, use the ClientRequestId property instead.

删除了预览功能Removed preview features

如果要从版本 2.0-preview 升级到版本 3,请注意,JSON 和 CSV 对 Blob 索引器的分析支持已删除,因为这些功能仍处于预览状态。If you are upgrading from version 2.0-preview to version 3, be aware that JSON and CSV parsing support for Blob Indexers has been removed since these features are still in preview. 具体而言,IndexingParametersExtensions 类的以下方法已删除:Specifically, the following methods of the IndexingParametersExtensions class have been removed:

  • ParseJson
  • ParseJsonArrays
  • ParseDelimitedTextFiles

如果应用程序硬依赖于这些功能,则将不能升级到版本 3 的 Azure 搜索 .NET SDK。If your application has a hard dependency on these features, you will not be able to upgrade to version 3 of the Azure Search .NET SDK. 可以继续使用版本 2.0-preview。You can continue to use version 2.0-preview. 但是,请记住,我们不建议在生产应用程序中使用预览版 SDKHowever, please keep in mind that we do not recommend using preview SDKs in production applications. 预览功能仅用于评估,并且可能会更改。Preview features are for evaluation only and may change.

结束语Conclusion

如果需要有关如何使用 Azure 搜索 .NET SDK 的更多详细信息,请参阅 .NET 操作指南If you need more details on using the Azure Search .NET SDK, see the .NET How-to.

我们欢迎你对 SDK 提供反馈。We welcome your feedback on the SDK. 如果遇到问题,请随时通过 Stack Overflow 向我们寻求帮助。If you encounter problems, feel free to ask us for help on Stack Overflow. 如果找到 Bug,可以在 Azure .NET SDK GitHub 存储库中提出问题。If you find a bug, you can file an issue in the Azure .NET SDK GitHub repository. 务必在问题标题上加前缀“[Azure 搜索]”。Make sure to prefix your issue title with "[Azure Search]".

感谢使用 Azure 搜索!Thank you for using Azure Search!