.NET Aspire Elasticsearch 整合

包括：裝載整合 和 Client 整合

Elasticsearch 是分散式、RESTful 搜尋和分析引擎、可調整的數據存放區，以及能夠處理越來越多的使用案例的向量資料庫。 .NET Aspire Elasticsearch 整合可讓您連線到現有的 Elasticsearch 實例，或使用 docker.io/library/elasticsearch 容器映射從 .NET 建立新的實例。

主機托管整合

主機整合 Elasticsearch 將 Elasticsearch 實例模型化為 ElasticsearchResource 類型。 若要存取此類型和 API，您可以將它新增至 📦Aspire.Hosting.Elasticsearch NuGet 套件的 應用程式主機 專案中。

.NET 命令列介面

dotnet add package Aspire.Hosting.Elasticsearch

PackageReference

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

如需詳細資訊，請參閱 dotnet add package 或 在 .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 資源包括具備預設認證，其 username 為 "elastic"，若未提供密碼，則會使用 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 數據保存在其容器生命週期之外。 數據磁碟區會掛接在 /usr/share/elasticsearch/data 路徑中的 Elasticsearch 容器，當未提供 name 參數時，名稱會隨機生成。 如需關於資料卷的更多資訊及為何它們比 綁定掛載更被青睞的詳細原因，請參閱 Docker 文件：「磁碟區」。

使用數據系結掛接新增 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 數據。 數據掛載會掛載於主機的 C:\Elasticsearch\Data 上（或 Unix的 /Elasticsearch/Data 路徑上）Elasticsearch 容器中。 如需資料系結掛接的詳細資訊，請參閱 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 AspireElasticsearchclient 整合，請在取用的 client專案中安裝 📦AspireElastic.Clients.Elasticsearch NuGet 套件，也就是應用程式使用 Elasticsearchclient的專案。 Elasticsearch client 整合會註冊 ElasticsearchClient 實例，讓您可用來與 Elasticsearch互動。

.NET CLI

dotnet add package Aspire.Elastic.Clients.Elasticsearch

PackageReference

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

新增 Elasticsearchclient

在 client取用專案的 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時，在 Aspire:Elastic:Clients:Elasticsearch 區段中提供 CloudId 和 ApiKey。

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 .NET Aspire 整合會自動設定記錄、追蹤和度量組態，有時稱為 可觀察性的支柱。 如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。 視支援服務而定，某些整合可能只支援其中一些功能。 例如，某些整合支援記錄和追蹤，但不支援計量。 您也可以使用 組態 一節中呈現的技術來停用遙測功能。

追蹤

.NET Aspire Elasticsearch 整合會使用 OpenTelemetry產生下列追蹤活動：

• Elastic.Transport

另請參閱

• Elasticsearch .NET
• .NET .NET Aspire 整合
• .NET Aspire GitHub repo