.NET Aspire RabbitMQ 整合

發行項
01/31/2025

RabbitMQ 是可靠的傳訊和串流代理程式，可讓您輕鬆地在雲端環境、內部部署和本機計算機上部署。 .NET Aspire RabbitMQ 整合可讓您連線到現有的 RabbitMQ 實例，或使用 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);

您也可以使用 AddRabbitMQClient 方法的 Action<IConnectionFactory> configureConnectionFactory 委派參數來設定 IConnectionFactory。例如，若要為連線設定用戶端提供的名稱：

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 Aspire RabbitMQ 整合目前預設不支援計量。

共用方式為