Azure Search .NET SDK バージョン 3 へのアップグレード

[アーティクル]
09/16/2021

バージョン 2.0-preview 以前の Azure Search .NET SDK を使用している場合、この記事を参考にして、バージョン 3 を使用するようにアプリケーションをアップグレードできます。

例を含む SDK の一般的なチュートリアルについては、「 .NET アプリケーションから Azure Search を使用する方法」を参照してください。

Azure Search .NET SDK のバージョン 3 には、以前のバージョンからの変更がいくつか含まれています。ほとんどは小さなものなので、コードの変更に必要な作業は最小限で済みます。新しいバージョンの SDK を使用するようにコードを変更する方法については、「アップグレードの手順」を参照してください。

Note

1.0.2-preview 以前のバージョンを使用している場合は、まずバージョン 1.1 にアップグレードしてから、バージョン 3 にアップグレードする必要があります。手順については、「Azure Search .NET SDK バージョン 1.1 へのアップグレード」をご覧ください。

Azure Search サービスのインスタンスは、最新のバージョンを含む複数の REST API バージョンをサポートします。バージョンが最新ではなくなった場合でも、そのバージョンを引き続き使用できますが、最新バージョンを使用するようにコードを移行することをお勧めします。 REST API を使用している場合は、api-version パラメーターを使用して、すべての要求に API バージョンを指定する必要があります。 .NET SDK を使用している場合は、使用している SDK のバージョンによって REST API の対応するバージョンが決まります。サービスが新しいバージョンの API をサポートするようにアップグレードされた場合でも、使用中の古い SDK のコードを変更なしで引き続き実行できます。

バージョン 3 の新機能

Azure Search .NET SDK のバージョン 3 は、Azure Search REST API の最新の一般公開バージョン (2016-09-01) を対象としています。これにより、次のような Azure Search の多数の新機能を .NET アプリケーションから使用することが可能になります。

カスタムアナライザー
Azure Blob Storage と Azure Table Storage のインデクサーのサポート
フィールドマッピング
インデックスの定義、インデクサー、およびデータソースの安全な同時更新を有効にする Etag のサポート
モデルクラスを装飾し、新しい FieldBuilder クラスを使用することによる、インデックスフィールド定義の宣言による作成のサポート
.NET Core と .NET Portable Profile 111 のサポート

アップグレードの手順

最初に、NuGet パッケージマネージャーコンソールを使用して、または Visual Studio でプロジェクト参照を右クリックして [NuGet パッケージの管理...] を選択することで、 Microsoft.Azure.Search の 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 Search .NET SDK には、ExtensibleEnum から派生する型が多数あります。これまで、これらの型はすべて string 型に暗黙的に変換できました。しかし、これらのクラスの Object.Equals 実装でバグが見つかり、バグを修正するためにこの暗黙的な変換を無効にする必要がありました。 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 Search .NET SDK のバージョン 3 にアップグレードすることはできません。バージョン 2.0-preview を引き続き使用できますが、 実稼働アプリケーションでのプレビュー版 SDK の使用は推奨されないことに注意してください。プレビュー機能は評価のみを目的としており、変更される場合があります。

まとめ

Azure Search .NET SDK の使い方について詳しくは、.NET の方法に関する記事をご覧ください。

SDK についてのご意見をお待ちしております。問題が発生した場合は、Stack Overflow でご質問ください。バグを発見した場合は、 Azure .NET SDK の GitHub リポジトリで問題を報告できます。問題のタイトルの前に、必ず "[Azure Search]" を付けてください。

Azure Search をお使いいただきありがとうございます。

次の方法で共有