.NET Aspire Elasticsearch 統合

含まれるもの:ホスティング統合 と Client 統合

Elasticsearch は、分散型の RESTful 検索および分析エンジン、スケーラブルなデータ ストア、増加するユース ケースに対応できるベクター データベースです。 .NET Aspire Elasticsearch 統合を使用すると、既存の Elasticsearch インスタンスに接続したり、docker.io/library/elasticsearch コンテナー イメージを使用して .NET から新しいインスタンスを作成したりできます。

ホスティング統合

Elasticsearch ホスティング統合は、ElasticsearchResource 型として Elasticsearch インスタンスをモデル化します。 この型と、それを 📦Aspireホスティングに追加するための API にアクセスするには、アプリホスト プロジェクトでElasticsearch NuGet パッケージを使用します。

.NET コマンドラインインターフェース

dotnet add package Aspire.Hosting.Elasticsearch

PackageReference

<PackageReference Include="Aspire.Hosting.Elasticsearch"
                  Version="*" />

詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

リソース Elasticsearch を追加してください

アプリ ホスト プロジェクトで、builder インスタンスの AddElasticsearch を呼び出して、Elasticsearch リソースを追加します。

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(elasticsearch);

// After adding all resources, run the app...

.NET .NET Aspire 前の例で示したように、docker.io/library/elasticsearch イメージでコンテナー イメージをアプリ ホストに追加すると、ローカル コンピューターに新しい Elasticsearch インスタンスが作成されます。 Elasticsearch リソース (elasticsearch 変数) への参照が ExampleProjectに追加されます。 Elasticsearch リソースには、"elastic" の username を持つ既定の資格情報と、パスワードが指定されなかったときに CreateDefaultPasswordParameter メソッドを使用してランダムに生成された password が含まれます。

WithReference メソッドは、"elasticsearch"という名前の ExampleProject で接続を構成します。 詳細については、「コンテナー リソースのライフサイクルの」を参照してください。

ヒント

既存の Elasticsearch インスタンスに接続する場合は、代わりに AddConnectionString 呼び出します。 詳細については、「既存のリソースを参照する」を参照してください。

データ ボリューム Elasticsearch リソースを追加する

Elasticsearch リソースにデータ ボリュームを追加するには、Elasticsearch リソースで WithDataVolume メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch")
                           .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
        .WithReference(elasticsearch);

// After adding all resources, run the app...

データ ボリュームは、Elasticsearch データをコンテナーのライフサイクル外に保持するために使用されます。 データ ボリュームは、Elasticsearch コンテナー内の /usr/share/elasticsearch/data パスにマウントされ、name パラメーターが指定されていない場合、名前はランダムに生成されます。 データ ボリュームの詳細と、マウントのバインド 優先される理由の詳細については、「 ドキュメント: ボリューム」を参照してください。

Elasticsearch リソースをデータバインドマウントで追加する

