integrazione di .NET AspireAzureWeb PubSub

Articolo
17/04/2025

include integrazione dell'hosting e integrazione di Client

Azure Web PubSub è un servizio di messaggistica in tempo reale completamente gestito che consente di creare applicazioni Web in tempo reale usando WebSocket e modelli di pubblicazione-sottoscrizione. L'integrazione .NET AspireAzureWeb PubSub consente di connettersi alle istanze di AzureWeb PubSub dalle applicazioni .NET.

Integrazione del servizio di hosting

Il .NET.NET AspireAzure Web PubSub che ospita l'integrazione modella le risorse Web PubSub come i tipi seguenti:

AzureWebPubSubResource: rappresenta una risorsa AzureWeb PubSub, incluse le informazioni di connessione alla risorsa Azure sottostante.
AzureWebPubSubHubResource: rappresenta una risorsa delle impostazioni dell'hub Web PubSub che contiene le impostazioni per un hub. Ad esempio, è possibile specificare se l'hub consente connessioni anonime o aggiungere gestori eventi all'hub.

Per accedere a questi tipi e API per esprimerli all'interno del progetto host dell'app, installare il pacchetto NuGet 📦Aspire.Hosting.Azure.WebPubSub:

.NET CLI dell'interfaccia della riga di comando
PackageReference

dotnet add package Aspire.Hosting.Azure.WebPubSub

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

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere una risorsa AzureWeb PubSub

Per aggiungere una risorsa AzureWeb PubSub al progetto host dell'app, chiamare il metodo AddAzureWebPubSub specificando un nome:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Il codice precedente aggiunge una risorsa AzureWeb PubSub denominata web-pubsub al progetto host dell'app. Il metodo WithReference passa le informazioni di connessione al progetto ExampleProject.

Importante

Quando chiami AddAzureWebPubSub, chiama implicitamente AddAzureProvisioning(IDistributedApplicationBuilder), che aggiunge il supporto per la generazione dinamica delle risorse Azure durante l'avvio dell'app. L'app deve configurare l'abbonamento e la località appropriate. Per ulteriori informazioni, vedere Configurazione locale: Configurazione.

Aggiungere una risorsa hub AzureWeb PubSub

Quando si aggiunge una AzureWeb PubSub risorsa, è anche possibile aggiungere una risorsa hub subordinata. La risorsa hub è un raggruppamento logico di connessioni e gestori eventi. Per aggiungere una AzureWeb PubSub risorsa hub al progetto host dell'app, concatenare una chiamata al AddHub metodo fornendo una risorsa e un nome hub:

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

Il codice precedente aggiunge una AzureWeb PubSub risorsa hub denominata messages e un nome hub di messageHub , che consente l'aggiunta di gestori eventi. Per aggiungere un gestore eventi, chiamare il AddEventHandler:

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

Il codice precedente aggiunge un progetto di servizio di lavoro denominato worker con un endpoint HTTP esterno. L'hub denominato messages risorsa viene aggiunto alla risorsa web-pubsub e un gestore eventi viene aggiunto alla risorsa messagesHub. L'URL del gestore eventi è impostato sull'endpoint HTTP esterno del servizio di lavoro. Per altre informazioni, vedere AzureWeb PubSub gestori eventi.

Generazione dell'approvvigionamento Bicep

Quando si pubblica l'app, le API di provisioning .NET.NET Aspire generano Bicep insieme al file del manifesto. Bicep è un linguaggio specifico del dominio per la definizione di risorse Azure. Per ulteriori informazioni, vedere Panoramica di Bicep.

Quando si aggiunge una risorsa AzureWeb PubSub, viene generato il seguente 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
  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

Il Bicep precedente è un modulo che provvede una AzureWeb PubSub risorsa. Inoltre, le assegnazioni di ruolo vengono create per la Azure risorsa in un modulo separato:

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

Il Bicep generato è un punto di partenza e viene influenzato dalle modifiche apportate all'infrastruttura di provisioning in C#. Le personalizzazioni apportate direttamente al file Bicep verranno sovrascritte, quindi è necessario effettuare modifiche tramite le API di provisioning C# per garantire che vengano riflesse nei file generati.

