.NET Aspire Azure Web PubSub integración

Artículo
03/22/2025

incluye: integración de hospedaje de e integración de Client

Azure Web PubSub es un servicio de mensajería en tiempo real totalmente administrado que permite crear aplicaciones web en tiempo real mediante WebSockets y patrones de publicación y suscripción. La integración de .NET AspireAzureWeb PubSub permite conectarse a instancias de AzureWeb PubSub desde las aplicaciones de .NET.

Integración de hospedaje

El .NET.NET AspireAzure Web PubSub modela los recursos de integración de alojamiento de Web PubSub como los siguientes tipos:

AzureWebPubSubResource: representa un recurso de AzureWeb PubSub, incluida la información de conexión al recurso de Azure subyacente.
AzureWebPubSubHubResource: representa un recurso de configuración del centro de Web PubSub, que contiene la configuración de un centro. Por ejemplo, puede especificar si el centro permite conexiones anónimas o agregar controladores de eventos al centro.

Para acceder a estos tipos y API para expresarlos dentro del proyecto de host de aplicación de , instale el paquete de NuGet 📦Aspire.Hosting.Azure.WebPubSub.

CLI de
PackageReference

dotnet add package Aspire.Hosting.Azure.WebPubSub

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

Para obtener más información, consulte dotnet add package o Manage package dependencies in .NET applications.

Adición de un recurso de AzureWeb PubSub

Para agregar un recurso de AzureWeb PubSub al proyecto host de la aplicación, llame al método AddAzureWebPubSub proporcionando un nombre:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

El código anterior agrega un recurso de AzureWeb PubSub denominado web-pubsub al proyecto host de la aplicación. El método WithReference pasa la información de conexión al proyecto de ExampleProject.

Importante

Al llamar a AddAzureWebPubSub, llama implícitamente a AddAzureProvisioning(IDistributedApplicationBuilder), lo que agrega compatibilidad para generar recursos de Azure dinámicamente durante el inicio de la aplicación. La aplicación debe configurar la suscripción y la ubicación adecuadas. Para obtener más información, consulte aprovisionamiento local: Configuración.

Añadir un recurso de concentrador AzureWeb PubSub

Para añadir un recurso del hub de AzureWeb PubSub a tu proyecto anfitrión de la aplicación, sigue una llamada al método AddHub(IResourceBuilder<AzureWebPubSubResource>, String) proporcionando un nombre:

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

El código anterior agrega un recurso del centro de AzureWeb PubSub denominado messages, que permite agregar controladores de eventos. Para agregar un controlador de eventos, llame al 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...

El código anterior agrega un proyecto de servicio de trabajo denominado worker con un punto de conexión HTTP externo. El centro denominado messages recurso se agrega al recurso web-pubsub y se agrega un controlador de eventos al recurso messagesHub. La dirección URL del controlador de eventos se establece en el punto de conexión HTTP externo del servicio de trabajo. Para obtener más información, consulte AzureWeb PubSub controladores de eventos.

Provisión generada por el script Bicep

Al publicar tu aplicación, las APIs de aprovisionamiento .NET.NET Aspire generan Bicep junto con el archivo de manifiesto. Bicep es un lenguaje específico de dominio para la definición de recursos de Azure. Para obtener más información, consulte Vista general de Bicep.

Al agregar un recurso AzureWeb PubSub, se genera el siguiente 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 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}'

Bicep anterior es un módulo que aprovisiona un recurso de AzureWeb PubSub con los valores predeterminados siguientes:

location: ubicación del grupo de recursos.
sku: la SKU del recurso de Web PubSub, el valor predeterminado es Free_F1.
principalId: el identificador principal del recurso Web PubSub.
principalType: el tipo principal del recurso de Web PubSub.
messages_url_0: la dirección URL del controlador de eventos del hub messages.
messages: El nombre del recurso del hub.
web_pubsub: el nombre del recurso de Web PubSub.
web_pubsub_WebPubSubServiceOwner: La asignación de rol para el propietario del recurso Web PubSub. Para obtener más información, consulte AzureWeb PubSub propietario del servicio.
endpoint: extremo del recurso de Web PubSub.

El Bicep generado es un punto de partida y está influenciado por los cambios en la infraestructura de aprovisionamiento realizados en C#. Las personalizaciones en el archivo de Bicep se sobrescribirán directamente, por lo que se realizarán cambios a través de las API de aprovisionamiento de C# para asegurarse de que se reflejan en los archivos generados.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo permite la personalización del Bicep generado al proporcionar una API fluida para configurar los recursos de Azure, utilizando la API de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar el kind, consistencyPolicy, locations, etc. En el ejemplo siguiente se muestra cómo personalizar el recurso de 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");
    });

El código anterior:

Encadena una llamada a API ConfigureInfrastructure:
- El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
- Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
- Se recupera un solo recurso WebPubSubService.
- El objeto WebPubSubService.Sku tiene sus propiedades de nombre y capacidad establecidas en Standard_S1 y 5, respectivamente.
- Se agrega una etiqueta al recurso de Web PubSub con una clave de ExampleKey y un valor de Example value.

Hay muchas más opciones de configuración disponibles para personalizar el recurso de Web PubSub. Para obtener más información, consulte Azure.Provisioning.WebPubSub. Para obtener más información, vea Azure.Provisioning personalización.

