.NET AspireAzureWeb PubSub 統合

2025-04-17

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

Azure Web PubSub は、フルマネージドのリアルタイムメッセージングサービスであり、WebSocket とパブリッシュ/サブスクライブパターンを使用してリアルタイム Web アプリケーションを構築できます。 .NET AspireAzureWeb PubSub 統合により、Azure アプリケーションから Web PubSub.NET インスタンスに接続できます。

ホスティング統合

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

AzureWebPubSubResource: 基になる Azure リソースへの接続情報を含む、Web PubSubAzure リソースを表します。
AzureWebPubSubHubResource: ハブの設定を含む Web PubSub ハブ設定リソースを表します。たとえば、ハブで匿名接続を許可するかどうかを指定したり、ハブにイベントハンドラーを追加したりすることができます。

アプリホストプロジェクト内でこれらの型とAPIを表現し、アクセスするには、📦Aspire.Hosting.Azure.WebPubSub NuGetパッケージをインストールしてください。

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

dotnet add package Aspire.Hosting.Azure.WebPubSub

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

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

AzureWeb PubSub リソースを追加する

AzureWeb PubSub リソースをアプリホストプロジェクトに追加するには、名前を指定して AddAzureWebPubSub メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var webPubSub = builder.AddAzureWebPubSub("web-pubsub");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(webPubSub);

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

上記のコードは、Azure という名前の Web PubSubweb-pubsub リソースをアプリホストプロジェクトに追加します。 WithReference メソッドは、接続情報を ExampleProject プロジェクトに渡します。

重要

AddAzureWebPubSubを呼び出すと、暗黙的に AddAzureProvisioning(IDistributedApplicationBuilder)が呼び出されます。これによって、アプリの起動時に Azure リソースを動的に生成するためのサポートが追加されます。アプリは、適切なサブスクリプションと場所を構成する必要があります。詳細については、「ローカルプロビジョニング: 構成」を参照してください。

AzureWeb PubSub ハブリソースを追加する

AzureWeb PubSub リソースを追加するときには、子ハブリソースを追加することもできます。ハブリソースは、接続とイベントハンドラーの論理的なグループ化です。アプリホストプロジェクトに AzureWeb PubSub ハブリソースを追加するには、リソースとハブ名を提供し、AddHub メソッドへの連鎖呼び出しを行います。

var builder = DistributedApplication.CreateBuilder(args);

var worker = builder.AddProject<Projects.WorkerService>("worker")
                    .WithExternalHttpEndpoints();

var webPubSub = builder.AddAzureWebPubSub("web-pubsub");
var messagesHub = webPubSub.AddHub(name: "messages", hubName: "messageHub");

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

前述のコードは、イベントハンドラの追加を可能にするAzureという名前のWeb PubSubmessagesハブリソースとmessageHubというハブ名を追加します。イベントハンドラーを追加するには、AddEventHandlerを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var worker = builder.AddProject<Projects.WorkerService>("worker")
                    .WithExternalHttpEndpoints();

var webPubSub = builder.AddAzureWebPubSub("web-pubsub");
var messagesHub = webPubSub.AddHub(name: "messages", hubName: "messageHub");

messagesHub.AddEventHandler(
    $"{worker.GetEndpoint("https")}/eventhandler/",
    systemEvents: ["connected"]);

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

上記のコードは、外部 HTTP エンドポイントを持つ worker という名前のワーカーサービスプロジェクトを追加します。 messages リソースという名前のハブが web-pubsub リソースに追加され、イベントハンドラーが messagesHub リソースに追加されます。イベントハンドラー URL は、ワーカーサービスの外部 HTTP エンドポイントに設定されます。詳細については、「AzureWeb PubSub イベントハンドラーの」を参照してください。

プロビジョニングによって生成された Bicep

アプリを発行すると、プロビジョニング API .NET.NET Aspire マニフェストファイルと共に Bicep が生成されます。 Bicep は、Azure リソースを定義するためのドメイン固有の言語です。詳細については、「Bicep Overview」を参照してください。

AzureWeb PubSub リソースを追加すると、次の Bicep が生成されます。

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

param sku string = 'Free_F1'

param capacity int = 1

param messages_url_0 string

