.NET AspireAzure Service Bus 統合

2025-04-01

含まれているもの: ホスティング統合 —および— Client 統合

Azure Service Bus は、メッセージキューとパブリッシュ/サブスクライブトピックを含むフルマネージドのエンタープライズメッセージブローカーです。 .NET AspireAzure Service Bus 統合により、Azure Service Bus アプリケーションから .NET インスタンスに接続できます。

ホスティング統合

.NET.NET AspireAzure Service Bus ホスティング統合は、さまざまな Service Bus リソースを次の種類としてモデル化します。

AzureServiceBusResource: Azure Service Bus リソースを表します。
AzureServiceBusQueueResource: Azure Service Bus キューリソースを表します。
AzureServiceBusSubscriptionResource: Azure Service Bus サブスクリプションリソースを表します。
AzureServiceBusTopicResource: Azure Service Bus トピックリソースを表します。
AzureServiceBusEmulatorResource: Azure Service Bus エミュレーターリソースを表します。

これらの型と API にアクセスして使用するには、アプリホストプロジェクトに、.Hosting..ServiceBus NuGet パッケージを追加します。

.NET コマンドラインインターフェース (CLI)
パッケージリファレンス

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

詳細については、「dotnet でのパッケージの追加」または「.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 が公開されます。つまり、他の Service Bus リソースを追加する前に、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'

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'
  }
}

output serviceBusEndpoint string = service_bus.properties.serviceBusEndpoint

output name string = service_bus.name

上記の Bicep は、 Azure Service Bus 名前空間リソースをプロビジョニングするモジュールです。さらに、ロールの割り当ては、別のモジュールで Azure リソースに対して作成されます。

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

param service_bus_outputs_name string

param principalType string

param principalId string

resource service_bus 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: service_bus_outputs_name
}

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
}

Service Bus 名前空間に加えて、Azure データ所有者の Azure ロールベースのアクセス制御 (Azure Service Bus RBAC) 組み込みロールもプロビジョニングされます。ロールは、Service Bus 名前空間のリソースグループに割り当てられます。詳細については、Azure Service Busデータ所有者を参照してください。

プロビジョニングインフラストラクチャをカスタマイズする

すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。この型は、Azure リソースを構成するための使い勝手の良い API を提供し、ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API を使用して生成された Bicep のカスタマイズを可能にします。たとえば、SKU、場所などを構成できます。次の例では、Azure Service Bus リソースをカスタマイズする方法を示します。

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

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

上記のコード:

ConfigureInfrastructure API への呼び出しを連鎖させます。
- infra パラメーターは、AzureResourceInfrastructure 型のインスタンスです。
- プロビジョニング可能なリソースは、GetProvisionableResources() メソッドを呼び出すことによって取得されます。
- 1つのServiceBusNamespaceが取得されました。
- ServiceBusNamespace.Sku を用いて ServiceBusSkuTier.Premium を作成した
- ExampleKey のキーと値が Example valueのタグが Service Bus 名前空間に追加されます。

Azure Service Bus リソースをカスタマイズするために使用できる構成オプションは他にも多数あります。詳細については、Azure.Provisioning.ServiceBusを参照してください。「プロビジョニングのカスタマイズ」についての詳細は、こちらを参照してください。

既存の Azure Service Bus 名前空間に接続する

接続する既存の Azure Service Bus 名前空間がある場合があります。 AzureServiceBusResourceが既存のリソースであることを注釈する呼び出しをチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

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

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

Azure Service Bus リソースを既存のリソースとして扱う方法の詳細については、「既存のAzure リソースを使用する」を参照してください。

手記

または、 Azure Service Bus リソースを表す代わりに、接続文字列をアプリホストに追加することもできます。このアプローチは弱く型指定されており、ロールの割り当てやインフラストラクチャのカスタマイズでは機能しません。詳細については、「Azureを使用して既存のリソースを追加する」を参照してください。

Azure Service Bus キューを追加する

Azure Service Bus キューを追加するには、AddServiceBusQueueで IResourceBuilder<AzureServiceBusResource> メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

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

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

AddServiceBusQueue(IResourceBuilder<AzureServiceBusResource>, String, String)を呼び出すと、Service Bus リソースに queueという名前のキューが構成されます。 messaging Service Bus リソースとその子queueの間の明示的な親子関係を表します。キューは、前に追加した AzureServiceBusResource によって表される Service Bus 名前空間に作成されます。詳細については、Azure Service Busの「キュー、トピック、サブスクリプション」を参照してください。

Azure Service Bus トピックとサブスクリプションを追加

Azure Service Bus トピックを追加するには、AddServiceBusTopicで IResourceBuilder<AzureServiceBusResource> メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

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

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

AddServiceBusTopic(IResourceBuilder<AzureServiceBusResource>, String, String)を呼び出すと、Service Bus リソースに topicという名前のトピックが構成されます。このトピックは、前に追加した AzureServiceBusResource によって表される Service Bus 名前空間に作成されます。

トピックのサブスクリプションを追加するには、AddServiceBusSubscription で IResourceBuilder<AzureServiceBusTopicResource> メソッドを呼び出し、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を呼び出すと、エミュレーターを使用してローカルで実行するように Service Bus リソースが構成されます。この場合のエミュレーターはAzure Service Bus エミュレーターです。 Azure Service Bus Emulator は、Azure Service Bus アプリをテストするための無料のローカル環境を提供し、.NET AspireAzure ホスティング統合に最適です。エミュレーターはインストールされていません。代わりに、コンテナーとして .NET.NET Aspire にアクセスできます。前の例に示すように、mcr.microsoft.com/azure-messaging/servicebus-emulator イメージ (およびコンパニオン mcr.microsoft.com/azure-sql-edge イメージ) でコンテナーをアプリホストに追加すると、アプリホストの起動時にコンテナーが作成されて起動されます。詳細については、「コンテナーリソースのライフサイクル」を参照してください。

