Azure Web PubSub - Hosting integration

Hosting integration

The 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 AppHost project, install the 📦 Aspire.Hosting.Azure.WebPubSub NuGet package:

Aspire CLI

Aspire CLI — Aspire.Hosting.Azure.WebPubSub Paket hinzufügen

aspire add azure-webpubsub

Die Aspire CLI ist interaktiv; das passende Suchergebnis wählen, wenn gefragt:

Aspire CLI — Beispielausgabe

Select an integration to add:

> azure-webpubsub (Aspire.Hosting.Azure.WebPubSub)
> Other results listed as selectable options...

Hinweis

Gibt es nur ein Ergebnis, wird es automatisch gewählt. Die Version muss trotzdem bestätigt werden.

apphost.cs (C# file-based app)

C# — AppHost.cs

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

PackageReference (*.csproj)

XML — Aspire.Hosting.Azure.WebPubSub Paketreferenz hinzufügen

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

Add an Azure Web PubSub resource

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

C# — AppHost.cs

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 AppHost project. The WithReference method passes the connection information to the ExampleProject project.

Achtung

When you call AddAzureWebPubSub, it implicitly calls AddAzureProvisioning—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

When you add an Azure Web PubSub resource, you can also add a child hub resource. The hub resource is a logical grouping of connections and event handlers. To add an Azure Web PubSub hub resource to your AppHost project, chain a call to the AddHub method:

C# — AppHost.cs

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

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

C# — AppHost.cs

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

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.

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:

C# — AppHost.cs

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.

Hinweis

Alternatively, instead of representing an Azure Web PubSub resource, you can add a connection string to the AppHost. This approach is weakly-typed and doesn’t work with role assignments or infrastructure customizations.

Provisioning-generated Bicep

When you publish your app, 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:

web-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
  properties: {
    disableLocalAuth: true
  }
  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

The preceding Bicep is a module that provisions an Azure Web PubSub resource. Additionally, role assignments are created for the Azure resource in a separate module:

web-pubsub-roles.bicep

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

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 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 API:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

Connection properties

When you reference an Azure Web PubSub resource using WithReference, the following connection properties are made available to the consuming project:

Property Name	Description
Uri	The HTTPS endpoint for the Web PubSub service, typically https://<resource-name>.webpubsub.azure.com/

Hinweis

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