Elasticsearch リソースにデータ バインド マウントを追加するには、WithDataBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch")
                           .WithDataBindMount(
                               source: @"C:\Elasticsearch\Data",
                               isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
        .WithReference(elasticsearch);

// After adding all resources, run the app...

大事な

データ バインド マウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適した ボリュームと比較して機能が制限されています。 ただし、バインド マウントを使用すると、ホスト システム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データ バインド マウントは、ホスト マシンのファイルシステムに依存して、コンテナーの再起動間に Elasticsearch データを保持します。 データ バインド マウントは、Elasticsearch コンテナー内のホスト コンピューター上の Windows 上の C:\Elasticsearch\Data (または Unixの /Elasticsearch/Data) パスにマウントされます。 データ バインドマウントの詳細については、「Docker ドキュメント:バインドマウント」を参照してください。

パスワード パラメーター Elasticsearch リソースを追加する

コンテナー イメージで使用されるパスワードを明示的に指定する場合は、これらの資格情報をパラメーターとして指定できます。 次の代替例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("password", secret: true);
var elasticsearch = builder.AddElasticsearch("elasticsearch", password);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(elasticsearch);

// After adding all resources, run the app...

パラメーターの指定の詳細については、「外部パラメーターの」を参照してください。

ホスティング統合の正常性チェック

Elasticsearch ホスティング統合により、Elasticsearch リソースの正常性チェックが自動的に追加されます。 正常性チェックでは、Elasticsearch インスタンスが実行中であり、そのインスタンスへの接続を確立できることを確認します。

ホスティング統合は、📦 AspNetCore.HealthChecks およびElasticsearch NuGet パッケージに依存しています。

Client 統合

.NET Aspire Elasticsearch client 統合を開始するには、clientを利用するプロジェクト、すなわち、Elasticsearchclientを使用するアプリケーションのプロジェクトに、📦Aspireおよび Elastic.Clients.Elasticsearch NuGet パッケージをインストールしてください。 Elasticsearch client 統合により、Elasticsearchとの対話に使用できる ElasticsearchClient インスタンスが登録されます。

.NET CLI

dotnet add package Aspire.Elastic.Clients.Elasticsearch

PackageReference

<PackageReference Include="Aspire.Elastic.Clients.Elasticsearch"
                  Version="*" />

Elasticsearch client の追加

client-consuming プロジェクトの Program.cs ファイルで、任意の IHostApplicationBuilder で AddElasticsearchClient 拡張メソッドを呼び出して、依存関係挿入コンテナー経由で使用する ElasticsearchClient を登録します。 このメソッドは、接続名パラメーターを受け取ります。

builder.AddElasticsearchClient(connectionName: "elasticsearch");

ヒント

connectionName パラメーターは、アプリ ホスト プロジェクトに Elasticsearch リソースを追加するときに使用する名前と一致する必要があります。 詳細については、「に Elasticsearch リソースを追加する」を参照してください。

その後、依存関係の挿入を使用して ElasticsearchClient インスタンスを取得できます。 たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(ElasticsearchClient client)
{
    // Use client...
}

キー付き Elasticsearchclient を追加する

接続名が異なる複数の ElasticsearchClient インスタンスを登録する場合があります。 キー付き Elasticsearch クライアントを登録するには、AddKeyedElasticsearchClientを呼び出します。

builder.AddKeyedElasticsearchClient(name: "products");
builder.AddKeyedElasticsearchClient(name: "orders");

その後、依存関係の挿入を使用して ElasticsearchClient インスタンスを取得できます。 たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(
    [FromKeyedServices("products")] ElasticsearchClient productsClient,
    [FromKeyedServices("orders")] ElasticsearchClient ordersClient)
{
    // Use clients...
}

キー付きサービスの詳細については、「.NET 依存関係の挿入: キー付きサービスの」を参照してください。

設定

.NET Aspire Elasticsearch client 統合には、プロジェクトの要件と規則に基づいて server 接続を構成するための複数のオプションが用意されています。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、builder.AddElasticsearchClientを呼び出すときに接続文字列の名前を指定できます。

builder.AddElasticsearchClient("elasticsearch");

その後、接続文字列は ConnectionStrings 構成セクションから取得されます。

{
  "ConnectionStrings": {
    "elasticsearch": "http://elastic:password@localhost:27011"
  }
}

構成プロバイダーを使用する

.NET Aspire Elasticsearch Client 統合では、Microsoft.Extensions.Configurationがサポートされています。 Aspire:Elastic:Clients:Elasticsearch キーを使用して、構成から ElasticClientsElasticsearchSettings を読み込みます。 次の例 appsettings について考えてみましょう。いくつかのオプションを構成するjson:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
            "DisableHealthChecks": false,
            "DisableTracing": false,
            "HealthCheckTimeout": "00:00:03",  
            "ApiKey": "<Valid ApiKey>",
            "Endpoint": "http://elastic:password@localhost:27011",
            "CloudId": "<Valid CloudId>"
        }
      }
    }
  }
}

完全な Elasticsearchclient 統合 JSON スキーマについては、Aspireを参照してください。Elastic.Clients.Elasticsearch/ConfigurationSchema。json.

インライン デリゲートを使用する

また、Action<ElasticClientsElasticsearchSettings> configureSettings デリゲートを渡して、コードから API キーを設定するなど、一部またはすべてのオプションをインラインで設定することもできます。

builder.AddElasticsearchClient(
    "elasticsearch",
    static settings =>
        settings.Endpoint = new Uri("http://elastic:password@localhost:27011"));

構成プロバイダーで CloudId と ApiKey を使用する

Elastic Cloud使用する場合は、を呼び出すときに、 セクションで と を指定できます。

builder.AddElasticsearchClient("elasticsearch");

次の例 appsettings について考えてみましょう。オプションを構成するjson:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
            "ApiKey": "<Valid ApiKey>",
            "CloudId": "<Valid CloudId>"
        }
      }
    }
  }
}

インライン デリゲートで CloudId と ApiKey を使用する

builder.AddElasticsearchClient(
    "elasticsearch",
    static settings =>
    {
        settings.ApiKey = "<Valid ApiKey>";
        settings.CloudId = "<Valid CloudId>";
    });

Client 統合正常性をチェックする

既定では、.NET.NET Aspire 統合により、すべてのサービス 正常性チェック が有効になります。 詳細については、.NET.NET Aspire 統合の概要を参照してください。

.NET Aspire Elasticsearch 統合では、構成された client を使用して PingAsyncを実行します。 結果が HTTP 200 OK の場合、正常性チェックは正常と見なされます。それ以外の場合は異常です。 同様に、例外がある場合、健康診断は異常とみなされ、エラーは健康診断の失敗を通じて伝播します。

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱 とも呼ばれます。 統合の可観測性とテレメトリの詳細については、統合の概要 参照してください。 バッキング サービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。 たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。 テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

トレーシング

.NET Aspire Elasticsearch 統合では、OpenTelemetryを使用して次のトレース アクティビティが出力されます。

• Elastic.Transport

関連項目

• Elasticsearch .NET
• .NET .NET Aspire 統合
• .NET Aspire GitHub リポジトリ