Service Bus エミュレーターコンテナーの構成

コンテナーリソースにはさまざまな構成が用意されています。たとえば、コンテナーのポートを構成したり、すべてをオーバーライドする wholistic JSON 構成を指定したりできます。

Service Bus エミュレーターコンテナーのホストポートを構成する

既定では、.NET.NET Aspireによって構成された Service Bus エミュレーターコンテナーは、次のエンドポイントを公開します。

エンドポイント	画像	コンテナーポート	ホストポート
`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...

前のコードは、Service Bus エミュレーターコンテナーの既存の emulator エンドポイントをポート 7777でリッスンするように構成します。 Service Bus エミュレーターコンテナーのポートは、次の表に示すようにホストポートにマップされます。

エンドポイント名	ポートマッピング (`container:host`)
`emulator`	`5672:7777`

Service Bus エミュレーターコンテナー JSON の設定を構成する

Service Bus エミュレーターは、構成されたリソースから、この config.json ファイルと同様の構成を自動的に生成します。この生成されたファイルを完全にオーバーライドすることも、 JSON 構成を構成の JsonNode 表現で更新することもできます。

カスタム JSON 構成ファイルを指定するには、WithConfigurationFile(IResourceBuilder<AzureServiceBusEmulatorResource>, String) メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

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

前のコードでは、Service Bus エミュレーターコンテナーが、JSONにあるカスタム ./messaging/custom-config.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 ホスティング統合により、Service Bus リソースの正常性チェックが自動的に追加されます。正常性チェックでは、Service Bus が実行されていること、および Service Bus への接続を確立できることを確認します。

ホスティング統合は、📦 AspNetCore.HealthChecks.AzureServiceBus NuGet パッケージに依存します。

Client 統合

.NET AspireAzure Service Bus クライアント統合を開始するには、Messaging.ServiceBus NuGet パッケージをクライアントを使用するプロジェクト (つまり、Service Bus クライアントを利用するアプリケーションのプロジェクト) 内にインストールします。 Service Bus クライアント統合により、Service Bus との対話に使用できる ServiceBusClient インスタンスが登録されます。

.NET コマンドラインインターフェース (CLI)
パッケージリファレンス

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

Service Bus クライアントの追加

クライアントを使用するプロジェクトの Program.cs ファイルで、任意の AddAzureServiceBusClient で IHostApplicationBuilder 拡張メソッドを呼び出して、依存関係挿入コンテナーを介して使用する ServiceBusClient を登録します。このメソッドは、接続名パラメーターを受け取ります。

builder.AddAzureServiceBusClient(connectionName: "messaging");

ヒント

connectionName パラメーターは、アプリホストプロジェクトで Service Bus リソースを追加するときに使用される名前と一致する必要があります。つまり、AddAzureServiceBus を呼び出す際に messaging の名前を指定した場合、その同じ名前を AddAzureServiceBusClientを呼び出す際にも使用する必要があります。詳細については、「Azure Service Bus リソースの追加」を参照してください。

その後、依存関係の挿入を使用して ServiceBusClient インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

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

依存関係の挿入の詳細については、依存関係の挿入.NET参照してください。

キー付き Service Bus クライアントを追加する

接続名が異なる複数の ServiceBusClient インスタンスを登録する場合があります。キー付き Service Bus クライアントを登録するには、AddKeyedAzureServiceBusClient メソッドを呼び出します。

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

重要

キー付きサービスを使用する場合、Service Bus リソースで 2 つの名前付きバス (1 つは mainBus 用、もう 1 つは loggingBus用) が構成されている必要があります。

その後、依存関係の挿入を使用して ServiceBusClient インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

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

キー付きサービスの詳細については、「 .NET 依存関係の挿入: キー付きサービス」を参照してください。

設定

.NET AspireAzure Service Bus 統合には、プロジェクトの要件と規則に基づいて接続を構成するための複数のオプションが用意されています。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、AddAzureServiceBusClient メソッドを呼び出すときに接続文字列の名前を指定できます。

builder.AddAzureServiceBusClient("messaging");

その後、接続文字列は ConnectionStrings 構成セクションから取得されます。

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

この接続文字列の書式を設定する方法の詳細については、ConnectionString のドキュメントを参照してください。

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

.NET AspireAzure 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
        }
      }
    }
  }
}

完全な Service Bus クライアント統合 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 AspireAzure Service Busの統合:

AzureMessagingServiceBusSettings.DisableTracing が falseされたときに正常性チェックを追加します。これは Service Bus への接続を試みます。
/health HTTP エンドポイントと統合されます。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります。

可観測性とテレメトリ

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

伐採

.NET AspireAzure 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 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 Service Bus トレースは現在プレビュー段階であるため、トレースが確実に出力されるように試験段階のスイッチを設定する必要があります。

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

詳細については、「 Azure Service Bus: Service Bus メッセージングによる分散トレースと相関付け」を参照してください。

メトリック

.NET AspireAzure Service Bus 統合は現在、Azure SDK の制限により、既定ではメトリックをサポートしていません。