.NET Aspire Azure Service Bus 集成

项目
12/13/2024

云原生应用通常需要与消息服务（如 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 使用 client项目中的 NuGet 包，即使用 Azure Service Busclient的应用程序的项目。

.NET 命令行界面
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

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

示例用法

在 client消耗项目的 Program.cs 文件中，调用 AddAzureServiceBusClient 扩展来注册 ServiceBusClient，以通过依赖注入容器来使用。

builder.AddAzureServiceBusClient("messaging");

若要使用依赖项注入检索配置的 ServiceBusClient 实例，请将其作为构造函数参数。例如，若要从示例服务获取 client，

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

应用主机使用情况

若要将 Azure Service Bus 的托管支持添加到 IDistributedApplicationBuilder，请在应用主机项目中安装 📦Aspire.Hosting.Azure.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。它使用 Aspire:Azure:Messaging:ServiceBus 密钥从 appsettings.json 或其他配置文件加载 AzureMessagingServiceBusSettings。

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

如果在 appsettings.json 文件的 Aspire:Azure:Messaging:ServiceBus 节中设置了配置，只需调用方法 AddAzureServiceBusClient 即可不传递任何参数。

使用内联委托

还可以传递 Action<AzureMessagingServiceBusSettings> 委托来设置一些或全部内联选项，例如设置 FullyQualifiedNamespace：

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

还可以使用 Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>> 委托（AddAzureServiceBus 方法的第二个参数）设置 ServiceBusClientOptions。例如，设置 ServiceBusClient ID 以标识 client：

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

配置选项

以下可配置选项通过 AzureMessagingServiceBusSettings 类公开：

名字	描述
`ConnectionString`	用于连接到服务总线命名空间的连接字符串。
`Credential`	用于向服务总线命名空间进行身份验证的凭据。
`FullyQualifiedNamespace`	完全限定的服务总线命名空间。
`DisableTracing`	禁用服务总线 client的跟踪。
^†`HealthCheckQueueName`	用于运行状况检查的队列的名称。
^†`HealthCheckTopicName`	用于运行状况检查的主题的名称。

^† 启用运行状况检查时，至少有一个名称选项是必需的。

可观测性和遥测

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

伐木

.NET Aspire Azure Service Bus 集成使用以下日志类别：

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

追踪

注意

适用于 .NET 的 Azure SDK 中的服务总线 ActivitySource 支持是实验性的，并且将来的活动形式可能会在未事先通知的情况下发生改变。

可以通过多种方式启用跟踪：

将 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

有关详细信息，请参阅：

指标

由于 Azure SDK 对 .NET的限制，.NET AspireAzure Service Bus 的集成当前默认情况下不支持度量指标。如果将来发生此更改，将更新此部分以反映这些更改。

通过