integração .NET AspireElasticsearch

Inclui:integração de hospedagem e integraçãoClient

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

Integração de hospedagem

O modelo de integração de hospedagem Elasticsearch modela a instância Elasticsearch como tipo ElasticsearchResource. Para acessar esse tipo e as APIs que permitem adicioná-lo ao seu pacote NuGet de hospedagemAspire. 📦Elasticsearch no projeto host do aplicativo .

.NET CLI

dotnet add package Aspire.Hosting.Elasticsearch

PackageReference

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

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

Adicionar Elasticsearch recurso

No projeto de host do aplicativo, chame AddElasticsearch na instância builder para adicionar um 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...

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

O método WithReference configura uma conexão no ExampleProject denominado "elasticsearch". Para obter mais informações, consulte ciclo de vida do recurso 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 Referenciar 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 persistir os dados de Elasticsearch fora do ciclo de vida do 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 eles são preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Adicionar recurso Elasticsearch com montagem vinculada de dados

Para adicionar um ponto de montagem de vínculo de dados ao recurso Elasticsearch, utilize 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 de dados associam montagens 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 acesso direto e modificação de arquivos no sistema host, ideal para desenvolvimento e teste que exigem alterações em tempo real.

Montagens de dados com vínculo dependem do sistema de arquivos da máquina host para manter os dados Elasticsearch entre reinicializações de contêineres. No contêiner Elasticsearch, o ponto de montagem de dados é montado no caminho C:\Elasticsearch\Data no Windows (ou /Elasticsearch/Data no Unix) na máquina host. Para obter mais informações sobre montagens de vínculos de dados, consulte a documentação Docker: Montagens de associação.

Adicionar o recurso Elasticsearch com o parâmetro de senha

Quando quiser fornecer explicitamente a senha usada pela imagem de contêiner, você pode 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 de integração de hospedagem

A integração de hospedagem Elasticsearch adiciona automaticamente uma verificação de integridade para o recurso de Elasticsearch. A verificação de integridade verifica se a instância de 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.

integração Client

Para começar a usar a integração .NET AspireElasticsearchclient, instale o 📦Aspire. Elastic.Clients.Elasticsearch pacote NuGet no projeto que consome client, ou seja, o projeto do aplicativo que usa o Elasticsearchclient. A integração Elasticsearchclient registra uma instância de ElasticsearchClient , a qual você pode usar para interagir com Elasticsearch.

.NET CLI

dotnet add package Aspire.Elastic.Clients.Elasticsearch

PackageReference

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

Adicionar Elasticsearchclient

No arquivo Program.cs do seu projeto que consome 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 recurso Elasticsearch.

Em seguida, você pode usar a injeção de dependência para recuperar a instância de ElasticsearchClient. 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ê deseja registrar várias instâncias de ElasticsearchClient com nomes de conexão diferentes. Para registrar clientes chaveados Elasticsearch, chame o AddKeyedElasticsearchClient.

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

Em seguida, você pode recuperar as instâncias de ElasticsearchClient usando a injeção de dependência. 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 com chave, consulte .NET injeção de dependência: serviços com 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 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 dá suporte a Microsoft.Extensions.Configuration. Ele carrega o ElasticClientsElasticsearchSettings da configuração utilizando 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 em linha

Além disso, você pode passar o delegado Action<ElasticClientsElasticsearchSettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para definir a chave de API a partir 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 Nuvem Elástica, você pode fornecer o 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>"
        }
      }
    }
  }
}

Usar um CloudId e um ApiKey com delegados embutidos

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

Client checagens de saúde de 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 de integrações.

A integração .NET AspireElasticsearch usa o client configurado para executar um PingAsync. Se o resultado for um HTTP 200 OK, a checagem de saúde é 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 íntegra com o erro propagado por meio da falha de verificação de integridade.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Rastreamento

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

• Elastic.Transport

Consulte também

• Elasticsearch .NET
• integrações .NET.NET Aspire
• .NET Aspire GitHub repo