Compartir a través de

.NET Aspire Azure Azure SignalR Service integración

Incluye:Integración de hosting incluida Sólo integración de hosting — Client integración no incluida, integración no incluida

Azure SignalR Service es un servicio de mensajería en tiempo real totalmente administrado que simplifica la adición de funcionalidad web en tiempo real a las aplicaciones. La .NET AspireAzureAzure SignalR Service integración permite aprovisionar, configurar y conectar fácilmente las aplicaciones de .NET a las instancias de AzureAzure SignalR Service.

En este artículo se describe cómo integrar AzureAzure SignalR Service en las .NET Aspire aplicaciones, que abarcan tanto el hospedaje como la integración de cliente.

Integración de hospedaje

Los modelos de integración de hospedaje .NET AspireAzureAzure SignalR Service presentan los recursos AzureSignalR como los siguientes tipos:

  • AzureSignalRResource: representa un recurso de AzureAzure SignalR Service, incluida la información de conexión al recurso de Azure subyacente.
  • AzureSignalREmulatorResource: representa un emulador para AzureAzure SignalR Service, lo que permite el desarrollo local y las pruebas sin necesidad de una Azure suscripción.

Para acceder a los tipos de hospedaje y las API para expresar estos recursos en el generador de aplicaciones distribuidas, instale .📦Aspire Hosting.Azure.SignalR Paquete NuGet en el proyecto host de la aplicación:

dotnet add package Aspire.Hosting.Azure.SignalR

Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en aplicaciones .NET.

Adición de un recurso de AzureAzure SignalR Service

Para agregar un AzureAzure SignalR Service recurso al proyecto host de la aplicación, llame al método AddAzureSignalR:

var builder = DistributedApplication.CreateBuilder(args);

var signalR = builder.AddAzureSignalR("signalr");

var api = builder.AddProject<Projects.ApiService>("api")
                 .WithReference(signalR)
                 .WaitFor(signalR);

builder.AddProject<Projects.WebApp>("webapp")
       .WithReference(api)
       .WaitFor(api);

// Continue configuring and run the app...

En el ejemplo anterior:

  • Se agrega un AzureAzure SignalR Service recurso denominado signalr .
  • El signalr recurso es referenciado por el api proyecto.
  • El proyecto api es referenciado por el proyecto webapp.

Esta arquitectura permite al webapp proyecto comunicarse con el api proyecto, que a su vez se comunica con el AzureAzure SignalR Service recurso.

Importante

La llamada a AddAzureSignalR habilita implícitamente el soporte de aprovisionamiento. Asegúrese de que el host de la aplicación esté configurado con la suscripción y la ubicación adecuadas Azure . Para obtener más información, consulte aprovisionamiento local: Configuración.

Bicep generado por generación de aprovisionamiento

Cuando agregas un AzureAzure SignalR Service recurso, .NET Aspire genera infraestructura de aprovisionamiento mediante Bicep. El Bicep generado incluye valores predeterminados para ubicación, SKU y asignaciones de roles.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource signalr 'Microsoft.SignalRService/signalR@2024-03-01' = {
  name: take('signalr-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    cors: {
      allowedOrigins: [
        '*'
      ]
    }
    features: [
      {
        flag: 'ServiceMode'
        value: 'Default'
      }
    ]
  }
  kind: 'SignalR'
  sku: {
    name: 'Free_F1'
    capacity: 1
  }
  tags: {
    'aspire-resource-name': 'signalr'
  }
}

output hostName string = signalr.properties.hostName

output name string = signalr.name

El Bicep generado proporciona un punto de partida y puede personalizarse más.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Esto permite la personalización del Bicep generado al proporcionar una API fluida para configurar los recursos Azure mediante la API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>).

builder.AddAzureSignalR("signalr")
    .ConfigureInfrastructure(infra =>
    {
        var signalRService = infra.GetProvisionableResources()
                                  .OfType<SignalRService>()
                                  .Single();

        signalRService.Sku.Name = "Premium_P1";
        signalRService.Sku.Capacity = 10;
        signalRService.PublicNetworkAccess = "Enabled";
        signalRService.Tags.Add("ExampleKey", "Example value");
    });

El código anterior:

Conexión a un AzureAzure SignalR Service existente

Es posible que tenga una AzureAzure SignalR Service existente a la que desea conectarse. Puede encadenar una llamada para indicar que el AzureSignalRResource es un recurso existente.

