Azure Web PubSub - Client integration

Client integration

The Aspire Azure Web PubSub client integration is used to connect to an Azure Web PubSub service using the WebPubSubServiceClient. To get started with the Aspire Azure Web PubSub service client integration, install the 📦 Aspire.Azure.Messaging.WebPubSub NuGet package.

.NET CLI

.NET CLI — Add Aspire.Azure.Messaging.WebPubSub package

dotnet add package Aspire.Azure.Messaging.WebPubSub

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Azure.Messaging.WebPubSub@*

PackageReference (*.csproj)

XML — Add Aspire.Azure.Messaging.WebPubSub package reference

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

Supported Web PubSub client types

The following Web PubSub client types are supported by the library:

Azure client type	Azure options class	Aspire settings class
WebPubSubServiceClient	WebPubSubServiceClientOptions	AzureMessagingWebPubSubSettings

Add Web PubSub client

In the Program.cs file of your client-consuming project, call the AddAzureWebPubSubServiceClient extension method to register a WebPubSubServiceClient for use via the dependency injection container. The method takes a connection name parameter:

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

Consejo

The connectionName parameter must match the name used when adding the Web PubSub resource in the AppHost project. For more information, see Add an Azure Web PubSub resource.

After adding the WebPubSubServiceClient, you can retrieve the client instance using dependency injection:

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

For more information, see:

• Azure.Messaging.WebPubSub documentation for examples on using the WebPubSubServiceClient.
• Dependency injection in .NET for details on dependency injection.

Properties of the Azure Web PubSub resources

When you use the WithReference method to pass an Azure Web PubSub resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called webpubsub becomes WEBPUBSUB_URI.

Azure Web PubSub service

The Azure Web PubSub resource exposes the following connection properties:

Property Name	Description
Uri	The service endpoint URI (e.g., https://{name}.webpubsub.azure.com)

For example, if you reference an Azure Web PubSub resource named webpubsub in your AppHost project, the following environment variables will be available in the consuming project:

• WEBPUBSUB_URI

Add keyed Web PubSub client

There might be situations where you want to register multiple WebPubSubServiceClient instances with different connection names. To register keyed Web PubSub clients, call the AddKeyedAzureWebPubSubServiceClient method:

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

Precaución

When using keyed services, it’s expected that your Web PubSub resource configured two named hubs, one for the messages and one for the commands.

Then you can retrieve the client instances using dependency injection:

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

For more information, see Keyed services in .NET.

Configuration

The Aspire Azure Web PubSub library provides multiple options to configure the Azure Web PubSub connection based on the requirements and conventions of your project. Either an Endpoint or a ConnectionString must be supplied.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling AddAzureWebPubSubServiceClient:

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

The connection information is retrieved from the ConnectionStrings configuration section. Two connection formats are supported:

• Service endpoint (recommended): Uses the service endpoint with DefaultAzureCredential.

  {
    "ConnectionStrings": {
      "web-pubsub": "https://{account_name}.webpubsub.azure.com"
    }
  }

• Connection string: Includes an access key.

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

Use configuration providers

The library supports Microsoft.Extensions.Configuration. It loads settings from configuration using the Aspire:Azure:Messaging:WebPubSub key:

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

Use inline delegates

You can configure settings inline:

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

Observability and telemetry

Aspire integrations automatically set up Logging, Tracing, and Metrics configurations.

Logging

The Aspire Azure Web PubSub integration uses the following log categories:

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

Tracing

The Aspire Azure Web PubSub integration will emit the following tracing activities using OpenTelemetry:

• Azure.Messaging.WebPubSub.*

Metrics

The Aspire Azure Web PubSub integration currently doesn’t support metrics by default due to limitations with the Azure SDK for .NET.