Compartir a través de

Uso del SDK de administración de Azure SignalR

  • Artículo

El SDK de administración de Azure SignalR le ayuda a administrar clientes de SignalR a través de Azure SignalR Service directamente, como mensajes de difusión. Por lo tanto, este SDK podría usarse, entre otros, en entornos sin servidor. Puede usar este SDK para administrar los clientes de SignalR conectados a Azure SignalR Service en cualquier entorno, como en una aplicación de consola, en una función de Azure o en un servidor web.

Nota:

Para ver las guías de la versión 1.9.x del SDK y anteriores, vaya al SDK de administración de Azure SignalR Service (heredado). También puede leer la Guía de migración.

Importante

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración.

Una cadena de conexión incluye la información de autorización necesaria para que la aplicación acceda al servicio Azure Web PubSub. La clave de acceso dentro de la cadena de conexión es similar a una contraseña raíz para el servicio. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura, proteger la cadena de conexión mediante Microsoft Entra ID y autorizar el acceso con Microsoft Entra ID.

Evite distribuirlas a otros usuarios, codificarlas de forma rígida o guardarlas en un archivo de texto sin formato al que puedan acceder otros usuarios. Rote sus claves si cree que se han puesto en peligro.

Características

Característica Transitorio Persistente
Difusión ✔️ ✔️
Difundir excepto algunos clientes ✔️ ✔️
Enviar a un cliente ✔️ ✔️
Enviar a clientes ✔️ ✔️
Envío a un usuario ✔️ ✔️
Enviar a los usuarios ✔️ ✔️
Envío a un grupo ✔️ ✔️
Enviar a grupos ✔️ ✔️
Enviar a un grupo excepto algunos clientes ✔️ ✔️
Agregar un usuario a un grupo ✔️ ✔️
Quitar un usuario de un grupo ✔️ ✔️
Comprobar si un usuario está en un grupo ✔️ ✔️
Admitir varias instancias de servicio de SignalR ❌ ✔️
Compatibilidad con clientes de MessagePack desde la versión 1.21.0 desde la versión 1.20.0
Error transitorio de reintento desde la versión 1.22.0 ❌

Las características solo se incluyen con la nueva API

Característica Transitorio Persistente
Comprobar si existe una conexión ✔️ Desde la versión 1.11.0
Comprobar si existe un grupo ✔️ Desde la versión 1.11.0
Comprobar si existe un usuario ✔️ Desde la versión 1.11.0
Cierre de una conexión de cliente ✔️ Desde la versión 1.11.0

  • Puede encontrar más detalles sobre los distintos modos aquí.

  • Puede encontrar un ejemplo completo sobre el SDK de administración aquí.

Uso

En esta sección se muestra cómo usar el SDK de administración.

Creación de Service Manager

Compile la instancia de ServiceManager desde un ServiceManagerBuilder.

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura, proteger la cadena de conexión mediante Microsoft Entra ID y autorizar el acceso con Microsoft Entra ID.


var serviceManager = new ServiceManagerBuilder()
                    .WithOptions(option =>
                    {
                        option.ConnectionString = "<Your Azure SignalR Service Connection String>";
                    })
                    .WithLoggerFactory(loggerFactory)
                    .BuildServiceManager();

Puede usar ServiceManager para comprobar el estado del punto de conexión de Azure SignalR y crear el contexto del centro de servicios. En la sección siguiente se proporcionan detalles sobre cómo crear el contexto del centro de servicios.

Para comprobar el estado del punto de conexión de Azure SignalR, puede usar el método ServiceManager.IsServiceHealthy. Si tiene varios puntos de conexión de Azure SignalR, solo se comprueba el primer punto de conexión.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Creación de un contexto del centro de servicios

Cree la instancia de ServiceHubContext a partir de ServiceManager:

var serviceHubContext = await serviceManager.CreateHubContextAsync("<Your Hub Name>",cancellationToken);

Negociación

En el modo predeterminado, el SDK de Azure SignalR Service expone un punto de conexión /<Your Hub Name>/negotiate para la negociación. Los clientes de SignalR llegan a este punto de conexión y, a continuación, redirigen a Azure SignalR Service más adelante.

En el modo sin servidor, se recomienda hospedar un punto de conexión de negociación para atender la solicitud de negociación de los clientes de SignalR y redirigir los clientes a Azure SignalR Service.

Sugerencia

Obtenga más información sobre el redireccionamiento en el Protocolo de negociación de SignalR.