var builder = DistributedApplication.CreateBuilder(args);

var existingSignalRName = builder.AddParameter("existingSignalRName");
var existingSignalRResourceGroup = builder.AddParameter("existingSignalRResourceGroup");

var signalr = builder.AddAzureSignalR("signalr")
                     .AsExisting(existingSignalRName, existingSignalRResourceGroup);

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

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

Importante

Al llamar a los métodos RunAsExisting, PublishAsExisting o AsExisting para trabajar con recursos que ya están presentes en su suscripción Azure, debe agregar ciertos valores de configuración a su Host de Aplicación para asegurarse de que .NET Aspire pueda localizarlos. Los valores de configuración necesarios incluyen SubscriptionId, AllowResourceGroupCreation, ResourceGroup y Location. Si no los establece, los errores de "Configuración faltante" aparecen en el .NET.NET Aspire panel de control. Para obtener más información sobre cómo establecerlas, consulte Configuración.

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

Nota:

Como alternativa, en lugar de representar un recurso de AzureAzure SignalR Service, puede agregar una cadena de conexión al host de la aplicación. Este enfoque está débilmente tipado y no funciona con asignaciones de roles ni personalizaciones de infraestructura. Para obtener más información, consulte Azure.

Adición de un recurso del AzureAzure SignalR Service emulador

El Azureemulador es una herramienta de desarrollo y pruebas local que emula el comportamiento de Azure SignalR ServiceAzure.Azure SignalR Service Este emulador solo admite el modo sin servidor, que requiere una configuración específica al usar el emulador.

Para usar el emulador, encadene una llamada al RunAsEmulator(IResourceBuilder<AzureSignalRResource>, Action<IResourceBuilder<AzureSignalREmulatorResource>>) método :

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var signalR = builder.AddAzureSignalR("signalr", AzureSignalRServiceMode.Serverless)
                     .RunAsEmulator();

builder.AddProject<Projects.ApiService>("apiService")
       .WithReference(signalR)
       .WaitFor(signalR);

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

En el ejemplo anterior, el RunAsEmulator método configura el AzureAzure SignalR Service recurso para que se ejecute como un emulador. El emulador se basa en la imagen del contenedor mcr.microsoft.com/signalr/signalr-emulator:latest. El emulador se inicia cuando se ejecuta el host de la aplicación y se detiene cuando se detiene el host de la aplicación.

Azure Azure SignalR Service Modos

Aunque el AzureAzure SignalR Service emulador solo admite el modo sin servidor , el AzureAzure SignalR Service recurso se puede configurar para usar cualquiera de los siguientes modos:

  • AzureSignalRServiceMode.Default
  • AzureSignalRServiceMode.Serverless

El modo predeterminado es la configuración "predeterminada" para AzureAzure SignalR Service. Cada modo tiene su propio conjunto de características y limitaciones. Para obtener más información, consulte AzureAzure SignalR Service modos.

Importante

El AzureAzure SignalR Service emulador solo funciona en modo sin servidor y el AddNamedAzureSignalR método no admite el modo sin servidor.

Integración del host del hub

No hay ninguna .NET Aspire oficialAzureSignalR. Sin embargo, hay soporte limitado para experiencias similares. En estos escenarios, AzureAzure SignalR Service actúa como proxy entre el servidor (donde se hospedan Hub o Hub<T>) y el cliente (donde se hospeda SignalR). Enruta AzureAzure SignalR Service el tráfico entre el servidor y el cliente, lo que permite la comunicación en tiempo real.

Importante

Es importante desambiguar entre .NET Aspire las integraciones del cliente y el .NETSignalR cliente. SignalR expone hubs, que actúan como un concepto del lado del servidor, y SignalR los clientes se conectan a esos hubs. Los proyectos de .NET que albergan los hubs de SignalR son los lugares donde se integra con .NET Aspire. El SignalR cliente es una biblioteca independiente que se conecta a esos centros, en un proyecto diferente.

Hay dos paquetes disponibles, cada uno dirigido a escenarios específicos, como administrar la conexión del cliente a AzureAzure SignalR Service y enlazar el recurso AzureAzure SignalR Service. Para empezar, instale el 📦 Microsoft.Azure.SignalR paquete NuGet en el proyecto que hospeda el hub SignalR.

dotnet add package Microsoft.Azure.SignalR

Configurar con nombre AzureAzure SignalR Service en modo predeterminado

