.NET AspireAzureWeb PubSub Einbindung

2025-06-28

Enthält: Hosting-Integration —&— Client Integration

Azure Web PubSub ist ein vollständig verwalteter Echtzeitnachrichtendienst, mit dem Sie Webanwendungen mit WebSockets und Veröffentlichungsabonnentmustern in Echtzeit erstellen können. Mit der .NET AspireAzureWeb PubSub-Integration können Sie eine Verbindung mit AzureWeb PubSub Instanzen aus Ihren .NET Anwendungen herstellen.

Integration von Hosting

Das .NET.NET AspireAzure Web PubSub Hostintegrationsmodell bildet die Web PubSub Ressourcen als die folgenden Typen ab:

AzureWebPubSubResource: Stellt eine AzureWeb PubSub Ressource dar, einschließlich Verbindungsinformationen zur zugrunde liegenden Azure Ressource.
AzureWebPubSubHubResource: Stellt eine Web PubSub Hubeinstellungsressource dar, die die Einstellungen für einen Hub enthält. Sie können z. B. angeben, ob der Hub anonyme Verbindungen zulässt oder Dem Hub Ereignishandler hinzufügen.

Um auf diese Typen und APIs zuzugreifen und sie in Ihrem App-Host-Projekt zu verwenden, installieren Sie das 📦Aspire.Hosting.Azure.WebPubSub NuGet-Paket.

.NET CLI
PaketReferenz

dotnet add package Aspire.Hosting.Azure.WebPubSub

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

Weitere Informationen finden Sie unter dotnet add package oder Paketabhängigkeiten in .NET-Anwendungen verwalten.

Hinzufügen einer AzureWeb PubSub-Ressource

Um Ihrem App-Hostprojekt eine AzureWeb PubSub Ressource hinzuzufügen, rufen Sie die AddAzureWebPubSub Methode auf, die einen Namen bereitstellt:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Der vorangehende Code fügt dem App-Hostprojekt eine AzureWeb PubSub Ressource mit dem Namen web-pubsub hinzu. Die WithReference Methode übergibt die Verbindungsinformationen an das ExampleProject Projekt.

Wichtig

Wenn Sie AddAzureWebPubSubaufrufen, wird dabei implizit AddAzureProvisioning(IDistributedApplicationBuilder)aufgerufen, wodurch die Unterstützung zur dynamischen Generierung von Azure-Ressourcen während des Anwendungsstarts hinzugefügt wird. Die App muss das entsprechende Abonnement und den entsprechenden Standort konfigurieren. Weitere Informationen finden Sie unter Lokale Bereitstellung: Konfiguration.

Hinzufügen einer AzureWeb PubSub Hubressource

Wenn Sie eine AzureWeb PubSub-Ressource hinzufügen, können Sie auch eine untergeordnete Hub-Ressource hinzufügen. Die Hubressource ist eine logische Gruppierung von Verbindungen und Ereignishandlern. Um eine AzureWeb PubSub-Hub-Ressource zu Ihrem App-Hostprojekt hinzuzufügen, verketten Sie einen Aufruf der AddHub-Methode, indem Sie einen Ressourcen- und Hubnamen bereitstellen:

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

Der vorangehende Code fügt eine AzureWeb PubSub Hubressource namens messages und einen Hubnamen hinzu messageHub , der das Hinzufügen von Ereignishandlern ermöglicht. Rufen Sie zum Hinzufügen eines Ereignishandlers die AddEventHandlerauf:

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

Der vorangehende Code fügt ein Workerdienstprojekt mit dem Namen worker mit einem externen HTTP-Endpunkt hinzu. Der Hub mit dem Namen messages Ressource wird der web-pubsub Ressource hinzugefügt, und der messagesHub-Ressource wird ein Ereignishandler hinzugefügt. Die Ereignishandler-URL wird auf den externen HTTP-Endpunkt des Worker-Dienstes festgelegt. Weitere Informationen finden Sie unter AzureWeb PubSub Ereignishandler.

Durch Bereitstellung generierte Bicep-Datei

Wenn Sie Ihre App veröffentlichen, generieren .NET.NET Aspire Bereitstellungs-APIs Bicep zusammen mit der Manifestdatei. Bicep ist eine domänenspezifische Sprache für die Definition von Azure-Ressourcen. Weitere Informationen finden Sie unter Bicep Overview.

