.NET Aspire Azure Service Bus 整合

發行項
02/27/2025

包括： 主機托管整合和 Client 整合

Azure Service Bus 是完全受控的企業訊息代理程式，其中包含消息佇列和發佈-訂閱主題。 .NET Aspire Azure Service Bus 整合可讓您從 .NET 應用程式連線到 Azure Service Bus 實例。

託管整合

託管整合 .NET.NET AspireAzure Service Bus 模型化各種服務總線資源為下列類型：

AzureServiceBusResource：代表 Azure Service Bus 資源。
AzureServiceBusEmulatorResource：代表 Azure Service Bus 模擬器資源。

若要存取這些型別和 API 來表示它們，請在應用程式主機專案中新增 📦Aspire.Hosting.Azure.ServiceBus 的 NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

如需詳細資訊，請參閱 dotnet add package 或在 .NET 應用程式中管理套件相依性。

新增 Azure Service Bus 資源

在您的應用程式主專案中，呼叫 AddAzureServiceBus 以新增並傳回 Azure Service Bus 資源產生器。

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");

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

當您將 AzureServiceBusResource 新增至應用程式主機時，它會公開其他有用的 API 來新增佇列和主題。換句話說，您必須先新增 AzureServiceBusResource，才能新增任何其他服務總線資源。

重要

當您呼叫 AddAzureServiceBus時，它會隱含地呼叫 AddAzureProvisioning，這可新增在應用程式啟動期間動態產生 Azure 資源的支援。應用程式必須設定適當的訂用帳戶和位置。如需詳細資訊，請參閱組態。

自動化生成的佈署 Bicep

如果您不熟悉 Bicep，這是定義 Azure 資源的特定領域語言。使用 .NET.NET Aspire，您不需要手動撰寫 Bicep，佈建 API 會為您自動產生 Bicep。當您發佈應用程式時，生成的 Bicep 會與清單檔案一起輸出。當您新增 Azure Service Bus 資源時，會產生下列 Bicep：

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param sku string = 'Standard'

param principalType string

param principalId string

resource service_bus 'Microsoft.ServiceBus/namespaces@2024-01-01' = {
  name: take('servicebus-${uniqueString(resourceGroup().id)}', 50)
  location: location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'service-bus'
  }
}

resource service_bus_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(service_bus.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: service_bus
}

output serviceBusEndpoint string = service_bus.properties.serviceBusEndpoint

上述 Bicep 是一個模組，其會布建具有下列預設值的 Azure Service Bus 命名空間：

sku：服務總線命名空間的 SKU。預設值為 Standard。
location：服務總線命名空間的位置。預設值為資源群組的位置。

除了服務總線命名空間之外，它也會布建 Azure 角色型訪問控制（Azure RBAC）內建角色 Azure Service Bus 數據擁有者。角色被指派至服務總線命名空間的資源群組。如需詳細資訊，請參閱 Azure Service Bus 資料擁有者。

自訂佈署基礎結構

所有 .NET AspireAzure 資源都是 AzureProvisioningResource 類型的子類別。此類型可藉由提供 Fluent API 來設定 Azure 資源，藉此自定義產生的 Bicep，方法是使用 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API。例如，您可以設定 SKU、位置等等。下列範例示範如何自訂 Azure Service Bus 資源：

builder.AddAzureServiceBus("service-bus")
    .ConfigureInfrastructure(infra =>
    {
        var serviceBusNamespace = infra.GetProvisionableResources()
                                       .OfType<ServiceBusNamespace>()
                                       .Single();

        serviceBusNamespace.Sku = new ServiceBusSku
        {
            Tier = ServiceBusSkuTier.Premium
        };
        serviceBusNamespace.Tags.Add("ExampleKey", "Example value");
    });

上述程式代碼：

將呼叫串聯至 ConfigureInfrastructure API：
- infra 參數是 AzureResourceInfrastructure 類型的實例。
- 藉由呼叫 GetProvisionableResources() 方法來擷取可布建的資源。
- 單一 ServiceBusNamespace 已被擷取。
- 使用 ServiceBusSkuTier.Premium 建立的 ServiceBusNamespace.Sku
- 標記會新增至服務總線命名空間，其索引鍵為 ExampleKey，且值為 Example value。

可用於自訂 Azure Service Bus 資源的組態選項還有許多。如需詳細資訊，請參閱 Azure.Provisioning.ServiceBus。如需詳細資訊，請參閱 Azure。佈建自訂。

