.NET Aspire RabbitMQ integração

Artigo
12/13/2024

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

RabbitMQ é um agente confiável de mensagens e streaming, que é fácil de implantar em ambientes de nuvem, no local e em sua máquina local. A integração de .NET AspireRabbitMQ permite que você se conecte a instâncias de RabbitMQ existentes ou crie novas instâncias a partir de .NET com a imagem de contêiner docker.io/library/rabbitmq.

Integração de hospedagem

A integração de hospedagem RabbitMQ modela um RabbitMQserver como o tipo RabbitMQServerResource. Para aceder a este tipo e às suas APIs, adicione o pacote NuGet 📦Aspire.Hosting.RabbitMQ no projeto de hospedeiro de aplicações .

.NET CLI
ReferênciaDePacote

dotnet add package Aspire.Hosting.RabbitMQ

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

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

Adicionar RabbitMQserver recurso

Em seu projeto de host de aplicativo, chame AddRabbitMQ na instância builder para adicionar um recurso RabbitMQserver:

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging");

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

// 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/rabbitmq, ele cria uma nova instância de RabbitMQserver em sua máquina local. Uma referência ao seu RabbitMQserver (a variável rabbitmq) é adicionada ao ExampleProject. O recurso RabbitMQserver inclui credenciais padrão com uma username de "guest" e password gerados aleatoriamente usando o método CreateDefaultPasswordParameter.

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

Dica

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

Adicionar RabbitMQserver recurso com plugin de gestão

Para adicionar o de plug-in de gerenciamento de ao recurso , chame o método :

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
                      .WithManagementPlugin();

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

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

O plugin de gerenciamento de RabbitMQ fornece uma API baseada em HTTP para gerenciamento e monitoramento de seus RabbitMQserver. .NET .NET Aspire adiciona outro docker.io/library/rabbitmq-management de imagem de contêiner ao host do aplicativo que executa o plug-in de gerenciamento.

Adicionar o recurso RabbitMQ,server com volume de dados

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

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
                      .WithDataVolume(isReadOnly: false);

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

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

O volume de dados é utilizado para manter os dados RabbitMQserver fora do ciclo de vida do seu contentor. O volume de dados é montado no caminho /var/lib/rabbitmq no contêiner RabbitMQserver e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e porque eles são preferidos em relação a montagens bind , consulte a documentação Docker sobre Volumes.

Adicionar recurso RabbitMQserver com montagem de ligação de dados

Para adicionar uma montagem de ligação de dados ao recurso RabbitMQserver, utilize o método WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
                      .WithDataBindMount(
                          source: @"C:\RabbitMQ\Data",
                          isReadOnly: false);

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

// 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 RabbitMQserver nas reinicializações do contêiner. A montagem da associação de dados é montada no caminho C:\RabbitMQ\Data no Windows (ou /RabbitMQ/Data no Unix) na máquina host no contêiner RabbitMQserver. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

Adicionar RabbitMQserver recurso com parâmetros

Quando quiser fornecer explicitamente o nome de usuário e a senha usados pela imagem do contêiner, você poderá fornecer essas credenciais como parâmetros. Considere o seguinte exemplo alternativo:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var rabbitmq = builder.AddRabbitMQ("messaging", username, password);

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

// 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 da integração de hospedagem

A integração de hospedagem RabbitMQ adiciona automaticamente uma verificação de integridade para o recurso RabbitMQserver. A verificação de integridade verifica se o RabbitMQserver está em execução e se uma conexão pode ser estabelecida com ele.

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

Client integração

Para começar com a integração .NET AspireRabbitMQclient, instale o pacote NuGet 📦Aspire.RabbitMQ.Client no projeto que consome o client, ou seja, o projeto para o aplicativo que usa o RabbitMQclient. A integração RabbitMQclient regista uma instância de IConnection que pode ser utilizada para interagir com RabbitMQ.

.NET CLI
PackageReference

dotnet add package Aspire.RabbitMQ.Client

<PackageReference Include="Aspire.RabbitMQ.Client"
                  Version="*" />

Adicionar RabbitMQclient

No ficheiro de Program.cs do seu projeto que consome client, chame o método de extensão AddRabbitMQClient em qualquer IHostApplicationBuilder para registar um IConnection para uso através do contentor de injeção de dependências. O método usa um parâmetro de nome de conexão.

builder.AddRabbitMQClient(connectionName: "messaging");

Dica

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

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

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

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

Adicionar RabbitMQclient com chave codificada

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

builder.AddKeyedRabbitMQClient(name: "chat");
builder.AddKeyedRabbitMQClient(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")] IConnection chatConnection,
    [FromKeyedServices("queue")] IConnection 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 AspireRabbitMQ fornece várias opções para configurar a conexão 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 de ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar o método AddRabbitMQClient:

builder.AddRabbitMQClient(connectionName: "messaging");

Em seguida, a cadeia de conexão é recuperada da seção de configuração ConnectionStrings:

{
  "ConnectionStrings": {
    "messaging": "amqp://username:password@localhost:5672"
  }
}

Para obter mais informações sobre como formatar essa cadeia de conexão, consulte os documentos de especificação de URI RabbitMQ.

Usar provedores de configuração

A integração .NET AspireRabbitMQ suporta Microsoft.Extensions.Configuration. Ele carrega o RabbitMQClientSettings da configuração usando a chave Aspire:RabbitMQ:Client. O trecho a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

{
  "Aspire": {
    "RabbitMQ": {
      "Client": {
        "ConnectionString": "amqp://username:password@localhost:5672",
        "DisableHealthChecks": true,
        "DisableTracing": true,
        "MaxConnectRetryCount": 2
      }
    }
  }
}

Para o esquema completo de integração RabbitMQclientJSON, consulte Aspire.RabbitMQ.Client/ConfigurationSchema.json.

Usar delegados embutidos

Além disso, poderá passar o Action<RabbitMQClientSettings> configureSettings delegate para configurar algumas ou todas as opções diretamente no código, por exemplo, para desativar os health checks a partir do código:

builder.AddRabbitMQClient(
    "messaging",
    static settings => settings.DisableHealthChecks = true);

Você também pode configurar o IConnectionFactory usando o parâmetro Action<IConnectionFactory> configureConnectionFactory delegate do método AddRabbitMQClient. Por exemplo, para definir o nome client fornecido para conexões:

builder.AddRabbitMQClient(
    "messaging",
    configureConnectionFactory:
        static factory => factory.ClientProvidedName = "MyApp");

Client verificações de integridade 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 AspireRabbitMQ:

Adiciona a verificação de integridade quando RabbitMQClientSettings.DisableHealthChecks é false, que tenta se conectar e criar um canal no RabbitMQserver.
Integra-se com o endpoint HTTP /health, que especifica que todas as verificações de integridade registadas devem passar para que a aplicação seja considerada pronta para aceitar tráfego.

Observabilidade e telemetria

As integrações .NET.NET Aspire configuram automaticamente Logging, Tracing, e Metrics, que às vezes são conhecidos 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 secção de configuração , secção.

Registo

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

RabbitMQ.Client

Rastreio

A integração .NET AspireRabbitMQ emite as seguintes atividades de rastreio utilizando OpenTelemetry:

Aspire.RabbitMQ.Client

Métricas

Atualmente, a integração .NET AspireRabbitMQ não suporta métricas por padrão.

Partilhar via