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 modelos .NET Aspire um NATSserver como o tipo NatsServerResource. Para aceder a este tipo, instale o 📦Aspire.Hosting.Nats pacote NuGet no projeto anfitrião da app e adicione-o com o construtor.

dotnet add package Aspire.Hosting.Nats

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

Adicionar NATSserver recurso

Em seu projeto de host de aplicativo, chame AddNats na instância builder para adicionar um recurso 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, como mostrado no exemplo anterior com a imagem docker.io/library/nats, ele cria uma nova instância de NATSserver em sua máquina local. Uma referência ao seu NATSserver (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 preferir conectar-se a um NATSserverexistente, ligue para AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a 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 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 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 manter os NATSserver dados 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 são preferidos em relação a montagens bind , consulte a documentação Docker: 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 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 NATSserver nas reinicializações do contêiner. A montagem da associação de dados é montada no caminho C:\NATS\Data no Windows (ou /NATS/Data no Unix) na máquina host no contêiner NATSserver. 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 NATSserver. A verificação de integridade 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.

Client integração

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

dotnet add package Aspire.NATS.Net

Adicionar NATSclient

No arquivo de Program.cs do seu projeto que consome client, chame o método de extensão AddNatsClient em qualquer IHostApplicationBuilder para registar 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 NATSserver recurso.

Em seguida, você pode recuperar a instância INatsConnection usando a injeção de dependência. 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ê 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 obter o esquema de integração completa 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 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 NATSserver de produção seguro 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