integración de .NET AspireRabbitMQ

Artículo
12/12/2024

Incluye:integración de hospedaje y Client integración

RabbitMQ es un agente de streaming y mensajería confiable, que es fácil de implementar en entornos en la nube, locales y en el equipo local. La integración de .NET AspireRabbitMQ permite conectarse a instancias de RabbitMQ existentes o crear nuevas instancias a partir de .NET con la imagen de contenedor docker.io/library/rabbitmq.

Integración de hospedaje

La integración de RabbitMQ aloja modelos RabbitMQserver como tipo RabbitMQServerResource. Para acceder a este tipo y sus APIs, agregue el paquete NuGet 📦Aspire.Hosting.RabbitMQ en el proyecto de host de la aplicación .

.NET CLI
ReferenciaDePaquete

dotnet add package Aspire.Hosting.RabbitMQ

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

Para obtener más información, consulte dotnet add package o Manage package dependencies in .NET applications.

Agregar RabbitMQserver recurso

En el proyecto host de la aplicación, llame a AddRabbitMQ en la instancia de builder para agregar un recurso de RabbitMQserver:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/library/rabbitmq, crea una nueva instancia de RabbitMQserver en el equipo local. Se ha añadido una referencia a su RabbitMQserver (la variable rabbitmq) en el ExampleProject. El recurso RabbitMQserver incluye credenciales predeterminadas con un username de "guest" y password generados aleatoriamente mediante el método CreateDefaultPasswordParameter.

El método WithReference configura una conexión en el ExampleProject denominado "messaging". Para obtener más información, consulte el ciclo de vida del recurso del contenedor .

Propina

Si prefiere conectarse a un RabbitMQserverexistente, llame a AddConnectionString en su lugar. Para obtener más información, vea Hacer referencia a los recursos existentes.

Añadir recurso RabbitMQserver con el complemento de administración

Para agregar el plugin de administración RabbitMQ al recurso RabbitMQserver, llame al método WithManagementPlugin:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

El complemento de administración de RabbitMQ proporciona una API basada en HTTP para la administración y monitoreo de la RabbitMQserver. .NET .NET Aspire agrega otra imagen de contenedor docker.io/library/rabbitmq-management al host de la aplicación que ejecuta el complemento de administración.

Añadir recurso RabbitMQserver con un volumen de datos

Para agregar un volumen de datos al recurso de RabbitMQserver, llame al método WithDataVolume en el 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...

El volumen de datos se usa para persistir los datos de RabbitMQserver fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta de acceso /var/lib/rabbitmq del contenedor de RabbitMQserver y, cuando no se proporciona un parámetro name, el nombre se genera de forma aleatoria. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a enlazar montajes, consulte Docker documentos: Volúmenes.

Adición de recurso RabbitMQserver con montaje de vinculación de datos

Para agregar un montaje de enlace de datos al recurso de RabbitMQserver, llame al 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

Los montajes de enlace de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen mejor rendimiento, portabilidad y seguridad, por lo que son más apropiados para entornos de producción. Sin embargo, los montajes enlazados permiten el acceso directo y la modificación de archivos en el sistema host, ideal para el desarrollo y las pruebas donde los cambios en tiempo real son necesarios.

Los montajes de vinculación de datos dependen del sistema de archivos de la máquina host para conservar los datos de RabbitMQserver en los reinicios del contenedor. En el contenedor de RabbitMQserver, se monta el enlace de datos en el C:\RabbitMQ\Data en Windows (o el /RabbitMQ/Data en Unix) en la ruta en el equipo host. Para obtener más información sobre los montajes de enlace, consulte los documentos de Docker: Montajes de enlace.

Agregar recurso RabbitMQserver con parámetros

Si desea proporcionar explícitamente el nombre de usuario y la contraseña usados por la imagen de contenedor, puede proporcionar estas credenciales como parámetros. Considere el siguiente ejemplo 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 obtener más información sobre cómo proporcionar parámetros, consulte Parámetros externos.