Tanto el punto de conexión como el token de acceso son útiles cuando desea redirigir los clientes de SignalR a Azure SignalR Service.

Puede usar la instancia de ServiceHubContext para generar la dirección URL del punto de conexión y el token de acceso correspondiente para que los clientes de SignalR se conecten a Azure SignalR Service.

var negotiationResponse = await serviceHubContext.NegotiateAsync(new (){UserId = "<Your User Id>"});

Supongamos que el punto de conexión del centro es http://<Your Host Name>/<Your Hub Name>, entonces, el punto de conexión de negociación es http://<Your Host Name>/<Your Hub Name>/negotiate. Una vez hospedado el punto de conexión de negociación, puede usar los clientes de SignalR para conectarse al centro de la siguiente manera:

var connection = new HubConnectionBuilder().WithUrl("http://<Your Host Name>/<Your Hub Name>").Build();
await connection.StartAsync();

Aquí puede encontrar el ejemplo sobre cómo usar el SDK de administración para redirigir los clientes de SignalR a Azure SignalR Service.

Envío de mensajes y administración de grupos

La clase ServiceHubContext que compilamos a partir de ServiceHubContextBuilder es una clase que implementa y extiende IServiceHubContext. Puede usarla para enviar mensajes a los clientes y administrar los grupos.

try
{
    // Broadcast
    await hubContext.Clients.All.SendAsync(callbackName, obj1, obj2, ...);

    // Send to user
    await hubContext.Clients.User(userId).SendAsync(callbackName, obj1, obj2, ...);

    // Send to group
    await hubContext.Clients.Group(groupId).SendAsync(callbackName, obj1, obj2, ...);

    // add user to group
    await hubContext.UserGroups.AddToGroupAsync(userId, groupName);

    // remove user from group
    await hubContext.UserGroups.RemoveFromGroupAsync(userId, groupName);
}
finally
{
    await hubContext.DisposeAsync();
}

Centro fuertemente tipado

Un centro fuertemente tipado es un modelo de programación que puede extraer los métodos de cliente en una interfaz, de modo que evita errores como errores ortográficos en el nombre del método o pasar los tipos de parámetro incorrectos.

Supongamos que tenemos un método cliente denominado ReceivedMessage con dos parámetros de cadena. Sin centros fuertemente tipados, se transmite a los clientes a través de hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). Con centros fuertemente tipados, primero debe definir una interfaz como esta:

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

Y, a continuación, debe crear un contexto de centro fuertemente tipado, que implemente IHubContext<Hub<T>, T>; T es la interfaz del método de cliente:

ServiceHubContext<IChatClient> serviceHubContext = await serviceManager.CreateHubContextAsync<IChatClient>(hubName, cancellationToken);

Por último, podría invocar directamente el método:

await Clients.All.ReceiveMessage(user, message);

Excepto por la diferencia de enviar mensajes, podría negociar o administrar grupos tanto con ServiceHubContext<T> como con ServiceHubContext.

Obtenga más información sobre los centros fuertemente tipados en los documentos de ASP.NET Core aquí.

Tipo de transporte

Este SDK puede comunicarse con Azure SignalR Service con dos tipos de transporte:

  • Transitorio: cree una solicitud Http de Azure SignalR Service para cada mensaje enviado. El SDK simplemente encapsula la API de REST de Azure SignalR Service en modo transitorio. Resulta útil cuando no se puede establecer una conexión WebSocket.
  • Persistente: cree primero una conexión WebSocket y, a continuación, envíe todos los mensajes de esta conexión. Resulta útil cuando se envía un gran número de mensajes.

Resumen de los comportamientos de serialización de los argumentos en los mensajes

Serialización Transitorio Persistente
Biblioteca JSON predeterminada Newtonsoft.Json Igual que ASP.NET Core SignalR:
Newtonsoft.Json para .NET Standard 2.0;
System.Text.Json para .NET Core App 3.1 y versiones posteriores
Compatibilidad con clientes de MessagePack desde la versión 1.21.0 desde la versión 1.20.0

Serialización de JSON

En el SDK de administración, los argumentos de método enviados a los clientes se serializan en JSON. Tenemos varias maneras de personalizar la serialización JSON. Se muestran todas las formas en el orden del más recomendado al menos recomendado.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