En el modo predeterminado , el proyecto de consumo debe basarse en un recurso con nombre AzureAzure SignalR Service . Tenga en cuenta el siguiente diagrama que ilustra la arquitectura de AzureAzure SignalR Service en modo predeterminado :

AzureAzure SignalR Service: diagrama de modo predeterminado.

Para obtener más información sobre el modo predeterminado , vea AzureAzure SignalR Service: Modo predeterminado.

En el SignalR proyecto host del centro de conectividad, configure AzureAzure SignalR Service mediante el encadenamiento de llamadas a .AddSignalR().AddNamedAzureSignalR("name"):

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR()
                .AddNamedAzureSignalR("signalr");

var app = builder.Build();

app.MapHub<ChatHub>("/chat");

app.Run();

El AddNamedAzureSignalR método configura el proyecto para usar el AzureAzure SignalR Service recurso denominado signalr. La cadena de conexión se lee desde la clave ConnectionStrings:signalrde configuración y se cargan valores adicionales desde la Azure:SignalR:signalr sección de configuración.

Nota:

Si usa el AzureSignalR emulador, no puede usar el AddNamedAzureSignalR método .

Configurar AzureAzure SignalR Service en modo sin servidor

Si el host de la aplicación usa el AzureSignalRemulador, también deberá instalar el paquete NuGet de 📦Microsoft.Azure.SignalR.Management.

dotnet add package Microsoft.Azure.SignalR.Management

Azure SignalR El modo sin servidor no requiere que se ejecute un servidor concentrador. El AzureAzure SignalR Service es responsable de mantener las conexiones de los clientes. Además, en este modo, no puede usar centros tradicionales SignalR, como Hub, Hub<T> o IHubContext<THub>. En su lugar, configure un punto de conexión ascendente que normalmente es un Azure activador de funciónSignalR. Tenga en cuenta el diagrama siguiente que muestra la arquitectura de AzureAzure SignalR Service en modo sin servidor :

AzureAzure SignalR Service: diagrama del modo sin servidor.

Para obtener más información sobre el modo sin servidor, vea AzureAzure SignalR Service: Modo sin servidor.

En un proyecto destinado a comunicarse con AzureAzure SignalR Service, registre los servicios adecuados llamando a AddSignalR y, a continuación, registre ServiceManager mediante la cadena de conexión signalr y agregue un punto de conexión /negotiate.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
{
   return new ServiceManagerBuilder()
       .WithOptions(options =>
       {
           options.ConnectionString = builder.Configuration.GetConnectionString("signalr");
       })
       .BuildServiceManager();
});

var app = builder.Build();

app.MapPost("/negotiate", async (string? userId, ServiceManager sm, CancellationToken token) =>
{
    // The creation of the ServiceHubContext is expensive, so it's recommended to 
    // only create it once per named context / per app run if possible.
    var context = await sm.CreateHubContextAsync("messages", token);
    
    var negotiateResponse = await context.NegotiateAsync(new NegotiationOptions
    {
        UserId = userId
    }, token);
    
    // The JSON serializer options need to be set to ignore null values, otherwise the
    // response will contain null values for the properties that are not set.
    // The .NET SignalR client will not be able to parse the response if the null values are present.
    // For more information, see https://github.com/dotnet/aspnetcore/issues/60935.
    return Results.Json(negotiateResponse, new JsonSerializerOptions(JsonSerializerDefaults.Web)
    {
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
    });
});

app.Run();

El código anterior configura el AzureAzure SignalR Service usando la clase ServiceManagerBuilder, pero no llama a AddSignalR ni a MapHub. Estas dos extensiones no son necesarias con el modo sin servidor . La cadena de conexión se lee de la clave ConnectionStrings:signalr de configuración. Cuando se usa el emulador, solo está disponible el punto de conexión HTTP. Dentro de la aplicación, puede usar la ServiceManager instancia para crear un ServiceHubContext. ServiceHubContext se usa para difundir mensajes y administrar las conexiones a los clientes.

El /negotiate punto de conexión es necesario para establecer una conexión entre el cliente que se conecta y el AzureAzure SignalR Service. ServiceHubContext se crea mediante el ServiceManager.CreateHubContextAsync método , que toma el nombre del centro como parámetro. Se llama al método NegotiateAsync para negociar la conexión con AzureAzure SignalR Service, que devuelve un token de acceso y la dirección URL a la que se va a conectar el cliente.

Para obtener más información, consulte Uso AzureSignalR del SDK de administración.

Consulte también