Verificación de salud de la integración de hospedaje

La integración de alojamiento RabbitMQ agrega automáticamente una comprobación de estado para el recurso RabbitMQserver. La comprobación de estado comprueba que el RabbitMQserver está en funcionamiento y que se puede establecer una conexión con él.

La integración de hospedaje se basa en el 📦 AspNetCore.HealthChecks.Rabbitmq paquete NuGet.

integración de Client

Para empezar a trabajar con la integración de .NET AspireRabbitMQclient, instale el paquete NuGet 📦Aspire.RabbitMQ.Client en el proyecto clientque consume, es decir, en el proyecto de la aplicación que usa el RabbitMQclient. La integración de RabbitMQclient registra una instancia de IConnection que se puede usar para interactuar con RabbitMQ.

.NET CLI
ReferenciaDePaquete

dotnet add package Aspire.RabbitMQ.Client

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

Agregar RabbitMQclient

En el archivo Program.cs del proyecto que consume client, invoca al método de extensión AddRabbitMQClient en cualquier IHostApplicationBuilder para registrar un IConnection para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddRabbitMQClient(connectionName: "messaging");

Propina

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso RabbitMQserver en el proyecto host de la aplicación. Para obtener más información, consulte Agregar RabbitMQserver recurso.

A continuación, puede recuperar la instancia de IConnection mediante la inserción de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

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

Para obtener más información sobre la inserción de dependencias, consulte .NET inserción de dependencias.

Agregar RabbitMQclient con clave

Puede haber situaciones en las que quiera registrar varias instancias de IConnection con nombres de conexión diferentes. Para registrar clientes de RabbitMQ con clave, llame al método AddKeyedRabbitMQClient:

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

A continuación, puede recuperar las instancias de IConnection mediante inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

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

Para obtener más información sobre los servicios con claves, consulte .NET inserción de dependencias: Servicios con claves.

Configuración

La integración de .NET AspireRabbitMQ proporciona varias opciones para configurar la conexión en función de los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar al método AddRabbitMQClient:

builder.AddRabbitMQClient(connectionName: "messaging");

A continuación, se obtiene la cadena de conexión de la sección de configuración ConnectionStrings.

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

Para obtener más información sobre cómo dar formato a esta cadena de conexión, consulte los documentos de especificación de URI de RabbitMQ.

Uso de proveedores de configuración

La integración de .NET AspireRabbitMQ admite Microsoft.Extensions.Configuration. Carga el RabbitMQClientSettings desde la configuración mediante la clave Aspire:RabbitMQ:Client. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:

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

Para obtener el esquema de integración completo RabbitMQclientJSON, consulte Aspire.RabbitMQ.Client/ConfigurationSchema.json.

Usar delegados insertados

También puede pasar el delegado de Action<RabbitMQClientSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar las comprobaciones de estado desde el código:

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

También puede configurar el IConnectionFactory mediante el parámetro de delegado del método . Por ejemplo, para establecer el nombre client proporcionado para las conexiones:

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

Comprobaciones de estado de la integración Client

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan las comprobaciones de estado de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

La integración de .NET AspireRabbitMQ:

Agrega la comprobación de estado cuando RabbitMQClientSettings.DisableHealthChecks es false, la cual intenta conectarse y crear un canal en el RabbitMQserver.
Se integra con el punto de conexión HTTP de /health, que especifica que todas las comprobaciones de estado registradas deben superarse para que la aplicación se considere lista para aceptar tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo admiten algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar utilizando las técnicas presentadas en la sección Configuración.

Registro

La integración de .NET AspireRabbitMQ usa las siguientes categorías de registro:

RabbitMQ.Client

Rastreo

La integración de .NET AspireRabbitMQ emite las siguientes actividades de seguimiento mediante OpenTelemetry:

Aspire.RabbitMQ.Client

Métricas

La integración de .NET AspireRabbitMQ actualmente no admite métricas de forma predeterminada.

Compartir a través de