Compartilhar via

integração .NET AspireNATS

  • Artigo

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

NATS é um sistema de mensagens distribuído, seguro e de alto desempenho. A integração .NET AspireNATS permite que você se conecte a instâncias de NATS existentes ou crie novas instâncias de .NET com a imagem de contêiner docker.io/library/nats.

Integração de hospedagem

NATS integração de hospedagem para .NET Aspire modela um NATSserver como o tipo de NatsServerResource. Para acessar esse tipo, instale o pacote NuGet 📦Aspire.Hosting.Nats no projeto de host do aplicativo e adicione-o ao construtor.

dotnet add package Aspire.Hosting.Nats

Para obter mais informações, consulte dotnet add package or Manage package dependencies in .NET applications.

Adicionar NATSserver recurso

No projeto de host do aplicativo, chame AddNats na instância builder para adicionar um recurso de NATSserver:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");

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

// 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/nats, ele cria uma nova instância NATSserver no computador local. Uma referência ao NATSserver (a variável nats) é adicionada ao ExampleProject.

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

Dica

Se você preferir se conectar a um NATSserverexistente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar NATSserver recurso com o JetStream

Para adicionar o NATS JetStream ao recurso NATSserver, chame o método WithJetStream:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithJetStream();

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

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

A funcionalidade NATS JetStream fornece um mecanismo de persistência interno chamado JetStream que permite que as mensagens sejam armazenadas e reproduzidas posteriormente. Opcionalmente, você pode fornecer um parâmetro srcMountPath para especificar o caminho para o diretório de dados JetStream no computador host (o caminho de montagem fornecido é mapeado para o argumento -sd do contêiner).

Adicionar NATSserver recurso com volume de dados

Para adicionar um volume de dados ao recurso NATSserver, chame o método WithDataVolume no recurso NATSserver:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataVolume(isReadOnly: false);

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

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

O volume de dados é usado para persistir os dados NATSserver fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /var/lib/nats no contêiner NATSserver. Um nome é gerado aleatoriamente, a menos que você forneça um conjunto do parâmetro name. 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 NATSserver com montagem de ligação de dados

Para adicionar uma montagem de associação de dados ao recurso NATSserver, chame o método WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataBindMount(
                      source: @"C:\NATS\Data",
                      isReadOnly: false);

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

// 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 vinculadas permitem acesso direto e modificação de arquivos no sistema host, sendo ideal para desenvolvimento e teste, onde alterações em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos do computador host para persistir os dados NATSserver entre reinicializações de contêiner. A montagem da associação de dados é montada no caminho C:\NATS\Data no Windows (ou /NATS/Data no Unix) no computador host no contêiner NATSserver. Para obter mais informações sobre montagens de associação de dados, consulte Docker documentos: Associar montagens.

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

A integração de hospedagem NATS adiciona automaticamente uma verificação de integridade para o recurso NATSserver. A checagem de saúde verifica se o NATSserver está em execução e se uma conexão pode ser estabelecida com ele.

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

integração Client

Para começar a usar a integração .NET AspireNATSclient, instale o 📦Aspire.NATSpacote NuGet do .Net no projeto que consome client, ou seja, o projeto do aplicativo que usa o NATSclient. A integração NATSclient registra uma instância de INatsConnection que você pode usar para interagir com NATS.

dotnet add package Aspire.NATS.Net

Adicionar NATSclient

No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddNatsClient em qualquer IHostApplicationBuilder para registrar um INatsConnection 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.AddNatsClient(connectionName: "nats");

Dica

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

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

public class ExampleService(INatsConnection connection)
{
    // Use connection...
}

Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar NATSclient com chave

Pode haver situações em que você deseja registrar várias instâncias de INatsConnection com nomes de conexão diferentes. Para registrar clientes chaveados de NATS, chame o método AddKeyedNatsClient:

builder.AddKeyedNatsClient(name: "chat");
builder.AddKeyedNatsClient(name: "queue");

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

public class ExampleService(
    [FromKeyedServices("chat")] INatsConnection chatConnection,
    [FromKeyedServices("queue")] INatsConnection queueConnection)
{
    // Use connections...
}

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

Configuração

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

Usar uma cadeia de conexão

Forneça o nome da cadeia de conexão ao chamar builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

A cadeia de conexão é recuperada da seção de configuração do ConnectionStrings:

{
  "ConnectionStrings": {
    "nats": "nats://nats:4222"
  }
}

Consulte a documentação ConnectionString para obter mais informações sobre como formatar essa cadeia de conexão.

Usar provedores de configuração

A integração .NET AspireNATS dá suporte a Microsoft.Extensions.Configuration. Ele carrega a NatsClientSettings da configuração usando a chave Aspire:Nats:Client. O snippet a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

{
  "Aspire": {
    "Nats": {
      "Client": {
        "ConnectionString": "nats://nats:4222",
        "DisableHealthChecks": true,
        "DisableTracing": true
      }
    }
  }
}

Para o esquema de integração completo NATSclientJSON, consulte Aspire.NATS.Net/ConfigurationSchema.json.

Usar delegados embutidos

Passe o delegado Action<NatsClientSettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para desabilitar verificações de integridade através do código.

builder.AddNatsClient(
    "nats",
    static settings => settings.DisableHealthChecks  = true);

NATS no manifesto .NET Aspire

NATS não faz parte do manifesto de implantação .NET Aspire. É recomendável que você configure um NATSserver de produção seguro fora do .NET Aspire.

Client verificações de integridade 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 AspireNATS lida com o seguinte:

  • Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade já registradas devem passar para que o aplicativo seja considerado pronto para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente Registro, Rastreamento e Métricas, que às vezes são conhecidos 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.

Registro de Logs

A integração .NET AspireNATS usa as seguintes categorias de log:

  • NATS

Rastreamento

A integração .NET AspireNATS emite as seguintes atividades de rastreamento:

  • NATS.Net

Consulte também