Auf Englisch lesen

Freigeben über

.NET Aspire Azure Web PubSub Einbindung

  • Artikel

umfasst: Hostingintegration und 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, um sie in Ihrem App-Host Projekt auszudrücken, installieren Sie die 📦Aspire. Hosting.Azure. WebPubSub NuGet-Paket:

dotnet add package Aspire.Hosting.Azure.WebPubSub

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

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

Um Ihrem App-Hostprojekt eine AzureWeb PubSub Hubressource hinzuzufügen, verketten Sie einen Aufruf an die AddHub(IResourceBuilder<AzureWebPubSubResource>, String) Methode, die einen Namen bereitstellt:

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

Der vorangehende Code fügt eine AzureWeb PubSub Hubressource namens messageshinzu, die 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("messages");

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 Workerdiensts festgelegt. Weitere Informationen finden Sie unter AzureWeb PubSub Ereignishandler.

Generiertes Bereitstellungs-Skript Bicep

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

Die vorangehende Bicep ist ein Modul, das eine AzureWeb PubSub Ressource mit den folgenden Standardwerten bereit stellt:

  • location: Der Speicherort der Ressourcengruppe.
  • sku: Die SKU der Web PubSub-Ressource ist standardmäßig auf Free_F1festgelegt.
  • principalId: Die Principal-ID der Web PubSub Ressource.
  • principalType: Der Prinzipaltyp der Web PubSub Ressource.
  • messages_url_0: Die URL des Ereignishandlers für den messages Hub.
  • messages: Der Name der Hubressource.
  • web_pubsub: Der Name der Web PubSub Ressource.
  • web_pubsub_WebPubSubServiceOwner: Die Rollenzuweisung für den Web PubSub Eigentümer der Ressource. Weitere Informationen finden Sie unter AzureWeb PubSub Dienstverantwortlicher.
  • endpoint: Der Endpunkt der Web PubSub Ressource.

Das generierte Bicep ist ein Einstiegspunkt und wird durch Änderungen an der Bereitstellungsinfrastruktur in C# beeinflusst. Anpassungen an der Bicep-Datei werden direkt überschrieben, daher sollten Sie Änderungen über die C#-Bereitstellungs-APIs vornehmen, um sicherzustellen, dass sie in den generierten Dateien widergespiegelt werden.

Bereitstellungsinfrastruktur anpassen

Alle .NET AspireAzure Ressourcen sind Unterklassen des AzureProvisioningResource Typs. Dieser Typ ermöglicht die Anpassung der generierten Bicep durch Bereitstellung einer flüssigen API zum Konfigurieren der Azure-Ressourcen—mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. 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:

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.

Alternativ können Sie dem Host der App anstelle einer AzureWeb PubSub-Ressource eine Verbindungszeichenfolge hinzufügen. Dies ist ein schwach typisierter Ansatz, der ausschließlich auf einem string-Wert basiert. Rufen Sie zum Hinzufügen einer Verbindung zu einem vorhandenen AzureWeb PubSub-Dienst die AddConnectionString-Methode auf:

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

Hinweis

Verbindungszeichenfolgen werden verwendet, um eine Vielzahl von Verbindungsinformationen darzustellen, einschließlich Datenbankverbindungen, Nachrichtenbroker, Endpunkt-URIs und andere Dienste. In der .NET.NET Aspire Nomenklatur wird der Begriff "Verbindungsstring" verwendet, um jede Art von Verbindungsinformationen darzustellen.

Die Verbindungszeichenfolge wird in der Konfiguration des App-Hosts konfiguriert, in der Regel unter "Benutzergeheimnisse", unter dem Abschnitt ConnectionStrings:

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

Weitere Informationen finden Sie unter Hinzufügen vorhandener Azure Ressourcen mit Verbindungszeichenfolgen.

ClientIntegration

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

dotnet add package Aspire.Azure.Messaging.WebPubSub

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 clientaufwendigen Projekts die AddAzureWebPubSubServiceClient Erweiterungsmethode auf, um eine WebPubSubServiceClient für die Verwendung über den Container zum Einfügen von Abhängigkeiten 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 die WebPubSubServiceClienthinzugefügt haben, können Sie die Clientinstanz mithilfe der Abhängigkeitseinfügung 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:

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 Clientinstanzen mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Clients aus einem Service ab:

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

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 Sie eine 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"
        }
      }
    }
  }
}

Die vollständige AzureOpenAI Clientintegration JSON Schema finden Sie unter Aspire.Azure. Messaging.WebPubSub/ConfigurationSchema.json.

Verwendung von Inline-Delegaten

Sie können Einstellungen inline konfigurieren:

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

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Tracing- und Metrikkonfigurationen ein, die manchmal als den Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrationsbeobachtbarkeit und Telemetrie finden Sie unter .NET.NET Aspire Integrationen Übersicht. Abhängig vom unterstützenden Dienst 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

Verfolgung

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 Metriken aufgrund von Einschränkungen mit dem Azure SDK für .NETnicht. Wenn sich dies in Zukunft ändert, wird dieser Abschnitt aktualisiert, um diese Änderungen widerzuspiegeln.

Siehe auch