連接到現有的 Azure Service Bus 命名空間

您可能有想要連線的現有 Azure Service Bus 命名空間。您可以將連接字串新增至應用程式主機，而不是代表新的 Azure Service Bus 資源。若要將連線新增至現有的 Azure Service Bus 命名空間，請呼叫 AddConnectionString 方法：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddConnectionString("messaging");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(serviceBus);

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

注意

連接字串可用來代表各種連線資訊，包括資料庫連接、訊息代理程式、端點 URI 和其他服務。在 .NET.NET Aspire 名詞中，「連接字串」一詞用來代表任何類型的連接資訊。

連接字串是在應用程式主機的組態中設定，通常是在 [] 區段下的 [ConnectionStrings下。應用程式主機會將此連接字串作為環境變數插入所有相依資源，例如：

{
    "ConnectionStrings": {
        "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={key_name};SharedAccessKey={key_value};"
    }
}

相依資源可以藉由呼叫 GetConnectionString 方法來存取插入的連接字串，並將連接名稱傳遞為參數，在此情況下 "messaging"。 GetConnectionString API 是 IConfiguration.GetSection("ConnectionStrings")[name]的簡寫。

新增 Azure Service Bus 佇列

若要新增 Azure Service Bus 佇列，請在 IResourceBuilder<AzureServiceBusResource>上呼叫 AddServiceBusQueue 方法：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusQueue("queue");

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

當您呼叫 AddServiceBusQueue(IResourceBuilder<AzureServiceBusResource>, String, String)時，它會將服務總線資源設定為具有名為 queue的佇列。此佇列會在您稍早新增的以 AzureServiceBusResource 表示的服務匯流排命名空間中建立。如需詳細資訊，請參閱 Azure Service Bus中的佇列、主題和訂用帳戶。

新增 Azure Service Bus 主題和訂用帳戶

若要新增 Azure Service Bus 主題，請在 IResourceBuilder<AzureServiceBusResource>上呼叫 AddServiceBusTopic 方法：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusTopic("topic");

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

當您呼叫 AddServiceBusTopic(IResourceBuilder<AzureServiceBusResource>, String, String)時，它會將服務總線資源設定為具有名為 topic的主題。本主題會在服務總線命名空間中建立，該命名空間是由您稍早新增的 AzureServiceBusResource 所表示。

若要新增主題的訂用帳戶，請在 IResourceBuilder<AzureServiceBusTopicResource> 上呼叫 AddServiceBusSubscription 方法，並使用 WithProperties 方法進行設定：

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
var topic = serviceBus.AddServiceBusTopic("topic");
topic.AddServiceBusSubscription("sub1")
     .WithProperties(subscription =>
     {
         subscription.MaxDeliveryCount = 10;
         subscription.Rules.Add(
             new AzureServiceBusRule("app-prop-filter-1")
             {
                 CorrelationFilter = new()
                 {
                     ContentType = "application/text",
                     CorrelationId = "id1",
                     Subject = "subject1",
                     MessageId = "msgid1",
                     ReplyTo = "someQueue",
                     ReplyToSessionId = "sessionId",
                     SessionId = "session1",
                     SendTo = "xyz"
                 }
             });
     });

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

上述程式代碼不僅會新增主題，並建立並設定名為主題 sub1 的訂用帳戶。訂閱的傳遞計數上限為 10，並且有一個名為 app-prop-filter-1的規則。規則是相互關聯篩選條件，根據 ContentType、CorrelationId、Subject、MessageId、ReplyTo、ReplyToSessionId、SessionId和 SendTo 屬性來篩選訊息。

如需詳細資訊，請參閱 Azure Service Bus中的佇列、主題和訂用帳戶。

新增 Azure Service Bus 模擬器資源

若要新增 Azure Service Bus 模擬器資源，請將 <IResourceBuilder<AzureServiceBusResource>> 上的呼叫鏈結至 RunAsEmulator API：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsEmulator();

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

當您呼叫 RunAsEmulator時，它會設定服務總線資源以使用模擬器在本機執行。在這裡情況下，模擬器是 Azure Service Bus Emulator。 Azure Service Bus 模擬器提供免費的本地環境來測試您的 Azure Service Bus 應用程式，是 .NET AspireAzure 託管整合的完美配套。模擬器不會安裝，而是以容器形式由 .NET.NET Aspire 存取。當您將容器新增至應用程式主機時，如上述範例所示，其中包含 mcr.microsoft.com/azure-messaging/servicebus-emulator 映射（以及隨附 mcr.microsoft.com/azure-sql-edge 映射），它會在應用程式主機啟動時建立並啟動容器。如需詳細資訊，請參閱容器資源生命週期。

設定服務總線模擬器容器

容器資源有多種組態可供選擇，例如，您可以設定容器的埠，或提供一個覆蓋所有設定的完整 JSON 組態。

設定服務總線模擬器容器主機埠

根據預設，.NET.NET Aspire設定服務總線模擬器容器時，會公開下列端點：

端點	圖片	集裝箱港口	主機埠
`emulator`	`mcr.microsoft.com/azure-messaging/servicebus-emulator`	5672	動態
`tcp`	`mcr.microsoft.com/azure-sql-edge`	1433	動態

接聽的埠預設為動態。當容器啟動時，埠會對應至主計算機上的隨機埠。若要設定端點埠，請依序在 RunAsEmulator 方法提供的容器資源生成器上進行鏈結呼叫，然後接著 WithHostPort(IResourceBuilder<AzureServiceBusEmulatorResource>, Nullable<Int32>)，如下列範例所示：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithHostPort(7777);
                         });

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