Wenn Sie eine AzureWeb PubSub Ressource hinzufügen, wird das folgende Bicep generiert:

@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

Das vorangehende Bicep ist ein Modul, das eine AzureWeb PubSub Ressource bereitstellt. Darüber hinaus werden Rollenzuweisungen für die Azure Ressource in einem separaten Modul erstellt:

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

Das generierte Bicep ist ein Einstiegspunkt und wird durch Änderungen an der Bereitstellungsinfrastruktur in C# beeinflusst. Direkte Anpassungen an der Bicep-Datei werden überschrieben. Nehmen Sie daher Änderungen über die C#-Bereitstellungs-APIs vor, damit sie in den generierten Dateien reflektiert werden.

Bereitstellungsinfrastruktur anpassen

Alle .NET AspireAzure Ressourcen sind Unterklassen des AzureProvisioningResource Typs. Dieser Typ ermöglicht die Anpassung des generierten Bicep, indem eine Fluent-API bereitgestellt wird, die es ermöglicht, die Azure-Ressourcen mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API zu konfigurieren. Sie können z. B. die kind, consistencyPolicy, locationsund mehr konfigurieren. Im folgenden Beispiel wird veranschaulicht, wie die AzureAzure Cosmos DB Ressource angepasst wird:

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

Der vorherige Code:

Verkettet einen Aufruf an die ConfigureInfrastructure-API.
- Der infra-Parameter ist eine Instanz des typs AzureResourceInfrastructure.
- Die bereitstellbaren Ressourcen werden durch Aufrufen der GetProvisionableResources()-Methode abgerufen.
- Die einzige WebPubSubService-Ressource wird abgerufen.
- Das WebPubSubService.Sku-Objekt hat seine Namen- bzw. Kapazitätseigenschaften auf Standard_S1 bzw. 5festgelegt.
- Ein Tag wird der Web PubSub-Ressource mit dem Schlüssel ExampleKey und dem Wert Example value hinzugefügt.

Es stehen viele weitere Konfigurationsoptionen zum Anpassen der Web PubSub Ressource zur Verfügung. Weitere Informationen finden Sie unter Azure.Provisioning.WebPubSub. Weitere Informationen finden Sie unter Azure.Provisioning Anpassung.

Herstellen einer Verbindung mit einer vorhandenen AzureWeb PubSub Instanz

Möglicherweise verfügen Sie über einen vorhandenen AzureWeb PubSub Dienst, mit dem Sie eine Verbindung herstellen möchten. Sie können einen Aufruf verketten, um anzumerken, dass Ihr AzureWebPubSubResource eine vorhandene Ressource ist.

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

Weitere Informationen zum Behandeln von AzureWeb PubSub Ressourcen als vorhandene Ressourcen finden Sie unter Verwenden vorhandener Azure Ressourcen.

Hinweis

Anstatt eine Azure AI Search-Ressource zu repräsentieren, können Sie auch eine Verbindungszeichenfolge zum Host der App hinzufügen. Dieser Ansatz ist schwach typiert und funktioniert nicht mit Rollenzuweisungen oder Infrastrukturanpassungen. Weitere Informationen finden Sie unter Hinzufügen vorhandener Azure Ressourcen mit Verbindungszeichenfolgen.

ClientIntegration

Die .NET AspireAzureWeb PubSub-Clientintegration wird verwendet, um eine Verbindung zu einem AzureWeb PubSub-Dienst mithilfe der WebPubSubServiceClient herzustellen. Um mit der Integration des .NET AspireAzureWeb PubSub-Dienstclients zu beginnen, installieren Sie das 📦Aspire.Azure.Messaging.WebPubSub NuGet-Paket in der Anwendung.

.NET CLI
PaketReferenz

dotnet add package Aspire.Azure.Messaging.WebPubSub

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

Unterstützte Web PubSub Clienttypen

Die folgenden Web PubSub Clienttypen werden von der Bibliothek unterstützt:

Azure Clienttyp	Azure Optionsklasse	.NET.NET Aspire Einstellungsklasse
WebPubSubServiceClient	WebPubSubServiceClientOptions	AzureMessagingWebPubSubSettings

Füge Web PubSub-Client hinzu

Rufen Sie in der Program.cs-Datei Ihres Projekts, das den Client verwendet, die AddAzureWebPubSubServiceClient-Erweiterungsmethode auf, um einen WebPubSubServiceClient für die Verwendung über den Dependency Injection-Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter:

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