Personalizzare l'infrastruttura di approvvigionamento

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure, utilizzando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Ad esempio, è possibile configurare il kind, consistencyPolicy, locationse altro ancora. L'esempio seguente illustra come personalizzare la risorsa AzureAzure Cosmos DB:

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

Il codice precedente:

Concatena una chiamata all'API ConfigureInfrastructure:
- Il parametro infra è un'istanza del tipo AzureResourceInfrastructure.
- Le risorse provisionabili vengono recuperate chiamando il metodo GetProvisionableResources().
- Viene recuperata la singola risorsa WebPubSubService.
- L'oggetto WebPubSubService.Sku ha le proprietà nome e capacità impostate rispettivamente su Standard_S1 e 5.
- Un tag viene aggiunto alla risorsa Web PubSub con una chiave di ExampleKey e un valore di Example value.

Sono disponibili molte altre opzioni di configurazione per personalizzare la risorsa Web PubSub. Per altre informazioni, vedere Azure.Provisioning.WebPubSub. Per maggiori informazioni, vedere la personalizzazione Azure.Provisioning.

Connettersi a un'istanza di AzureWeb PubSub esistente

Potrebbe essere disponibile un servizio di AzureWeb PubSub esistente a cui connettersi. È possibile concatenare una chiamata per annotare che il AzureWebPubSubResource è una risorsa esistente:

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

Per altre informazioni sulla gestione delle risorse di AzureWeb PubSub come risorse esistenti, vedere Usare risorse Azure esistenti.

In alternativa, anziché rappresentare una risorsa AzureWeb PubSub, è possibile aggiungere una stringa di connessione all'host dell'app. Si tratta di un approccio di tipo debole basato esclusivamente su un valore string. Per aggiungere una connessione a un servizio di AzureWeb PubSub esistente, chiamare il metodo AddConnectionString:

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

Nota

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker di messaggi, URI degli endpoint e altri servizi. Nella nomenclatura .NET.NET Aspire, il termine "stringa di connessione" è utilizzato per rappresentare qualsiasi tipo di informazioni di connessione.

La stringa di connessione è configurata nella configurazione dell'host dell'app, in genere in Segreti utente, nella sezione ConnectionStrings:

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

Per ulteriori informazioni, vedere Azure.

Client integrazione

L'integrazione client .NET AspireAzureWeb PubSub viene usata per connettersi a un servizio AzureWeb PubSub usando il WebPubSubServiceClient. Per iniziare a usare l'integrazione client del servizio .NET AspireAzureWeb PubSub, installare il pacchetto NuGet 📦Aspire.Azure.Messaging.WebPubSub nell'applicazione.

.NET CLI dell'interfaccia della riga di comando
PackageReference

dotnet add package Aspire.Azure.Messaging.WebPubSub

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

Tipi di client Web PubSub supportati

I tipi di client Web PubSub seguenti sono supportati dalla libreria:

Azure tipo di client	Opzioni classe Azure	classe di impostazioni .NET.NET Aspire
WebPubSubServiceClient	WebPubSubServiceClientOptions	AzureMessagingWebPubSubSettings

Aggiungere Web PubSub client

Nel file Program.cs del progetto cliente-consumatore, chiamare il metodo di estensione AddAzureWebPubSubServiceClient per registrare un WebPubSubServiceClient da usare tramite il contenitore di iniezione delle dipendenze. Il metodo accetta un parametro del nome di connessione:

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

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Web PubSub nel progetto host dell'app. Per altre informazioni, vedere Aggiungere una risorsa AzureWeb PubSub.

Dopo aver aggiunto il WebPubSubServiceClient, puoi recuperare l'istanza del client usando la dependency injection. Ad esempio, per recuperare l'oggetto sorgente dati da un servizio di esempio, definiscilo come parametro del costruttore e assicurati che la classe ExampleService sia registrata con il contenitore di iniezione delle dipendenze.

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

Per altre informazioni, vedere:

Azure. Consultare la documentazione di Messaging.WebPubSub per esempi su come utilizzare il WebPubSubServiceClient.
iniezione di dipendenze in .NET per informazioni dettagliate sull'iniezione di dipendenze.

Aggiungere un cliente con chiave Web PubSub

In alcuni casi potrebbe essere necessario registrare più istanze di WebPubSubServiceClient con nomi di connessione diversi. Per registrare i client Web PubSub con chiave, chiamare il metodo AddKeyedAzureWebPubSubServiceClient:

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

Importante

Quando si usano i servizi con chiave, è previsto che la risorsa Web PubSub ha configurato due hub denominati, uno per il messages e uno per l'commands.

È quindi possibile recuperare le istanze client usando l'iniezione di dipendenze. Ad esempio, per recuperare i client da un servizio:

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

Se si vuole registrare una singola WebPubSubServiceClient istanza con un nome di connessione specifico, è presente un overload che usa il nome della connessione come chiave del servizio. Chiamare il metodo AddKeyedAzureWebPubSubServiceClient . Questo metodo registra il client come servizio singleton nel contenitore di inserimento delle dipendenze.

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

Per altre informazioni, vedere Servizi con chiave in .NET.

Configurazione

La libreria .NET AspireAzureWeb PubSub offre più opzioni per configurare la connessione AzureWeb PubSub in base ai requisiti e alle convenzioni del progetto. È necessario specificare un Endpoint o un ConnectionString.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama AddAzureWebPubSubServiceClient:

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

Le informazioni di connessione vengono recuperate dalla sezione di configurazione ConnectionStrings. Sono supportati due formati di connessione:

Nodo di servizio (scelta consigliata): utilizza l'endpoint del servizio con DefaultAzureCredential.
```
{
  "ConnectionStrings": {
    "web-pubsub": "https://{account_name}.webpubsub.azure.com"
  }
}
```

Stringa di connessione: include una chiave di accesso.

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

Usare i fornitori di configurazione

La libreria supporta Microsoft.Extensions.Configuration. Carica le impostazioni dalla configurazione usando la chiave Aspire:Azure:Messaging:WebPubSub:

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

Per lo schema AzureOpenAIJSON di integrazione client completa, vedere Aspire.Azure. Messaging.WebPubSub/ConfigurationSchema.json.

Usare delegati inline

È possibile configurare le impostazioni inline:

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

Osservabilità e telemetria

.NET .NET Aspire le integrazioni impostano automaticamente registrazione, tracciamento e metriche, talvolta conosciute come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireAzureWeb PubSub usa le categorie di log seguenti:

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

Tracciamento

L'integrazione .NET AspireAzureWeb PubSub genererà le attività di traccia seguenti usando OpenTelemetry:

Azure.Messaging.WebPubSub.*

Metriche

L'integrazione .NET AspireAzureWeb PubSub attualmente non supporta le metriche per impostazione predefinita a causa di limitazioni con Azure SDK per .NET. Se tali modifiche verranno apportate in futuro, questa sezione verrà aggiornata in modo da riflettere tali modifiche.

Vedere anche

Collabora con noi su GitHub

L'origine di questo contenuto è disponibile in GitHub, in cui è anche possibile creare ed esaminare i problemi e le richieste pull. Per ulteriori informazioni, vedere la guida per i collaboratori.

Feedback su .NET Aspire

.NET Aspire è un progetto di open source. Selezionare un collegamento per fornire feedback:

Apri un problema di documentazione Inviare commenti e suggerimenti per il prodotto

Risorse aggiuntive

Formazione

Modulo

Personalizzare un'app .NET Aspire per usare le risorse di Azure esistenti - Training

In questo modulo si apprenderà come spostare i servizi di backup per l'app .NET Aspire ospitata in Azure dai contenitori ai servizi nativi di Azure.

Certificazione

Microsoft Certified: Azure Developer Associate - Certifications

Progettare soluzioni end-to-end in Microsoft Azure per creare Funzioni di Azure, implementare e gestire app Web, sviluppare soluzioni che usano Archiviazione di Azure e altro ancora.

Il futuro ti appartiene

Condividi tramite