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

Integração de hospedagem NATS para .NET Aspire modela um servidor NATS como tipo NatsServerResource. Para acessar esse tipo, instale o pacote NuGet 📦Aspire.Hosting.Nats no projeto do host do aplicativo e, em seguida, adicione-o com o builder.

dotnet add package Aspire.Hosting.Nats

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

Adicionar NATS recurso de servidor

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

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 de servidor NATS no computador local. Uma referência ao servidor NATS (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 servidor NATS existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar recurso de servidor NATS com JetStream

Para adicionar o JetStream NATS ao servidor NATS, 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 NATS recurso de servidor com volume de dados

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

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 do servidor NATS fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /var/lib/nats no contêiner do servidor NATS. 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 o recurso de servidor NATS com montagem de dados bind

Para adicionar uma montagem de associação de dados ao recurso de servidor NATS, 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 dados dependem do sistema de arquivos da máquina host para manter os dados do servidor NATS durante reinicializações de contêiner. A montagem da associação de dados é montada no C:\NATS\Data no caminho do Windows (ou /NATS/Data no Unix) no computador host no contêiner do servidor NATS. 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 de servidor NATS. A verificação de integridade verifica se o servidor NATS está em execução e se uma conexão pode ser estabelecida com ele.

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

integração Client

Para começar a usar a integração do cliente .NET AspireNATS, instale o pacote NuGet 📦Aspire.NATS.Net no projeto que consome o cliente, ou seja, o projeto para o aplicativo que utiliza o cliente NATS. A integração do cliente NATS registra uma instância INatsConnection que você pode usar para interagir com NATS.

dotnet add package Aspire.NATS.Net

Adicionar NATS cliente

No arquivo Program.cs do projeto que consome o cliente, 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 de servidor NATS no projeto de host do aplicativo. Para obter mais informações, consulte NATSde recursos do servidor .

Em seguida, você pode usar a injeção de dependência para recuperar a instância INatsConnection. Por exemplo, para recuperar o cliente 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 cliente com chave NATS

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 obter o esquema NATS de integração completa do cliente JSON, 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 servidor NATS 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