Tipp

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der Web PubSub-Ressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Hinzufügen einer AzureWeb PubSub Ressource.

Nachdem Sie den WebPubSubServiceClient hinzugefügt haben, können Sie die Clientinstanz mithilfe der Dependency Injection abrufen. Wenn Sie beispielsweise das Datenquellenobjekt aus einem Beispieldienst abrufen möchten, definieren Sie es als Konstruktorparameter, und stellen Sie sicher, dass die ExampleService Klasse im Container zum Einfügen von Abhängigkeiten registriert ist:

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

Weitere Informationen finden Sie unter:

Azure.Messaging.WebPubSub-Dokumentation für Beispiele zur Verwendung des WebPubSubServiceClient.
Dependency Injection in .NET für Details zur Dependency Injection.

Gekennzeichneten Web PubSub-Client hinzufügen

Es kann Situationen geben, in denen Sie mehrere WebPubSubServiceClient-Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Um Clients mit dem Schlüssel Web PubSub zu registrieren, rufen Sie die Methode AddKeyedAzureWebPubSubServiceClient auf:

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

Wichtig

Bei der Verwendung von Schlüsseldiensten wird erwartet, dass Ihre Web PubSub-Ressource zwei benannte Hubs konfiguriert hat, einen für die messages und einen für die commands.

Anschließend können Sie die Client-Instanzen mithilfe von Dependency Injection abrufen. So rufen Sie beispielsweise die Clients aus einem Service ab:

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

Wenn Sie eine einzelne WebPubSubServiceClient Instanz mit einem bestimmten Verbindungsnamen registrieren möchten, gibt es eine Überladung, die den Verbindungsnamen als Dienstschlüssel verwendet. Rufen Sie die AddKeyedAzureWebPubSubServiceClient-Methode auf. Diese Methode registriert den Client als Singletondienst im Container zum Einfügen von Abhängigkeiten.

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

Weitere Informationen finden Sie unter Schlüsselbasierte Dienste in .NET.

Konfiguration

Die .NET AspireAzureWeb PubSub-Bibliothek bietet mehrere Optionen zum Konfigurieren der AzureWeb PubSub Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts. Es muss entweder ein Endpoint oder ein ConnectionString bereitgestellt werden.

Verwenden einer Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von AddAzureWebPubSubServiceClientden Namen der Verbindungszeichenfolge angeben:

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

Die Verbindungsinformationen werden aus dem Konfigurationsabschnitt ConnectionStrings abgerufen. Zwei Verbindungsformate werden unterstützt:

Dienstendpunkt (empfohlen): Verwendet den Dienstendpunkt mit DefaultAzureCredential.

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

Verbindungszeichenfolge: Enthält einen Zugriffsschlüssel.

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

Konfigurationsanbieter verwenden

Die Bibliothek unterstützt Microsoft.Extensions.Configuration. Die Einstellungen werden mithilfe des Aspire:Azure:Messaging:WebPubSub Schlüssels aus der Konfiguration geladen:

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

Das Schema der vollständigen AzureOpenAI Client-Integration JSON finden Sie unter Aspire.Azure.Messaging.WebPubSub/ConfigurationSchema.json.

Inline-Delegaten verwenden

Sie können Einstellungen inline konfigurieren:

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

Einblick und Telemetrie

.NET .NET Aspire-Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeit bezeichnet werden. Weitere Informationen zum Einblick in Integrationen und zur Telemetrie finden Sie in der .NET.NET AspireÜbersicht über Integrationen. Abhängig vom Unterstützungsdienst unterstützen einige Integrationen möglicherweise nur bestimmte Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefunktionen können auch mithilfe der im Abschnitt Konfiguration dargestellten Techniken deaktiviert werden.

Protokollierung

Die .NET AspireAzureWeb PubSub Integration verwendet die folgenden Protokollkategorien:

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

Ablaufverfolgung

Die .NET AspireAzureWeb PubSub Integration wird die folgenden Nachverfolgungsaktivitäten mithilfe von OpenTelemetryausgeben:

Azure.Messaging.WebPubSub.*

Kennzahlen

Die .NET AspireAzureWeb PubSub-Integration unterstützt derzeit standardmäßig keine Metriken aufgrund von Einschränkungen mit dem Azure SDK für .NET. Wenn sich dies in Zukunft ändert, wird dieser Abschnitt aktualisiert, um diese Änderungen widerzuspiegeln.

Freigeben über