La forma más recomendada es usar una clase abstracta general ObjectSerializer, ya que admite diferentes bibliotecas de serialización JSON como System.Text.Json y Newtonsoft.Json, y se aplica a todos los tipos de transporte. Por lo general, no es necesario que implemente ObjectSerializer usted mismo, ya que ya se proporcionan implementaciones JSON útiles para System.Text.Json y Newtonsoft.Json.

  • Cuando se usa System.Text.Json como biblioteca de procesamiento JSON, builtin JsonObjectSerializer usa System.Text.Json.JsonSerializer para la serialización o deserialización. Este es un ejemplo para usar la nomenclatura camel case para la serialización JSON:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new JsonObjectSerializer(new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        }));
    })
    .BuildServiceManager();

  • Cuando se usa Newtonsoft.Json como biblioteca de procesamiento JSON, instale primero el paquete Microsoft.Azure.Core.NewtonsoftJson desde NuGet mediante la CLI de .NET:

    dotnet add package Microsoft.Azure.Core.NewtonsoftJson

    Este es un ejemplo para usar la nomenclatura camel case con NewtonsoftJsonObjectSerializer:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new NewtonsoftJsonObjectSerializer(new JsonSerializerSettings()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        }));
    })
    .BuildServiceManager();

  • Al usar otras bibliotecas de procesamiento JSON

    También puede implementar ObjectSerializer por su cuenta. Los vínculos siguientes pueden ayudar:

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Este método solo es para los usuarios Newtonsoft.Json. Este es un ejemplo para usar la nomenclatura camel case:

var serviceManager = new ServiceManagerBuilder()
    .WithNewtonsoftJson(o =>
    {
        o.PayloadSerializerSettings = new JsonSerializerSettings
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        };
    })
    .BuildServiceManager();
ServiceManagerOptions.JsonSerializerSettings (en desuso)

Este método solo se aplica al tipo de transporte transitorio. No usar.

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.JsonSerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    })
    .BuildServiceManager();

Serialización del paquete de mensajes

  1. Debe instalar el paquete Microsoft.AspNetCore.SignalR.Protocols.MessagePack.

  2. Para agregar un protocolo MessagePack en paralelo con el protocolo JSON predeterminado:

    var serviceManagerBuilder = new ServiceManagerBuilder()
    .AddHubProtocol(new MessagePackHubProtocol());

  3. Para controlar completamente los protocolos del centro, puede usar

        var serviceManagerBuilder = new ServiceManagerBuilder()
        .WithHubProtocols(new MessagePackHubProtocol(), new JsonHubProtocol());

    WithHubProtocols primero borra los protocolos existentes y, a continuación, agrega los nuevos protocolos. También puede usar este método para quitar el protocolo JSON y usar solo MessagePack.

Para el modo transitorio, de manera predeterminada, el lado del servicio convierte la carga JSON en la carga de MessagePack y es la forma heredada de admitir MessagePack. Sin embargo, se recomienda agregar explícitamente un protocolo de centro de MessagePack ya que la forma heredada podría no funcionar como se espera.

Reintento de solicitudes HTTP

Para el modo transitorio, este SDK proporciona la capacidad de volver a enviar automáticamente las solicitudes cuando se producen errores transitorios, siempre y cuando las solicitudes sean idempotentes. Para habilitar esta capacidad, puede usar la propiedad ServiceManagerOptions.RetryOptions.

En concreto, se reintentan los siguientes tipos de solicitudes:

  • En el caso de las solicitudes de mensajes que envían mensajes a los clientes de SignalR, el SDK vuelve a intentar la solicitud si el código de estado de la respuesta HTTP es mayor que 500. Cuando el código de respuesta HTTP es igual a 500, podría indicar un tiempo de espera en el lado de servicio y volver a intentar la solicitud podría dar lugar a mensajes duplicados.

  • Para otros tipos de solicitudes, como agregar una conexión a un grupo, el SDK reintenta la solicitud en las condiciones siguientes:

    1. El código de estado de la respuesta HTTP está en el intervalo 5xx o la solicitud agota el tiempo de espera con un código de estado 408 (tiempo de espera de solicitud).
    2. Se ha agotado el tiempo de espera de la solicitud con una duración mayor que la longitud de tiempo de espera configurada en ServiceManagerOptions.HttpClientTimeout.

El SDK solo puede reintentar solicitudes idempotentes, que son solicitudes que no tienen ningún otro efecto si se repiten. Si las solicitudes no son idempotentes, es posible que tenga que controlar los reintentos manualmente.

Pasos siguientes

En este artículo, se obtiene información sobre cómo usar SignalR Service en las aplicaciones. Consulte los artículos siguientes para obtener más información sobre SignalR Service.

Aspectos internos de Azure SignalR Service

Inicio rápido: creación de una sala de chat con SignalR Service