.NET Aspire Elasticsearch integration
In this article, you learn how to use the .NET Aspire Elasticsearch integration. 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 integration, install the Aspire.Elastic.Clients.Elasticsearch NuGet package in the client-consuming project, i.e., the project for the application that uses the Elasticsearch client.
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 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 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 integration 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 integrations enable health checks for all services. For more information, see .NET Aspire integrations overview.
The .NET Aspire 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. 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 integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about integration observability and telemetry, see .NET Aspire integrations overview. Depending on the backing service, some integrations may only support some of these features. For example, some integrations 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 integration will emit the following tracing activities using OpenTelemetry:
Elastic.Transport