resource web_pubsub 'Microsoft.SignalRService/webPubSub@2024-03-01' = {
  name: take('webpubsub-${uniqueString(resourceGroup().id)}', 63)
  ___location: ___location
  sku: {
    name: sku
    capacity: capacity
  }
  tags: {
    'aspire-resource-name': 'web-pubsub'
  }
}

resource messages 'Microsoft.SignalRService/webPubSub/hubs@2024-03-01' = {
  name: 'messages'
  properties: {
    eventHandlers: [
      {
        urlTemplate: messages_url_0
        userEventPattern: '*'
        systemEvents: [
          'connected'
        ]
      }
    ]
  }
  parent: web_pubsub
}

output endpoint string = 'https://${web_pubsub.properties.hostName}'

output name string = web_pubsub.name

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

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

param web_pubsub_outputs_name string

param principalType string

param principalId string

resource web_pubsub 'Microsoft.SignalRService/webPubSub@2024-03-01' existing = {
  name: web_pubsub_outputs_name
}

resource web_pubsub_WebPubSubServiceOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(web_pubsub.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '12cf5a90-567b-43ae-8102-96cf46c7d9b4'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '12cf5a90-567b-43ae-8102-96cf46c7d9b4')
    principalType: principalType
  }
  scope: web_pubsub
}

生成された Bicep は開始点であり、C# のプロビジョニングインフラストラクチャへの変更の影響を受ける。 Bicep ファイルのカスタマイズは直接上書きされるため、C# プロビジョニング API を通じて変更を加えて、生成されたファイルに反映されるようにします。

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

すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。この種類の型を使うことで、Azure API を利用して ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) リソースを構成する流暢な API が提供され、生成された Bicep をカスタマイズすることができます。たとえば、kind、consistencyPolicy、locationsなどを構成できます。次の例では、AzureAzure Cosmos DB リソースをカスタマイズする方法を示します。

builder.AddAzureWebPubSub("web-pubsub")
    .ConfigureInfrastructure(infra =>
    {
        var webPubSubService = infra.GetProvisionableResources()
                                    .OfType<WebPubSubService>()
                                    .Single();

        webPubSubService.Sku.Name = "Standard_S1";
        webPubSubService.Sku.Capacity = 5;
        webPubSubService.Tags.Add("ExampleKey", "Example value");
    });

前述のコード:

ConfigureInfrastructure API への呼び出しを連鎖させます。
- infra パラメーターは、AzureResourceInfrastructure 型のインスタンスです。
- プロビジョニング可能なリソースは、GetProvisionableResources() メソッドを呼び出すことによって取得されます。
- 単一の WebPubSubService リソースが取得されます。
- WebPubSubService.Sku オブジェクトの名前と容量のプロパティはそれぞれ、Standard_S1 と 5に設定されています。
- Web PubSub というキーと ExampleKeyという値を持つタグが Example value リソースに追加されます。

Web PubSub リソースをカスタマイズするために使用できる構成オプションは他にも多数あります。詳細については、Azure.Provisioning.WebPubSubを参照してください。詳細については、Azure.Provisioning のカスタマイズをご覧ください。

既存の AzureWeb PubSub インスタンスに接続する

接続する既存の AzureWeb PubSub サービスがある場合があります。呼び出しをチェーンして、AzureWebPubSubResource が既存のリソースであることを注釈付けることができます。

var builder = DistributedApplication.CreateBuilder(args);

var existingPubSubName = builder.AddParameter("existingPubSubName");
var existingPubSubResourceGroup = builder.AddParameter("existingPubSubResourceGroup");

