.NET Aspire RabbitMQ 集成

项目
12/15/2024

RabbitMQ 是一个可靠的消息传送和流式处理代理，可在云环境、本地和本地计算机上轻松部署。通过 .NET AspireRabbitMQ 集成，可以连接到现有 RabbitMQ 实例，或使用 docker.io/library/rabbitmq 容器映像从 .NET 创建新实例。

托管集成

托管集成 RabbitMQ 将 RabbitMQserver 建模为 RabbitMQServerResource 类型。若要访问此类型及其 API，请在应用主机项目中添加 📦Aspire.Hosting.RabbitMQ NuGet 包。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.RabbitMQ

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

有关详细信息，请参阅 dotnet add package 或管理包依赖性在 .NET 应用程序。

添加 RabbitMQserver 资源

在应用主机项目中，对 builder 实例调用 AddRabbitMQ 以添加 RabbitMQserver 资源：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

当 .NET.NET Aspire 向应用主机添加容器映像时，如上例中所示的 docker.io/library/rabbitmq 映像，它会在本地计算机上创建新的 RabbitMQserver 实例。将对 RabbitMQserver（rabbitmq 变量）的引用添加到 ExampleProject。 RabbitMQ server 资源包括具有 "guest"username 的默认凭据，并使用 CreateDefaultPasswordParameter 方法随机生成 password。

WithReference 方法在名为 "messaging"的 ExampleProject 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

如果想要连接到现有 RabbitMQserver，请改为调用 AddConnectionString。有关详细信息，请参阅引用现有资源。

使用管理插件添加 RabbitMQserver 资源

若要将 RabbitMQ 管理插件添加到 RabbitMQserver 资源，请调用 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...

RabbitMQ 管理插件提供基于 HTTP 的 API，用于对 RabbitMQserver的管理与监控。 .NET .NET Aspire 向运行管理插件的应用主机添加另一个容器映像 docker.io/library/rabbitmq-management。

使用数据卷添加 RabbitMQserver 资源

若要将数据卷添加到 RabbitMQserver 资源，请在 RabbitMQserver 资源上调用 WithDataVolume 方法：

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...

数据卷用于在容器的生命周期之外保留 RabbitMQserver 数据。数据卷装载在 RabbitMQserver 容器中的 /var/lib/rabbitmq 路径上，如果未提供 name 参数，则会随机生成名称。有关数据卷的更多信息，以及它们为何优于绑定挂载的原因，请参阅 Docker 文档：卷。

添加具有数据绑定挂载的 RabbitMQserver 资源

若要向 RabbitMQserver 资源添加数据绑定挂载，请使用 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...

重要

与卷相比，绑定装载的数据功能有限，从而提供更好的性能、可移植性和安全性，使它们更适用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定挂载依赖于主机的文件系统，以便在容器重启时保留 RabbitMQserver 数据。数据绑定挂载在主机的 Windows 路径 C:\RabbitMQ\Data（或 Unix上的 /RabbitMQ/Data）上的 RabbitMQserver 容器中。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

使用参数添加 RabbitMQserver 资源

如果要显式提供容器映像使用的用户名和密码，可以将这些凭据作为参数提供。请考虑以下替代示例：

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...

有关提供参数的详细信息，请参阅外部参数。

托管集成运行状况检查

托管集成 RabbitMQ 会自动为 RabbitMQserver 资源添加运行状况检查。运行状况检查会验证 RabbitMQserver 是否正在运行，并确认是否可以建立连接。

托管集成依赖于 📦 的 AspNetCore.HealthChecks 和Rabbitmq 的 NuGet 包。

Client 集成

若要开始 .NET AspireRabbitMQclient 集成，请安装 📦Aspire。RabbitMQ。Client 使用 client项目中的 NuGet 包，即使用 RabbitMQclient的应用程序的项目。 RabbitMQ client 集成会注册一个供您用于与 RabbitMQ交互的 IConnection 实例。

.NET CLI
PackageReference

dotnet add package Aspire.RabbitMQ.Client

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

添加 RabbitMQclient

在 client消耗项目的 Program.cs 文件中，对任何 IHostApplicationBuilder 调用 AddRabbitMQClient 扩展方法，以注册 IConnection，以便通过依赖项注入容器使用。该方法采用连接名称参数。

builder.AddRabbitMQClient(connectionName: "messaging");

提示

connectionName 参数必须与在应用主机项目中添加 RabbitMQserver 资源时使用的名称匹配。有关详细信息，请参阅添加 RabbitMQserver 资源。

然后，可以使用依赖项注入检索 IConnection 实例。例如，若要从示例服务检索连接，

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

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加键 RabbitMQclient

在某些情况下，可能需要使用不同的连接名称注册多个 IConnection 实例。若要注册密钥 RabbitMQ 客户端，请调用 AddKeyedRabbitMQClient 方法：

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

然后，可以使用依赖项注入检索 IConnection 实例。例如，若要从示例服务检索连接，

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

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

.NET Aspire RabbitMQ 集成提供了多个选项，用于根据项目的要求和约定配置连接。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 AddRabbitMQClient 方法时提供连接字符串的名称：

builder.AddRabbitMQClient(connectionName: "messaging");

然后，从 ConnectionStrings 配置部分检索连接字符串：

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

有关如何设置此连接字符串格式的详细信息，请参阅 RabbitMQ URI 规范文档。

使用配置提供程序

.NET Aspire RabbitMQ 集成支持 Microsoft.Extensions.Configuration。使用 Aspire:RabbitMQ:Client 键从配置中加载 RabbitMQClientSettings。以下是一个 appsettings.json 文件的示例，它配置了某些选项：

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

有关完整的 RabbitMQclient 集成 JSON 架构，请参阅 Aspire。RabbitMQ。Client/ConfigurationSchema。json。

使用内联委托

还可以传递 Action<RabbitMQClientSettings> configureSettings 委托来设置一些或所有内联选项，例如禁用代码中的运行状况检查：

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

可以通过 AddRabbitMQClient 方法的 Action<IConnectionFactory> configureConnectionFactory 委托参数来设置 IConnectionFactory。例如，设置 client 为连接提供的名称：

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

Client 集成运行状况检查

默认情况下，.NET.NET Aspire 集成为所有服务启用健康检查。有关详细信息，请参阅 .NET.NET Aspire 集成概述。

.NET Aspire RabbitMQ 集成：

添加健康检查，当 RabbitMQClientSettings.DisableHealthChecks 是 false时，该检查尝试连接至 RabbitMQserver并创建通道。
与 /health HTTP 终结点集成，该终结点要求所有已注册的健康检查必须通过，应用才能被视为可以接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时被称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire RabbitMQ 集成使用以下日志类别：

RabbitMQ.Client

追踪

.NET Aspire RabbitMQ 集成使用 OpenTelemetry发出以下跟踪活动：

Aspire.RabbitMQ.Client

指标

默认情况下，.NET AspireRabbitMQ 集成不支持指标。

通过