此程式代碼會設定服務總線模擬器容器的現有 emulator 連接點，以接聽埠 7777。服務總線模擬器容器的埠會映射至主機埠，如下表所示：

端點名稱	連接埠對應（`container:host`）
`emulator`	`5672:7777`

設定服務總線模擬器容器 JSON 配置

服務總線模擬器容器會以預設 config.json 檔案執行。您可以完全覆寫此檔案，或使用組態的 JsonNode 表示法來更新 JSON 組態。

若要提供自訂 JSON 組態檔，請呼叫 WithConfigurationFile(IResourceBuilder<AzureServiceBusEmulatorResource>, String) 方法：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfigurationFile(
                                 path: "./messaging/custom-config.json");
                         });

上述程式代碼會將服務總線模擬器容器設定為使用位於 ./messaging/custom-config.json的自定義 JSON 組態檔。若要改為覆寫預設組態中的特定屬性，請呼叫 WithConfiguration(IResourceBuilder<AzureServiceBusEmulatorResource>, Action<JsonNode>) 方法：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfiguration(
                                 (JsonNode configuration) =>
                                 {
                                     var userConfig = configuration["UserConfig"];
                                     var ns = userConfig["Namespaces"][0];
                                     var firstQueue = ns["Queues"][0];
                                     var properties = firstQueue["Properties"];
                                     
                                     properties["MaxDeliveryCount"] = 5;
                                     properties["RequiresDuplicateDetection"] = true;
                                     properties["DefaultMessageTimeToLive"] = "PT2H";
                                 });
                         });

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

上述程式代碼會從預設組態擷取 UserConfig 節點。然後，它會更新第一個佇列的屬性，將 MaxDeliveryCount 設定為 5、RequiresDuplicateDetection 為 true，並將 DefaultMessageTimeToLive 設定為 2 hours。

託管集成健全性檢查

主機整合 Azure Service Bus 會自動為服務總線資源新增健康檢查。健康檢查以確保服務總線正在運行，且可以建立連線。

主機整合依賴 📦 AspNetCore.HealthChecks.AzureServiceBus NuGet 套件。

Client 整合

若要開始進行 .NET AspireAzure Service Bus 用戶端整合，請在使用服務總線用戶端的應用程式專案中安裝 📦Aspire.Azure.Messaging.ServiceBus NuGet 套件。服務總線用戶端整合會註冊可用來與服務總線互動的 ServiceBusClient 實例。

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

<PackageReference Include="Aspire.Azure.Messaging.ServiceBus"
                  Version="*" />

新增服務總線用戶端

在用戶端取用專案的 Program.cs 檔案中，在任何 AddAzureServiceBusClient 上呼叫 IHostApplicationBuilder 擴充方法，來註冊 ServiceBusClient，以便透過相依性注入容器使用。方法會採用連接名稱參數。

builder.AddAzureServiceBusClient(connectionName: "messaging");

小提示

connectionName 參數必須符合在應用程式主機專案中新增服務總線資源時所使用的名稱。換句話說，當您呼叫 AddAzureServiceBus 並提供名稱 messaging 時，在呼叫 AddAzureServiceBusClient時也應使用相同的名稱。如需詳細資訊，請參閱新增的 Azure Service Bus 資源。

