integración .NET AspireElasticsearch (versión preliminar)

incluye: integración de hospedaje de e integración de Client

Elasticsearch es un motor de búsqueda y análisis distribuido, un almacén de datos escalable y una base de datos vectorial capaz de abordar un número creciente de casos de uso. La integración de .NET AspireElasticsearch permite conectarse a instancias de Elasticsearch existentes o crear nuevas instancias a partir de .NET con la imagen de contenedor docker.io/library/elasticsearch.

El Elasticsearch que hospeda la integración modela una instancia de Elasticsearch como tipo de ElasticsearchResource. Para acceder a este tipo y a las APIs que le permiten agregarlo al 📦Aspire.Hosting.Elasticsearch paquete NuGet en el proyecto anfitrión de la aplicación .

dotnet add package Aspire.Hosting.Elasticsearch

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

Para obtener más información, consulte dotnet add package o Administrar las dependencias de los paquetes en .NET aplicaciones.

En el proyecto host de la aplicación, llame a AddElasticsearch en la instancia de builder para agregar un recurso de Elasticsearch:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(elasticsearch);

// After adding all resources, run the app...

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/library/elasticsearch, crea una nueva instancia de Elasticsearch en el equipo local. Se agrega una referencia al recurso de Elasticsearch (la variable elasticsearch) al ExampleProject. El recurso Elasticsearch incluye credenciales predeterminadas con una username de "elastic" y password generadas aleatoriamente mediante el método CreateDefaultPasswordParameter cuando no se proporcionó una contraseña.

El método WithReference configura una conexión en el ExampleProject denominado "elasticsearch". Para obtener más información, consulte ciclo de vida de los recursos de contenedor.

Para agregar un volumen de datos al recurso de Elasticsearch, llame al método WithDataVolume en el recurso Elasticsearch:

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...

El volumen de datos se usa para persistir los datos de Elasticsearch más allá del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /usr/share/elasticsearch/data dentro del contenedor Elasticsearch y, cuando no se proporciona un parámetro name, el nombre se genera aleatoriamente. Para obtener más información sobre los volúmenes de datos y detalles de por qué son preferidos sobre volúmenes vinculados, consulte la Docker documentación: Volúmenes.

Para agregar un montaje de vinculación de datos al recurso de Elasticsearch, utilice el método 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...

Los montajes de vinculación de datos dependen del sistema de archivos del equipo host para mantener los datos de Elasticsearch durante los reinicios del contenedor. El montaje de enlace de datos está montado en la ruta de acceso C:\Elasticsearch\Data en Windows (o /Elasticsearch/Data en Unix) en la máquina anfitriona que aloja el contenedor Elasticsearch. Para obtener más información sobre las vinculaciones de montaje de datos, consulte la documentación Docker: Enlazar montajes.

Cuando quiera proporcionar explícitamente la contraseña usada por la imagen de contenedor, puede proporcionar estas credenciales como parámetros. Considere el siguiente ejemplo alternativo:

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...

Para obtener más información sobre cómo proporcionar parámetros, consulte Parámetros externos.

La integración de hospedaje Elasticsearch agrega automáticamente una comprobación de estado para el recurso Elasticsearch. La comprobación de estado comprueba que la instancia de Elasticsearch se está ejecutando y que se puede establecer una conexión con ella.

La integración de hospedaje se basa en el 📦 AspNetCore.HealthChecks.Elasticsearch paquete NuGet.

Para empezar con la integración del cliente .NET AspireElasticsearch, instalar el paquete NuGet 📦Aspire.Elastic.Clients.Elasticsearch en el proyecto que utiliza el cliente, es decir, el proyecto de la aplicación que usa el cliente Elasticsearch. La integración de cliente de Elasticsearch registra una instancia de ElasticsearchClient que puede usar para interactuar con Elasticsearch.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

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

En el archivo Program.cs de su proyecto cliente, llame al método de extensión AddElasticsearchClient en cualquier IHostApplicationBuilder para registrar un ElasticsearchClient para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

A continuación, puede recuperar la instancia de ElasticsearchClient mediante inyección de dependencia. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

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

Puede haber situaciones en las que quiera registrar varias instancias de ElasticsearchClient con nombres de conexión diferentes. Para registrar clientes de Elasticsearch con clave, llame al AddKeyedElasticsearchClient:

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

A continuación, puede recuperar las instancias de ElasticsearchClient mediante inyección de dependencia. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

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

Para obtener más información sobre los servicios con claves, consulte .NET inserción de dependencias: Servicios con claves.

La integración de cliente de .NET AspireElasticsearch proporciona varias opciones para configurar la conexión del servidor en función de los requisitos y convenciones del proyecto.

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar a builder.AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

Desde ahí, la cadena de conexión será obtenida de la sección de configuración ConnectionStrings.

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

La integración de .NET AspireElasticsearchClient admite Microsoft.Extensions.Configuration. Carga el ElasticClientsElasticsearchSettings desde la configuración utilizando la clave Aspire:Elastic:Clients:Elasticsearch. Considere el ejemplo siguiente appsettings.json que configura algunas de las opciones:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
            "DisableHealthChecks": false,
            "DisableTracing": false,
            "HealthCheckTimeout": "00:00:03",  
            "ApiKey": "<Valid ApiKey>",
            "Endpoint": "http://elastic:password@localhost:27011",
            "CloudId": "<Valid CloudId>"
        }
      }
    }
  }
}

Para obtener el esquema completo Elasticsearch de integración del cliente JSON, consulte Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

También puede pasar el delegado Action<ElasticClientsElasticsearchSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para establecer la clave de API desde el código:

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

Al usar Elastic Cloud, puede proporcionar el CloudId y el ApiKey en la sección Aspire:Elastic:Clients:Elasticsearch al llamar a builder.AddElasticsearchClient.

builder.AddElasticsearchClient("elasticsearch");

Considere el ejemplo siguiente appsettings.json que configura las opciones:

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

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

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan verificaciones de estado para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

La integración .NET AspireElasticsearch utiliza el cliente configurado para realizar una PingAsync. Si el resultado es HTTP 200 OK, la comprobación de estado se considera correcta; de lo contrario, es incorrecta. Del mismo modo, si hay una excepción, la comprobación de estado se considera no satisfactoria y el error se propaga a través del fallo de la comprobación de estado.

.NET .NET Aspire integraciones configuran automáticamente el registro de eventos, el seguimiento y las métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección de configuración .

La integración de .NET AspireElasticsearch emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

• Elastic.Transport

• Elasticsearch .NET
• .NET .NET Aspire integraciones
• .NET Aspire GitHub repositorio