Comparteix a través de

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

  • Article

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.

Integración de hospedaje

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

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

Agregar Elasticsearch recurso

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.

Propina

Si prefiere conectarse a una instancia de Elasticsearch existente, llame a AddConnectionString en su lugar. Para obtener más información, vea Consulte los recursos existentes.

Agregar recurso Elasticsearch con un volumen de datos

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.

Agrega el recurso Elasticsearch con montaje de enlace de datos.

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

Importante

Los montajes de enlace de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen un mejor rendimiento, portabilidad y seguridad, lo que los hace más adecuados para entornos de producción. Sin embargo, los montajes bind permiten el acceso directo y la modificación de archivos en el sistema host, ideal para el desarrollo y las pruebas donde se necesitan cambios realizados de forma inmediata.

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.

Añadir recurso Elasticsearch con el parámetro contraseña

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.

Comprobaciones de salud de la integración de hospedaje

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.

integración Client

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

Agregar cliente Elasticsearch

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");

Propina

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso Elasticsearch en el proyecto host de la aplicación. Para obtener más información, consulte Agregar Elasticsearch recurso.

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

Adición de un cliente de Elasticsearch con clave

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.

Configuración

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.

Uso de una cadena de conexión

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"
  }
}

Uso de proveedores de configuración

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.

Use delegados en línea

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"));

Utiliza un CloudId y un ApiKey con proveedores de configuración

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>"
        }
      }
    }
  }
}

Usar un CloudId y un ApiKey con delegados en línea

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

verificación del estado de integración de Client

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.

Observabilidad y telemetría

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

Seguimiento

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

  • Elastic.Transport

Consulte también