.NET Aspire RabbitMQ 整合

發行項
12/12/2024

RabbitMQ 是可靠的傳訊和串流代理程式，可讓您輕鬆地在雲端環境、內部部署和本機計算機上部署。 .NET Aspire RabbitMQ 整合可讓您連線到現有的 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 實例。 RabbitMQ server 的參照（rabbitmq 變數）已新增至 ExampleProject。 RabbitMQ server 資源包含默認帳戶憑證，具有 username 為 "guest"，並使用 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 數據。資料繫結掛載會安裝在 RabbitMQserver 容器內主機的 C:\RabbitMQ\Data 路徑上（或 Unix的 /RabbitMQ/Data）之上。如需資料系結掛接的詳細資訊，請參閱 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 整合，請在 client取用專案中安裝 📦Aspire。RabbitMQ。Client NuGet 套件，這個專案即是用於使用 RabbitMQclient的應用程式。 RabbitMQ client 整合會註冊 IConnection 實例，讓您可用來與 RabbitMQ互動。

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

共用方式為