.NET Aspire Azure Service Bus 統合

クラウドネイティブ アプリでは、多くの場合、Azure Service Busなどのメッセージング サービスとの通信が必要です。 メッセージング サービスは、アプリケーションを分離し、キュー、トピックとサブスクリプション、アトミック トランザクション、負荷分散などの機能に依存するシナリオを実現するのに役立ちます。 .NET Aspire Service Bus 統合は、アプリを Azure Service Busに接続するための次の問題を処理します。

• Azure Service Busに接続するための ServiceBusClient が DI コンテナーに登録されます。
• コードまたは構成ファイルの設定を使用して、ServiceBusClient 構成をインラインで適用します。

前提 条件

• Azure サブスクリプション - 無料で作成する
• 名前空間 について、Service Bus 名前空間を 追加する方法を詳しく説明します。 または、運用環境では推奨されない接続文字列を使用することもできます。

作業の開始

.NET Aspire Azure Service Bus 統合を開始するには、📦Aspire.Azure.Messaging.ServiceBus NuGet パッケージをclientを使用するプロジェクト、すなわちAzure Service Busclientを利用するアプリケーションのプロジェクトにインストールします。

.NET CLI

dotnet add package Aspire.Azure.Messaging.ServiceBus

PackageReference

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

詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

使用例

client-consuming プロジェクトの 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

dotnet add package Aspire.Hosting.Azure.ServiceBus

PackageReference

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

アプリ ホスト プロジェクトで、Service Bus 統合を登録し、次の方法を使用してサービスを使用します。

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 Service Bus 統合には、プロジェクトの要件と規則に基づいて ServiceBusClient を構成するための複数のオプションが用意されています。

構成プロバイダーを使用する

Service Bus 統合では、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");

AddAzureServiceBus メソッドの 2 番目のパラメーターである Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>> デリゲートを使用して、ServiceBusClientOptions を設定することもできます。 たとえば、clientを識別する ServiceBusClient ID を設定するには、次のようにします。

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

構成オプション

次の構成可能なオプションは、AzureMessagingServiceBusSettings クラスを介して公開されます。

名前	説明
ConnectionString	Service Bus 名前空間への接続に使用される接続文字列。
Credential	Service Bus 名前空間に対する認証に使用される資格情報。
FullyQualifiedNamespace	完全修飾 Service Bus 名前空間。
DisableTracing	Service Bus clientのトレースを無効にします。
†HealthCheckQueueName	ヘルスチェックに使用されるキューの名前。
†HealthCheckTopicName	ヘルスチェックに使用されるトピックの名前。

^† 正常性チェックを有効にする場合は、少なくとも 1 つの名前オプションが必須です。

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱 とも呼ばれます。 統合の可観測性とテレメトリの詳細については、統合の概要 参照してください。 バッキング サービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。 たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。 テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.NET Aspire Azure Service Bus 統合では、次のログ カテゴリが使用されます。

• Azure.Core
• Azure.Identity
• Azure-Messaging-ServiceBus

トレース

手記

ActivitySource サービスバスの Azure SDK における .NET でのサポートは実験的であり、今後予告なくアクティビティの内容が変更される可能性があります。

トレースは、いくつかの方法で有効にすることができます。

• 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 for .NET: 分散トレーシングとサービスバス client。
• Azure SDK for .NET: OpenTelemetry 構成。
• Azure SDK for .NET: 試験的なトレース機能を有効化します。

メトリック

現在、.NET AspireAzure Service Bus 統合では、.NET用の Azure SDK の制限により、メトリックは既定でサポートされていません。 今後その変更が行われる場合は、これらの変更を反映するようにこのセクションが更新されます。

関連項目

• Azure Service Bus
• .NET .NET Aspire 統合
• .NET Aspire GitHub リポ