.NET Aspire Azure Web PubSub integration

Includes: Hosting integration and Client integration

Azure Web PubSub is a fully managed real-time messaging service that enables you to build real-time web applications using WebSockets and publish-subscribe patterns. The .NET Aspire Azure Web PubSub integration enables you to connect to Azure Web PubSub instances from your .NET applications.

Hosting integration

The .NET Aspire Azure Web PubSub hosting integration models the Web PubSub resources as the following types:

• AzureWebPubSubResource: Represents an Azure Web PubSub resource, including connection information to the underlying Azure resource.
• AzureWebPubSubHubResource: Represents a Web PubSub hub settings resource, which contains the settings for a hub. For example, you can specify if the hub allows anonymous connections or add event handlers to the hub.

To access these types and APIs for expressing them within your app host project, install the 📦 Aspire.Hosting.Azure.WebPubSub NuGet package:

.NET CLI

dotnet add package Aspire.Hosting.Azure.WebPubSub

PackageReference

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

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add an Azure Web PubSub resource

To add an Azure Web PubSub resource to your app host project, call the AddAzureWebPubSub method providing a name:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

The preceding code adds an Azure Web PubSub resource named web-pubsub to the app host project. The WithReference method passes the connection information to the ExampleProject project.

Important

When you call AddAzureWebPubSub, it implicitly calls AddAzureProvisioning(IDistributedApplicationBuilder)—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

Add an Azure Web PubSub hub resource

To add an Azure Web PubSub hub resource to your app host project, chain a call to the AddHub(IResourceBuilder<AzureWebPubSubResource>, String) method providing a name:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

The preceding code adds an Azure Web PubSub hub resource named messages, which enables the addition of event handlers. To add an event handler, call the AddEventHandler:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

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

The preceding code adds a worker service project named worker with an external HTTP endpoint. The hub named messages resource is added to the web-pubsub resource, and an event handler is added to the messagesHub resource. The event handler URL is set to the worker service's external HTTP endpoint. For more information, see Azure Web PubSub event handlers.

Generated provisioning Bicep

When you publish your app, .NET Aspire provisioning APIs generate Bicep alongside the manifest file. Bicep is a domain-specific language for defining Azure resources. For more information, see Bicep Overview.

When you add an Azure Web PubSub resource, the following Bicep is generated:

@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 principalType string

param principalId string

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

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

The preceding Bicep is a module that provisions an Azure Web PubSub resource with the following defaults:

• location: The location of the resource group.
• sku: The SKU of the Web PubSub resource, defaults to Free_F1.
• principalId: The principal ID of the Web PubSub resource.
• principalType: The principal type of the Web PubSub resource.
• messages_url_0: The URL of the event handler for the messages hub.
• messages: The name of the hub resource.
• web_pubsub: The name of the Web PubSub resource.
• web_pubsub_WebPubSubServiceOwner: The role assignment for the Web PubSub resource owner. For more information, see Azure Web PubSub Service Owner.
• endpoint: The endpoint of the Web PubSub resource.

The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files.

Customize provisioning infrastructure

All .NET Aspire Azure resources are subclasses of the AzureProvisioningResource type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API. For example, you can configure the kind, consistencyPolicy, locations, and more. The following example demonstrates how to customize the Azure Cosmos DB resource:

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");
    });

The preceding code:

• Chains a call to the ConfigureInfrastructure API:
  • The infra parameter is an instance of the AzureResourceInfrastructure type.
  • The provisionable resources are retrieved by calling the GetProvisionableResources() method.
  • The single WebPubSubService resource is retrieved.
  • The WebPubSubService.Sku object has its name and capacity properties set to Standard_S1 and 5, respectively.
  • A tag is added to the Web PubSub resource with a key of ExampleKey and a value of Example value.

There are many more configuration options available to customize the Web PubSub resource. For more information, see Azure.Provisioning.WebPubSub. For more information, see Azure.Provisioning customization.

Connect to an existing Azure Web PubSub instance

You might have an existing Azure Web PubSub service that you want to connect to. You can chain a call to annotate that your AzureWebPubSubResource is an existing resource:

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...

For more information on treating Azure Web PubSub resources as existing resources, see Use existing Azure resources.

Alternatively, instead of representing an Azure Web PubSub resource, you can add a connection string to the app host. Which is a weakly-typed approach that's based solely on a string value. To add a connection to an existing Azure Web PubSub service, call the AddConnectionString method:

var builder = DistributedApplication.CreateBuilder(args);

var webPubSub = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureWebPubSub("web-pubsub")
    : builder.AddConnectionString("web-pubsub");

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

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

Note

Connection strings are used to represent a wide range of connection information, including database connections, message brokers, endpoint URIs, and other services. In .NET Aspire nomenclature, the term "connection string" is used to represent any kind of connection information.

The connection string is configured in the app host's configuration, typically under User Secrets, under the ConnectionStrings section:

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

For more information, see Add existing Azure resources with connection strings.

Client integration

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

.NET CLI

dotnet add package Aspire.Azure.Messaging.WebPubSub

PackageReference

<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	.NET 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");

Tip

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

After adding the WebPubSubServiceClient, you can retrieve the client instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

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.

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");

Important

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. For example, to retrieve the clients from a service:

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

For more information, see Keyed services in .NET.

Configuration

The .NET 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"
        }
      }
    }
  }
}

For the complete Azure OpenAI client integration JSON schema, see Aspire.Azure.Messaging.WebPubSub/ConfigurationSchema.json.

Use inline delegates

You can configure settings inline:

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

Observability and telemetry

.NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about integration observability and telemetry, see .NET Aspire integrations overview. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

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

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

Tracing

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

• Azure.Messaging.WebPubSub.*

Metrics

The .NET Aspire Azure Web PubSub integration currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. If that changes in the future, this section will be updated to reflect those changes.

See also

• Azure Web PubSub
• .NET Aspire integrations
• .NET Aspire GitHub repo