.NET Aspire Elasticsearch component
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
.NET Aspire
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for