.NET Aspire Azure Service Bus 整合

發行項
01/23/2025

雲端原生應用程式通常需要與傳訊服務通訊，例如 Azure Service Bus。傳訊服務有助於分離應用程式，並啟用依賴佇列、主題、訂閱、原子交易、負載平衡等功能的情境。 .NET Aspire 服務總線整合會處理下列問題，以將您的應用程式連線到 Azure Service Bus：

在 DI 容器中註冊 ServiceBusClient，以便連線到 Azure Service Bus。
透過程式代碼或組態檔設定內嵌套用 ServiceBusClient 組態。

先決條件

Azure 訂用帳戶 - 免費建立訂用帳戶
Azure Service Bus 命名空間，深入瞭解如何新增服務總線命名空間。或者，您可以使用連接字串，這在生產環境中不建議使用。

開始

若要開始使用 .NET AspireAzure Service Bus 整合，請安裝 📦Aspire。Azure。Messaging.ServiceBus 用戶端取用專案中的 NuGet 套件，也就是使用 Azure Service Bus 用戶端的應用程式專案。

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

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

範例使用方式

在用戶端取用專案的 Program.cs 檔案中，呼叫 AddAzureServiceBusClient 擴充元件，註冊 ServiceBusClient 以透過依賴注入容器使用。

builder.AddAzureServiceBusClient("messaging");

若要使用相依性插入擷取已設定的 ServiceBusClient 實例，請將其作為建構函式參數。例如，若要從範例服務擷取用戶端：

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

應用程式主機使用方式

若要將 Azure Service Bus 的託管支援新增到您的 IDistributedApplicationBuilder，請在 📦 專案中安裝 AspireAzure.Hosting..ServiceBus. NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

在應用程式主機專案中，註冊服務總線整合，並使用下列方法取用服務：

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureServiceBus("messaging")
    : builder.AddConnectionString("messaging");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(serviceBus)

配置

.NET .NET Aspire 服務總線整合提供多個選項，可根據專案的需求和慣例來設定 ServiceBusClient。

使用組態提供者

服務匯流整合支援 Microsoft.Extensions.Configuration。它會使用 AzureMessagingServiceBusSettings 金鑰，從 appsettings.json 或其他組態檔載入 Aspire:Azure:Messaging:ServiceBus。

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Identifier": "CLIENT_ID"
          }
        }
      }
    }
  }
}

如果您在 Aspire:Azure:Messaging:ServiceBus 檔案的 [appsettings.json] 區段中設定組態，您可以直接呼叫方法 AddAzureServiceBusClient 而不傳遞任何參數。

使用內聯委派

您也可以傳遞 Action<AzureMessagingServiceBusSettings> 委派來設定部分或所有內嵌選項，例如設定 FullyQualifiedNamespace：

builder.AddAzureServiceBusClient(
    "messaging",
    static settings => settings.FullyQualifiedNamespace = "YOUR_SERVICE_BUS_NAMESPACE");

您也可以使用委派，設定 Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>>，這是 AddAzureServiceBus 方法的第二個參數。例如，若要設定 ServiceBusClient 標識碼來識別用戶端：

builder.AddAzureServiceBusClient(
    "messaging",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.Identifier = "CLIENT_ID"));

組態選項

下列可設定的選項會透過 AzureMessagingServiceBusSettings 類別公開：

名字	描述
`ConnectionString`	用來連接到服務總線命名空間的連接字串。
`Credential`	用來向服務總線命名空間進行身分驗證的憑證。
`FullyQualifiedNamespace`	完全限定的服務總線命名空間。
`DisableTracing`	停用服務總線客戶端的追蹤。
^†`HealthCheckQueueName`	用於健康狀態檢查的佇列名稱。
^†`HealthCheckTopicName`	用於健康檢查的主題名稱。

^† 啟用健康情況檢查時，至少必須有一個名稱選項。

可檢視性和遙測

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

伐木

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

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

追蹤

注意

ActivitySource SDK for Azure 中對 .NET 的 Service Bus 支援是實驗性功能，活動的形式可能會在未來不通知的情況下變更。

您可以透過數種方式啟用追蹤：

將 Azure.Experimental.EnableActivitySource執行時間組態設定設定為 true。這可以使用下列任一項來完成：
- 通話 AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);。
- 將 RuntimeHostConfigurationOption 設定新增至項目檔：
```
<ItemGroup>
    <RuntimeHostConfigurationOption
         Include="Azure.Experimental.EnableActivitySource"
         Value="true" />
</ItemGroup>
```
將 AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE 環境變數設定為「true」。
- 您可以藉由將呼叫鏈結至 WithEnvironment("AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE", "true") 來達成

啟用時，.NET AspireAzure 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

如需詳細資訊，請參閱：

指標

.NET Aspire Azure Service Bus 整合功能目前預設不支援度量功能，因為供 Azure使用的 .NET SDK 的限制。如果未來發生該變更，本節將會更新以反映這些變更。

共用方式為