Partilhar via

.NET Aspire NATS integração

  • Artigo

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

NATS é um sistema de mensagens distribuído, seguro e de alto desempenho. A integração de .NET AspireNATS permite que você se conecte a instâncias de NATS existentes ou crie novas instâncias a partir 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 servidor NATS como o tipo NatsServerResource. Para aceder a este tipo, instale o pacote NuGet 📦Aspire.Hosting.Nats no projeto de hospedagem app host e adicione-o ao builder.

dotnet add package Aspire.Hosting.Nats

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

Adicionar NATS recurso do servidor

Em seu projeto de host de 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, como mostrado no exemplo anterior com a imagem docker.io/library/nats, ele cria uma nova instância do servidor NATS em sua máquina local. Uma referência ao seu servidor NATS (a variável nats) é adicionada ao ExampleProject.

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

Dica

Se você preferir se conectar a um servidor NATS existente, ligue para AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a recursos existentes.

Adicionar o recurso de servidor NATS com o JetStream

Para adicionar o NATS JetStream ao recurso do 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 integrado 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 na máquina host (o caminho de montagem fornecido mapeia para o argumento -sd do contêiner).

Adicionar o recurso do servidor NATS com volume de dados

Para adicionar um volume de dados ao recurso do servidor NATS, chame o método WithDataVolume no recurso do 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 manter 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 são preferidos em relação a montagens bind , consulte a documentação Docker: Volumes.

Adicionar NATS recurso de servidor com montagem de associação de dados

Para adicionar uma montagem de ligação de dados ao recurso do 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 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 vínculo de dados dependem do sistema de arquivos da máquina host para manter os dados do servidor NATS durante reinicializações do contêiner. A montagem de associação de dados é montada no C:\NATS\Data no caminho do Windows (ou /NATS/Data no Unix) na máquina host no contêiner do servidor NATS. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

Verificações de integridade da 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.

Client integração

Para começar com a integração do cliente .NET AspireNATS, instale o pacote NuGet 📦Aspire.NATS.Net no projeto que consome o cliente, isto é, o projeto para a aplicação que usa o cliente NATS. A integração do cliente NATS regista uma instância de INatsConnection que pode ser usada para interagir com NATS.

dotnet add package Aspire.NATS.Net

Adicionar NATS cliente

No ficheiro Program.cs do seu projeto cliente-consumidor, chame o método de extensão AddNatsClient em qualquer IHostApplicationBuilder para registar um INatsConnection para ser utilizado através do contentor 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 Adicionar NATS recurso de servidor.

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

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

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

Em seguida, você pode recuperar as instâncias IConnection usando a injeção de dependência. 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 com chave, consulte .NET injeção de dependência: Serviços com chave.

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 quando você chamar builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

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

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

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

Usar provedores de configuração

A integração .NET AspireNATS suporta Microsoft.Extensions.Configuration. Ele carrega o NatsClientSettings da configuração usando a tecla Aspire:Nats:Client. O trecho 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 consultar o esquema completo de integração de cliente NATSJSON, veja 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 desativar as verificações de integridade através do código:

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

NATS no manifesto de .NET Aspire

NATS não faz parte do manifesto de implementação .NET Aspire. É recomendável configurar um servidor seguro de produção NATS fora de .NET Aspire.

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

  • Integra-se com o ponto de extremidade HTTP /health, que especifica que todas as verificações do estado de saúde registadas devem ser concluídas com sucesso para que a aplicação seja considerada pronta para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas 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 seção de configuração .

Registo

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

  • NATS

Rastreio

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

  • NATS.Net

Ver também