接著，您可以使用依賴注入來取得 ServiceBusClient 實例。例如，若要從範例服務擷取連線：

public class ExampleService(ServiceBusClient client)
{
    // Use client...
}

如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

新增具有金鑰的服務總線用戶端

在某些情況下，您可能想要以不同的連線名稱註冊多個 ServiceBusClient 實例。若要註冊金鑰服務總線用戶端，請呼叫 AddKeyedAzureServiceBusClient 方法：

builder.AddKeyedAzureServiceBusClient(name: "mainBus");
builder.AddKeyedAzureServiceBusClient(name: "loggingBus");

重要

使用索引鍵服務時，您的服務總線資源預期會設定兩個具名總線，一個用於 mainBus，另一個用於 loggingBus。

然後，您可以使用依賴注入來擷取 ServiceBusClient 實例。例如，若要從範例服務擷取連線：

public class ExampleService(
    [FromKeyedServices("mainBus")] ServiceBusClient mainBusClient,
    [FromKeyedServices("loggingBus")] ServiceBusClient loggingBusClient)
{
    // Use clients...
}

若要進一步了解鍵控服務，請參閱 .NET 相依性注入：鍵控服務。

配置

.NET Aspire Azure Service Bus 整合提供多個選項，可根據專案的需求和慣例來設定連線。

使用連線字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 AddAzureServiceBusClient 方法時提供連接字串的名稱：

builder.AddAzureServiceBusClient("messaging");

然後，從 ConnectionStrings 組態區段擷取連接字串：

{
  "ConnectionStrings": {
    "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};"
  }
}

如需如何格式化此連接字串的詳細資訊，請參閱 ConnectionString 檔。

使用組態提供者

.NET Aspire Azure Service Bus 整合支援 Microsoft.Extensions.Configuration。它會使用 AzureMessagingServiceBusSettings 鍵從設定中載入 Aspire:Azure:Messaging:ServiceBus。下列代碼段是 appsettings.json 檔案的範例，可設定一些選項：

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "ConnectionString": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};",
          "DisableTracing": false
        }
      }
    }
  }
}

如需完整的服務總線用戶端整合 JSON 架構，請參閱 Aspire。Azure。Messaging.ServiceBus/ConfigurationSchema.json。

使用內聯委派

您也可以傳遞 Action<AzureMessagingServiceBusSettings> configureSettings 委任來設置部分或所有的內嵌選項，例如，從程式碼中停用追蹤：

builder.AddAzureServiceBusClient(
    "messaging",
    static settings => settings.DisableTracing = true);

您也可以使用 Azure.Messaging.ServiceBus.ServiceBusClientOptions 方法的選擇性 Action<ServiceBusClientOptions> configureClientOptions 參數來設定 AddAzureServiceBusClient。例如，針對此用戶端的所有要求問題設定 ServiceBusClientOptions.Identifier 使用者代理程式標頭後綴：

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => clientOptions.Identifier = "myapp");

Client 整合性健康檢查

在預設情況下，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

.NET Aspire Azure Service Bus 整合：

當 AzureMessagingServiceBusSettings.DisableTracing 為 false時，新增健康檢查，用於嘗試連線到服務總線。
與 /health HTTP 端點整合，規定所有已註冊的健康檢查必須通過，應用程式才能被視為已準備好接受流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和指標組態，有時稱為 可觀察性支柱。如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。視支援服務而定，某些整合可能只支援其中一些功能。例如，某些整合支援記錄和追蹤，但不支援計量。您也可以使用組態一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire Azure Service Bus 整合會使用下列記錄類別：

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

除了取得失敗要求 Azure Service Bus 的診斷之外，您還可以設定延遲閾值，以決定哪些成功的 Azure Service Bus 診斷將被記錄。點作業的預設值為 100 毫秒，非點作業的預設值為 500 毫秒。

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => {
            clientOptions.ServiceBusClientTelemetryOptions = new()
            {
                ServiceBusThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

追蹤

.NET Aspire Azure Service Bus 整合會使用 OpenTelemetry產生下列追蹤活動：

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

Azure Service Bus 追蹤目前處於預覽狀態，因此您必須設定實驗性開關，以確保發出追蹤。

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

如需詳細資訊，請參閱 Azure Service Bus：透過服務總線傳訊的分散式追蹤和相互關聯。

指標

.NET Aspire Azure Service Bus 整合目前預設不支援計量，因為 Azure SDK 的限制。

共用方式為