Elasticsearch client integration

To get started with the Aspire Elasticsearch client integration, install the 📦 Aspire.Elastic.Clients.Elasticsearch NuGet package:

.NET CLI

.NET CLI — Add Aspire.Elastic.Clients.Elasticsearch package

dotnet add package Aspire.Elastic.Clients.Elasticsearch

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Elastic.Clients.Elasticsearch@*

PackageReference (*.csproj)

XML — Add Aspire.Elastic.Clients.Elasticsearch package reference

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

The Elasticsearch client integration registers an ElasticsearchClient instance that you can use to interact with Elasticsearch.

For an introduction to the Elasticsearch integration, see Get started with the Elasticsearch integrations.

Add Elasticsearch client

In the Program.cs file of your client-consuming project, call the AddElasticsearchClient extension method to register an ElasticsearchClient for use via the dependency injection container:

builder.AddElasticsearchClient(connectionName: "elasticsearch");

संकेत

The connectionName parameter must match the name used when adding the Elasticsearch resource in the AppHost project.

You can then retrieve the ElasticsearchClient instance using dependency injection. For example, to retrieve the connection from an example service:

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

Add keyed Elasticsearch client

There might be situations where you want to register multiple ElasticsearchClient instances with different connection names. To register keyed Elasticsearch clients, call the AddKeyedElasticsearchClient method:

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

Then you can retrieve the ElasticsearchClient instances using dependency injection:

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

For more information on keyed services, see .NET dependency injection: Keyed services.

Configuration

The Elasticsearch integration provides multiple options to configure the server connection based on the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

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

Use configuration providers

The Elasticsearch integration supports Microsoft.Extensions.Configuration. It loads the ElasticClientsElasticsearchSettings from configuration using the Aspire:Elastic:Clients:Elasticsearch key. Example 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>"
        }
      }
    }
  }
}

Use inline delegates

You can pass the Action<ElasticClientsElasticsearchSettings> delegate to set up options inline:

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

Use CloudId and ApiKey with configuration providers

When using Elastic Cloud, you can provide the CloudId and ApiKey in the configuration:

builder.AddElasticsearchClient("elasticsearch");

Example appsettings.json:

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

Use CloudId and ApiKey with inline delegates

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

Client integration health checks

By default, Aspire integrations enable health checks for all services. The Elasticsearch integration uses the configured client to perform a PingAsync. If the result is an HTTP 200 OK, the health check is considered healthy, otherwise it’s unhealthy.

Observability and telemetry

Tracing

The Elasticsearch integration will emit the following tracing activities using OpenTelemetry:

• Elastic.Transport