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

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

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

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

注

バージョン 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 のバージョンが決まります。古い SDK を使用している場合は、サービスが新しい API バージョンをサポートするようにアップグレードされた場合でも、変更なしでそのコードを実行し続けることができます。

バージョン 3 の新機能

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

カスタムアナライザー
Azure Blob Storage と Azure Table Storage インデクサーのサポート
フィールドマッピングを使用したインデクサーのカスタマイズ
インデックス定義、インデクサー、およびデータソースの安全な同時更新を可能にする ETag のサポート
モデルクラスを修飾し、新しい FieldBuilder クラスを使用して、インデックスフィールド定義を宣言的に構築するためのサポート。
.NET Core と .NET ポータブルプロファイル 111 のサポート

アップグレードの手順

まず、NuGet パッケージマネージャーコンソールを使用するか、プロジェクト参照を右クリックして [NuGet パッケージの管理...] を選択して、Microsoft.Azure.Search の NuGet 参照を更新します。Visual Studio で〘

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 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 を使用していただきありがとうございます。

Last updated on 2021-09-16