.NET AspireAzureWeb PubSub integración

Incluye: Integración de alojamiento —&— Client integración

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

La integración de hospedamiento .NET.NET AspireAzure Web PubSub modela los recursos 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 de hub Web PubSub, que contiene la configuración de un hub. Por ejemplo, puede especificar si el centro permite conexiones anónimas o agregar controladores de eventos al centro.

Para acceder a estos tipos y a las API para expresarlos dentro de su proyecto app host, instale el paquete 📦Aspire.Hosting.Azure.WebPubSub NuGet:

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.

Añadir un recurso de concentrador AzureWeb PubSub

Al añadir un recurso AzureWeb PubSub, también puede añadir un recurso de concentrador secundario. El recurso del concentrador es un agrupamiento lógico de conexiones y manejadores de eventos. Para añadir un recurso de hub AzureWeb PubSub a su proyecto de alojamiento de aplicaciones, encadene una llamada al método AddHub proporcionando un nombre de recurso y de 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...

El código anterior agrega un AzureWeb PubSub recurso del centro denominado messages y un nombre del centro de messageHub , 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(name: "messages", hubName: "messageHub");

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 URL del controlador de eventos se establece en el punto final HTTP externo del servicio de trabajador. Para obtener más información, consulte AzureWeb PubSub controladores de eventos.

Bicep generado por el aprovisionamiento

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 definir recursos Azure. Para obtener más información, consulte Descripción 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 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

El Bicep anterior es un módulo que aprovisiona un recurso AzureWeb PubSub. Además, las asignaciones de roles se crean para el Azure recurso en un módulo independiente:

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

El Bicep generado es un punto de partida y se ve influido por los cambios en la infraestructura de aprovisionamiento en C#. Las personalizaciones realizadas directamente en el archivo Bicep se sobrescribirán, por lo tanto, haga cambios a través de las API de aprovisionamiento de C# para asegurarse de que se reflejen 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 proporcionando una API fluida para configurar los recursos Azure mediante la API 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 el único 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 anotar que su 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.

Integración con 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.

dotnet add package Aspire.Azure.Messaging.WebPubSub

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

Tipos de clientes compatibles Web PubSub

La biblioteca admite los siguientes tipos de cliente Web PubSub:

Agregar cliente Web PubSub

En el archivo Program.cs del proyecto que consume el cliente, 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");

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 ejemplos de 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");

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

Si deseas registrar una única instancia de WebPubSubServiceClient con un nombre de conexión específico, hay una sobrecarga que usa el nombre de la conexión como clave del servicio. Llame al método AddKeyedAzureWebPubSubServiceClient. Este método registra el cliente como un servicio singleton en el contenedor de inserción de dependencias.

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

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. Debe suministrarse 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 ConnectionStrings. Se admiten dos formatos de conexión:

• Punto de conexión del servicio (recomendado): Utiliza el punto final 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 desde el archivo de configuración usando la clave Aspire:Azure:Messaging:WebPubSub.

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

Para obtener el esquema completo de integración AzureOpenAI de cliente JSON, consulte 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

Seguimiento

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.

Consulte también

• Azure Web PubSub
• .NET.NET Aspire integraciones
• .NET AspireGitHub Repo