Conexión a una instancia de AzureWeb PubSub existente

Es posible que tenga un servicio AzureWeb PubSub existente al que desea conectarse. Puede encadenar una llamada para indicar que el AzureWebPubSubResource es un recurso existente.

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

Para obtener más información sobre cómo tratar los recursos de AzureWeb PubSub como recursos existentes, consulte Uso de recursos de Azure existentes.

Como alternativa, en lugar de representar un recurso de AzureWeb PubSub, puede agregar una cadena de conexión al host de la aplicación. Este es un enfoque débilmente tipado que se basa únicamente en un valor de string. Para agregar una conexión a un servicio de AzureWeb PubSub existente, llame al método 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:

Las cadenas de conexión se usan para representar una amplia gama de información de conexión, incluidas las conexiones de base de datos, los agentes de mensajes, los URI de punto de conexión y otros servicios. En .NET.NET Aspire nomenclatura, el término "cadena de conexión" se usa para representar cualquier tipo de información de conexión.

La cadena de conexión se configura en la configuración del host de la aplicación, normalmente en Secretos de usuario, en la sección ConnectionStrings:

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

Para obtener más información, consulte Agregar recursos existentes con Azure cadenas de conexión.

integración Client

La integración de cliente de .NET AspireAzureWeb PubSub se usa para conectarse a un servicio de AzureWeb PubSub mediante el WebPubSubServiceClient. Para empezar a trabajar con la integración de cliente del servicio .NET AspireAzureWeb PubSub, instale el paquete NuGet "📦Aspire.Azure.Messaging.WebPubSub" en la aplicación.

CLI de
PackageReference

dotnet add package Aspire.Azure.Messaging.WebPubSub

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

Tipos de cliente de Web PubSub admitidos

La biblioteca admite los siguientes tipos de cliente Web PubSub:

tipo de cliente Azure	clase Azure de opciones	clase de configuración de .NET.NET Aspire
WebPubSubServiceClient	WebPubSubServiceClientOptions	AzureMessagingWebPubSubSettings

Agregar cliente Web PubSub

En el archivo Program.cs de su proyecto cliente consumidor, llame al método de extensión AddAzureWebPubSubServiceClient para registrar un WebPubSubServiceClient para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión:

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

Sugerencia

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso Web PubSub en el proyecto host de la aplicación. Para obtener más información, consulte sobre cómo añadir un recurso AzureWeb PubSub.

Después de agregar el WebPubSubServiceClient, puede recuperar la instancia de cliente mediante la inyección de dependencias. Por ejemplo, para recuperar el objeto de origen de datos de un servicio de ejemplo, definalo como parámetro de constructor y asegúrese de que la clase ExampleService esté registrada con el contenedor de inserción de dependencias:

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

Para obtener más información, consulte:

Azure. Documentación de Messaging.WebPubSub para obtener ejemplos sobre el uso de la WebPubSubServiceClient.
Inyección de dependencias en .NET para obtener más información sobre la inyección de dependencias.

Adición de un cliente de Web PubSub con clave

Puede haber situaciones en las que quiera registrar varias instancias de WebPubSubServiceClient con nombres de conexión diferentes. Para registrar clientes de Web PubSub con clave, llame al método AddKeyedAzureWebPubSubServiceClient:

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

Importante

Cuando se utilizan servicios identificados, se espera que el recurso de Web PubSub configure dos hubs nombrados, uno para el messages y otro para el commands.

Luego, puedes recuperar las instancias del cliente utilizando la inyección de dependencias. Por ejemplo, para recuperar los clientes de un servicio:

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

Para obtener más información, consulte Servicios con clave en .NET.

Configuración

La biblioteca .NET AspireAzureWeb PubSub proporciona varias opciones para configurar la conexión de AzureWeb PubSub en función de los requisitos y convenciones del proyecto. Se debe proporcionar un Endpoint o un ConnectionString.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar a AddAzureWebPubSubServiceClient:

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

La información de conexión se recupera de la sección de configuración de ConnectionStrings. Se admiten dos formatos de conexión:

Punto de conexión de servicio (recomendado): usa el punto de conexión de servicio con DefaultAzureCredential.
```
{
  "ConnectionStrings": {
    "web-pubsub": "https://{account_name}.webpubsub.azure.com"
  }
}
```

cadena de conexión: incluye una clave de acceso.

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

Uso de proveedores de configuración

La biblioteca admite Microsoft.Extensions.Configuration. Carga la configuración mediante la clave Aspire:Azure:Messaging:WebPubSub:

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

Para consultar el esquema completo de integración de cliente de AzureOpenAI en JSON, vea Aspire.Azure.Messaging.WebPubSub/ConfigurationSchema.json.

Utilice delegados en línea

Puede configurar las configuraciones en línea:

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

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.

Registro

La integración de .NET AspireAzureWeb PubSub usa las siguientes categorías de registro:

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

Rastrear

La integración de .NET AspireAzureWeb PubSub emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

Azure.Messaging.WebPubSub.*

Métricas

Actualmente, la integración de .NET AspireAzureWeb PubSub no admite métricas de forma predeterminada debido a limitaciones con el SDK de Azure para .NET. Si eso cambia en el futuro, esta sección se actualizará para reflejar esos cambios.

Compartir a través de