Partilhar via

.NET Aspire Elasticsearch integração

  • Artigo

Inclui:integração de Hosting e integração Client

Elasticsearch é um mecanismo de pesquisa e análise RESTful distribuído, armazenamento de dados escalável e banco de dados vetorial capaz de lidar com um número crescente de casos de uso. A integração de .NET AspireElasticsearch permite que você se conecte a instâncias de Elasticsearch existentes ou crie novas instâncias a partir de .NET com a imagem de contêiner docker.io/library/elasticsearch.

Integração de hospedagem

A integração de hospedagem Elasticsearch modela uma instância Elasticsearch como o tipo ElasticsearchResource. Para aceder a este tipo e APIs que lhe permitem adicioná-lo ao seu 📦Aspire. Hospedagem.Elasticsearch pacote NuGet no aplicativo host projeto.

dotnet add package Aspire.Hosting.Elasticsearch

Para obter mais informações, consulte dotnet add package ou Gerir dependências de pacotes em aplicações .NET.

Adicionar Elasticsearch recurso

Em seu projeto de host de aplicativo, chame AddElasticsearch na instância builder para adicionar um recurso Elasticsearch:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, como mostrado no exemplo anterior com a imagem docker.io/library/elasticsearch, ele cria uma nova instância de Elasticsearch em sua máquina local. Uma referência ao seu recurso Elasticsearch (a variável elasticsearch) é adicionada ao ExampleProject. O recurso Elasticsearch inclui credenciais padrão com uma username de "elastic" e password gerados aleatoriamente usando o método CreateDefaultPasswordParameter quando uma senha não foi fornecida.

O método WithReference configura uma conexão no ExampleProject chamado "elasticsearch". Para obter mais informações, consulte Ciclo de vida do recurso de contêiner.

Dica

Se você preferir se conectar a uma instância de Elasticsearch existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a recursos existentes.

Adicionar recurso Elasticsearch com volume de dados

Para adicionar um volume de dados ao recurso Elasticsearch, chame o método WithDataVolume no 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...

O volume de dados é usado para manter os dados Elasticsearch fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /usr/share/elasticsearch/data no contêiner Elasticsearch e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que são preferidos em detrimento das montagens de ligação , consulte a documentação Docker: Volumes.

Adicionar Elasticsearch recurso com montagem de associação de dados

Para adicionar uma montagem de ligação de dados ao recurso Elasticsearch, chame o 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

Os suportes de ligação de de dados têm funcionalidade limitada em comparação com volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos da máquina host para manter os dados Elasticsearch nas reinicializações do contêiner. A montagem de associação de dados é montada no caminho C:\Elasticsearch\Data no Windows (ou /Elasticsearch/Data no Unix) na máquina host no contêiner Elasticsearch. Para obter mais informações sobre montagens de bind de dados, consulte a documentação Docker: Bind mounts.

Adicionar o recurso Elasticsearch com o parâmetro palavra-passe

Quando quiser fornecer explicitamente a senha usada pela imagem do contêiner, você poderá fornecer essas credenciais como parâmetros. Considere o seguinte exemplo 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 obter mais informações sobre como fornecer parâmetros, consulte Parâmetros externos.

Verificações de integridade da integração de hospedagem

A integração de hospedagem Elasticsearch adiciona automaticamente uma verificação de integridade para o recurso Elasticsearch. A verificação de integridade verifica se a instância Elasticsearch está em execução e se uma conexão pode ser estabelecida com ela.

A integração de hospedagem depende do 📦 AspNetCore.HealthChecks.Elasticsearch pacote NuGet.

Client integração

Para começar com a integração .NET AspireElasticsearchclient, instale o 📦Aspire. Elastic.Clients.Elasticsearch pacote NuGet no projeto de consumo de client, ou seja, o projeto para o aplicativo que usa o Elasticsearchclient. A integração regista uma instância ElasticsearchClient que pode ser usada para interagir com .

dotnet add package Aspire.Elastic.Clients.Elasticsearch

Adicionar Elasticsearchclient

No arquivo de Program.cs do seu projeto de consumo de client, chame o método de extensão AddElasticsearchClient em qualquer IHostApplicationBuilder para registrar um ElasticsearchClient para uso por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Elasticsearch no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar Elasticsearch recurso.

Em seguida, você pode recuperar a instância ElasticsearchClient usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Adicionar Elasticsearchclient com chave

Pode haver situações em que você queira registrar várias instâncias de ElasticsearchClient com nomes de conexão diferentes. Para registrar clientes de Elasticsearch chaveados, ligue para o AddKeyedElasticsearchClient:

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

Pode-se, em seguida, recuperar as instâncias ElasticsearchClient usando injeção de dependências. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre serviços identificados por chave, consulte sobre .NET injeção de dependência: Serviços identificados por chave.

Configuração

A integração .NET AspireElasticsearchclient fornece várias opções para configurar a conexão server com base nos requisitos e convenções do seu projeto.

Usar uma cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração de ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar builder.AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

Em seguida, a cadeia de conexão será recuperada da seção de configuração ConnectionStrings:

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

Usar provedores de configuração

A integração .NET AspireElasticsearchClient suporta Microsoft.Extensions.Configuration. Ele carrega o ElasticClientsElasticsearchSettings da configuração usando a chave Aspire:Elastic:Clients:Elasticsearch. Considere o exemplo a seguir appsettings.json que configura algumas das opções:

{
  "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 o esquema completo de integração ElasticsearchclientJSON, consulte Aspire.Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Usar delegados embutidos

Além disso, pode passar o delegado de Action<ElasticClientsElasticsearchSettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para definir a chave de API através do código:

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

Use um CloudId e um ApiKey com provedores de configuração

Ao usar o Elastic Cloud, você pode fornecer os CloudId e ApiKey na seção Aspire:Elastic:Clients:Elasticsearch ao chamar builder.AddElasticsearchClient.

builder.AddElasticsearchClient("elasticsearch");

Considere o exemplo a seguir appsettings.json que configura as opções:

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

Utilize um CloudId e um ApiKey com delegados em linha

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

Client verificações de integridade da integração

Por padrão, as integrações .NET.NET Aspire habilitam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral das integrações.

A integração .NET AspireElasticsearch usa o client configurado para executar um PingAsync. Se o resultado for um HTTP 200 OK, a verificação de integridade é considerada saudável; caso contrário, é considerada não saudável. Da mesma forma, se houver uma exceção, a verificação de integridade será considerada não saudável, com o erro a propagar-se através da falha da verificação de integridade.

Observabilidade e telemetria

.NET .NET Aspire integrações automaticamente configuram Registo, Rastreio e Métricas, que às vezes são conhecidos como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na secção Configuração.

Rastreio

A integração .NET AspireElasticsearch emitirá as seguintes atividades de rastreio utilizando OpenTelemetry:

  • Elastic.Transport

Ver também