.NET Aspire RabbitMQ 集成

项目
01/23/2025

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

托管集成

托管集成 RabbitMQ 将 RabbitMQ 服务器建模为 RabbitMQServerResource 类型。若要访问此类型及其 API，请在 📦 项目中添加 AspireRabbitMQ.Hosting. NuGet 包。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.RabbitMQ

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

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

添加 RabbitMQ 服务器资源

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

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 映像，它会在本地计算机上创建新的 RabbitMQ 服务器实例。将对 RabbitMQ 服务器（rabbitmq 变量）的引用添加至 ExampleProject。 RabbitMQ 服务器资源包括具有 username"guest" 的默认凭据，并使用 password 方法随机生成 CreateDefaultPasswordParameter。

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

提示

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

使用管理插件添加 RabbitMQ 服务器资源

若要将 RabbitMQ 管理插件添加到 RabbitMQ 服务器资源，请调用 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，用于管理和监视 RabbitMQ 服务器。 .NET .NET Aspire 向运行管理插件的应用主机添加另一个容器映像 docker.io/library/rabbitmq-management。

使用数据卷添加 RabbitMQ 服务器资源

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

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

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

使用数据绑定挂载来添加 RabbitMQ 服务器资源

若要将数据绑定挂载添加到 RabbitMQ 服务器资源，请调用 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...

重要

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

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

使用参数添加 RabbitMQ 服务器资源

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

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 托管集成会自动为 RabbitMQ 服务器资源添加运行状况检查。运行状况检查验证 RabbitMQ 服务器是否正在运行，并且可以建立与服务器的连接。

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

Client 集成

若要开始 .NET AspireRabbitMQ 客户端集成，请在使用客户端的项目中安装 📦Aspire。RabbitMQ。Client NuGet 包，即使用 RabbitMQ 客户端的应用程序对应的项目。 RabbitMQ 客户端集成注册了一个 IConnection 实例，该实例可用于与 RabbitMQ交互。

.NET CLI
PackageReference

dotnet add package Aspire.RabbitMQ.Client

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

添加 RabbitMQ 客户端

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

builder.AddRabbitMQClient(connectionName: "messaging");

提示

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

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

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

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

添加加密的 RabbitMQ 客户端

在某些情况下，可能需要使用不同的连接名称注册多个 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。使用 RabbitMQClientSettings 键从配置中加载 Aspire:RabbitMQ:Client。以下是一个 appsettings.json 文件的示例，它配置了某些选项：

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

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

使用内联委托

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

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

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

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

Client 集成运行状况检查

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

.NET Aspire RabbitMQ 集成：

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

可观测性和遥测

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

伐木

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

RabbitMQ.Client

追踪

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

Aspire.RabbitMQ.Client

指标

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

通过