.NET Aspire Elasticsearch 集成

包括：托管集成 和 Client 集成

Elasticsearch 是分布式 RESTful 搜索和分析引擎、可缩放数据存储和矢量数据库，能够处理越来越多的用例。 通过 .NET AspireElasticsearch 集成，可以连接到现有 Elasticsearch 实例，或使用 docker.io/library/elasticsearch 容器映像从 .NET 创建新实例。

托管集成

托管集成 Elasticsearch 将 Elasticsearch 实例建模为 ElasticsearchResource 类型。 若要访问此类型和 API，请将其添加到 应用主机 项目的 NuGet 包中，位于 托管中。

.NET CLI

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 数据。 数据卷挂载在 Elasticsearch 容器中的 /usr/share/elasticsearch/data 路径上，当未提供 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 数据。 数据绑定装载被装载在 Windows 系统上的 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 集成，请安装 📦Aspire。Elastic.Clients.Elasticsearchclient消耗项目中的 NuGet 包，即使用 Elasticsearchclient的应用程序的项目。 Elasticsearch client 集成注册了可用于与 Elasticsearch交互的 ElasticsearchClient 实例。

.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 存储库