Modifica

Condividi tramite

.NET Aspire Elasticsearch component

  • Articolo

In this article, you learn how to use the .NET Aspire Elasticsearch component. The Aspire.Elastic.Clients.Elasticsearch library registers a ElasticsearchClient in the DI container for connecting to a Elasticsearch. It enables corresponding health check and telemetry.

Prerequisites

  • Elasticsearch cluster.
  • Endpoint URI string for accessing the Elasticsearch API endpoint or a CloudId and an ApiKey from Elastic Cloud

Get started

To get started with the .NET Aspire Elasticsearch component, install the Aspire.Elastic.Clients.Elasticsearch NuGet package in the consuming client project.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Example usage

In the Program.cs file of your project, call the AddElasticsearchClient extension method to register a ElasticsearchClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddElasticsearchClient("elasticsearch");

App host usage

To model the Elasticsearch resource in the app host, install the Aspire.Hosting.Elasticsearch NuGet package in the app host project.

dotnet add package Aspire.Hosting.Elasticsearch

In the Program.cs file of AppHost, register a Elasticsearch cluster and consume the connection using the following methods:

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

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(elasticsearch);

The WithReference method configures a connection in the MyService project named elasticsearch. In the Program.cs file of MyService, the Elasticsearch connection can be consumed using:

builder.AddElasticsearchClient("elasticsearch");

Configuration

The .NET Aspire Elasticsearch client component 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 builder.AddElasticsearchClient():

builder.AddElasticsearchClient("elasticsearch");

And then the connection string will be retrieved from the ConnectionStrings configuration section:

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

Use configuration providers

The .NET Aspire Elasticsearch Client component supports Microsoft.Extensions.Configuration. It loads the ElasticClientsElasticsearchSettings from configuration by using the Aspire:Elastic:Clients:Elasticsearch key. Consider the following example appsettings.json that configures some of the options:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
            "Endpoint": "http://elastic:password@localhost:27011"
        }
      }
    }
  }
}

Use inline delegates

Also you can pass the Action<ElasticClientsElasticsearchSettings> configureSettings delegate to set up some or all the options inline, for example to set the API key from code:

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

Use a CloudId and an ApiKey with configuration providers

When using Elastic Cloud, you can provide the CloudId and ApiKey in Aspire:Elastic:Clients:Elasticsearch section when calling builder.AddElasticsearchClient().

builder.AddElasticsearchClient("elasticsearch");

Consider the following example appsettings.json that configures the options:

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

Use a CloudId and an ApiKey with inline delegates

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

Health checks

By default, .NET Aspire components enable health checks for all services. For more information, see .NET Aspire components overview.

The .NET Aspire Elasticsearch component 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. Likewise, if there's an exception, the health check is considered unhealthy with the error propagating through the health check failure.

Observability and telemetry

.NET Aspire components automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about component observability and telemetry, see .NET Aspire components overview. Depending on the backing service, some components may only support some of these features. For example, some components support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Tracing

The .NET Aspire Elasticsearch component will emit the following tracing activities using OpenTelemetry:

  • Elastic.Transport

See also