var webPubSub = builder.AddAzureWebPubSub("web-pubsub")
                       .AsExisting(existingPubSubName, existingPubSubResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(webPubSub);

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

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

注

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

Client 統合

.NET AspireAzureWeb PubSub クライアント統合は、Azureを使用して Web PubSubWebPubSubServiceClient サービスに接続するために使用されます。 .NET AspireAzureWeb PubSub サービスクライアントの統合を開始するには、📦Aspireをインストールします。Azure.Messaging.WebPubSub アプリケーション内の NuGet パッケージ。

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

dotnet add package Aspire.Azure.Messaging.WebPubSub

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

サポートされている Web PubSub クライアントの種類

ライブラリでは、次の Web PubSub クライアントの種類がサポートされています。

Azure クライアントの種類	Azure オプションクラス	.NET.NET Aspire 設定クラス
WebPubSubServiceClient	WebPubSubServiceClientOptions	AzureMessagingWebPubSubSettings

クライアント Web PubSub 追加する

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

builder.AddAzureWebPubSubServiceClient(
    connectionName: "web-pubsub");

ヒント

connectionName パラメーターは、アプリホストプロジェクトに Web PubSub リソースを追加するときに使用する名前と一致する必要があります。詳細については、「AzureWeb PubSub リソースを追加する」を参照してください。

WebPubSubServiceClientを追加した後、依存関係の挿入を使用してクライアントインスタンスを取得できます。たとえば、サンプルサービスからデータソースオブジェクトを取得するには、それをコンストラクターパラメーターとして定義し、ExampleService クラスが依存関係挿入コンテナーに登録されていることを確認します。

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

詳細については、以下を参照してください。

Azure.Messaging.WebPubSub のドキュメントで WebPubSubServiceClientの使用方法の例を示します。
依存性注入の詳細については、.NETの依存性注入を参照してください。

キー付き Web PubSub クライアントを追加する

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

builder.AddKeyedAzureWebPubSubServiceClient(name: "messages");
builder.AddKeyedAzureWebPubSubServiceClient(name: "commands");

重要

キー付きサービスを使用する場合、Web PubSub リソースで 2 つの名前付きハブ (1 つは messages 用、もう 1 つは commands用) が構成されている必要があります。

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

public class ExampleService(
    [KeyedService("messages")] WebPubSubServiceClient messagesClient,
    [KeyedService("commands")] WebPubSubServiceClient commandsClient)
{
    // Use clients...
}

特定の接続名で単一のWebPubSubServiceClient インスタンスを登録したい場合、接続名をサービスキーとして使用するオーバーロードがあります。 AddKeyedAzureWebPubSubServiceClient メソッドを呼び出します。このメソッドは、クライアントを依存性注入コンテナ内のシングルトンサービスとして登録します。

builder.AddKeyedAzureWebPubSubServiceClient(connectionName: "web-pubsub");

詳細については、「.NETにおけるのキー付きサービス」を参照してください。

設定

.NET AspireAzureWeb PubSub ライブラリには、プロジェクトの要件と規則に基づいて AzureWeb PubSub 接続を構成するための複数のオプションが用意されています。 Endpoint または ConnectionString を指定する必要があります。

接続文字列を使用する

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

builder.AddAzureWebPubSubServiceClient(
    "web-pubsub",
    settings => settings.HubName = "your_hub_name");

接続情報は、ConnectionStrings 構成セクションから取得されます。次の 2 つの接続形式がサポートされています。

サービスエンドポイント (推奨): DefaultAzureCredentialでサービスエンドポイントを使用します。
```
{
  "ConnectionStrings": {
    "web-pubsub": "https://{account_name}.webpubsub.azure.com"
  }
}
```

接続文字列: アクセスキーが含まれます。

{
  "ConnectionStrings": {
    "web-pubsub": "Endpoint=https://{account_name}.webpubsub.azure.com;AccessKey={account_key}"
  }
}

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

ライブラリは Microsoft.Extensions.Configurationをサポートしています。 Aspire:Azure:Messaging:WebPubSub キーを使用して構成から設定を読み込みます。

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "WebPubSub": {
          "DisableHealthChecks": true,
          "HubName": "your_hub_name"
        }
      }
    }
  }
}

完全な AzureOpenAI クライアント統合 JSON スキーマについては、Aspireを参照してください。Azure.Messaging.WebPubSub/ConfigurationSchema.json.

インラインデリゲートを使用する

設定はインラインで構成できます。

builder.AddAzureWebPubSubServiceClient(
    "web-pubsub",
    settings => settings.DisableHealthChecks = true);

可観測性とテレメトリ

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

ログ記録

.NET AspireAzureWeb PubSub 統合では、次のログカテゴリが使用されます。

Azure
Azure.Core
Azure.Identity
Azure.Messaging.WebPubSub

トレース

.NET AspireAzureWeb PubSub 統合では、OpenTelemetryを使用して次のトレースアクティビティが出力されます。

Azure.Messaging.WebPubSub.*

メトリック

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