Biblioteca cliente de Azure WebJobs SignalR Service para .NET: versión 1.11.2

Artículo
09/15/2023

Esta extensión proporciona funcionalidad para acceder a Azure SignalR Service desde una función de Azure.

Introducción

Instalar el paquete

Instale el cliente SignalR Service con NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.SignalRService

Requisitos previos

Suscripción de Azure: Para usar servicios de Azure, incluida Azure SignalR Service, necesitará una suscripción. Si no tiene una cuenta de Azure existente, puede registrarse para obtener una evaluación gratuita o usar las ventajas de la suscripción de Visual Studio al crear una cuenta.
Recurso de Azure SignalR: Para usar SignalR Service biblioteca cliente, también necesitará un recurso de Azure SignalR. Si no está familiarizado con la creación de recursos de Azure, puede seguir la guía paso a paso para crear un recurso de SignalR mediante el Azure Portal. Allí también puede encontrar instrucciones detalladas para usar la CLI de Azure, Azure PowerShell o plantillas de Azure Resource Manager (ARM) para crear un recurso de SignalR.

Para crear rápidamente el recurso de SignalR necesario en Azure y recibir una cadena de conexión para ellos, puede implementar nuestra plantilla de ejemplo haciendo clic en:

Una vez implementada la instancia, ábrala en el portal y busque su página de configuración. Cambie la configuración del modo de servicio a Sin servidor.

Autenticar el cliente

Para que SignalR Service cliente acceda al recurso de SignalR, deberá comprender cómo autenticarse con él. Los medios más fáciles para hacerlo es usar una cadena de conexión que se puede encontrar en Azure Portal o mediante la CLI / de Azure Azure PowerShell fragmento de código siguiente.

Fragmento de código de la CLI de Azure:

az signalr key list -n <your-resource-name> -g <your-resource-group-name> --query primaryKey -o tsv

Azure PowerShell fragmento de código:

Get-AzSignalRKey -ResourceGroupName <your-resource-name> -Name <your-resource-name>

La ConnectionStringSetting propiedad de los enlaces de SignalR (incluido SignalRAttribute, SignalRConnectionInfoAttribute, etc SignalRTriggerAttribute .) se usa para especificar la propiedad de configuración que almacena la cadena de conexión. Si no se especifica, se espera que la propiedad AzureSignalRConnectionString contenga la cadena de conexión.

Para el desarrollo local, use el local.settings.json archivo para almacenar la cadena de conexión:

{
  "Values": {
    "<connection_name>": "<connection-string>"
  }
}

Cuando se implemente, use la configuración de la aplicación para establecer la cadena de conexión.

Conceptos clave

Cliente de SignalR Service frente a cliente de SignalR

Cliente de SignalR Service : significa esta biblioteca. Proporciona funcionalidades de servidor signalR en un estilo sin servidor.

Cliente de SignalR: un concepto opuesto del servidor signalR. Consulte ASP.NET Core clientes de SignalR para obtener más información.

Enlace de entrada de información de conexión de SignalR

SignalRConnectionInfoEl enlace de entrada facilita la generación del token necesario para que los clientes de SignalR inicien una conexión a Azure SignalR Service.

Siga el tutorial de enlace de entrada de información de conexión de Azure SignalR para obtener más información sobre el enlace de entrada de información de conexión de SignalR.

Enlace de salida de SignalR

SignalR El enlace de salida permite :

enviar mensajes a todas las conexiones, a una conexión, a un usuario, a un grupo.
agregar o quitar conexiones o usuarios de un grupo.

Siga el enlace de salida de Azure SignalR para más información sobre el enlace de salida de SignalR.

Desencadenador signalR

El desencadenador SignalR permite ejecutar una función cuando se envía un mensaje a Azure SignalR Service.

Siga el desencadenador de Azure SignalR para más información sobre el desencadenador de SignalR.

Escenarios admitidos

Negociar para un cliente de SignalR.
Administrar un grupo como agregar o quitar un único usuario o conexión en un grupo.
Enviar mensajes a un único usuario o conexión, a un grupo, a todos los usuarios o conexiones.
Use varias instancias de Azure SignalR Service para la resistencia y la recuperación ante desastres en Azure Functions. Consulte los detalles de Compatibilidad con varias instancias de Azure SignalR Service en Azure Functions.

Ejemplos

Negociación para el cliente de SignalR

Para que un cliente se conecte a SignalR, debe obtener la dirección URL del centro de cliente de SignalR y un token de acceso. Llamamos al proceso como "negociación".

[FunctionName("Negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req,
    [SignalRConnectionInfo(HubName = "<hub_name>", UserId = "<user_id>")] SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

Difundir mensajes individuales

Para difundir mensajes a todas las conexiones de un centro desde una única invocación de Azure Functions, puede aplicar el SignalR atributo al valor devuelto de la función. El valor devuelto debe ser de tipo SignalRMessage.

[FunctionName("sendOneMessageWithReturnValueBinding")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

También puede usar un out parámetro de tipo SignalRMessage.

[FunctionName("messages")]
public static void SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req, [SignalR(HubName = "<hub_name>")] out SignalRMessage message)
{
    message = new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

Difundir varios mensajes

Para difundir varios mensajes a todas las conexiones de un centro desde una sola invocación de Azure Functions, puede aplicar el SignalR atributo al IAsyncCollector<SignalRMessage> parámetro .

[FunctionName("messages")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
    [SignalR(HubName = "<hub_name>")] IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
    new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    });
}

Envío de mensajes a una conexión, usuario o grupo

Para enviar mensajes a una conexión, usuario o grupo, la función es similar a la difusión de mensajes anteriores, excepto que se especifica ConnectionIdo UserIdGroupName en las propiedades de SignalRMessage.

Este es un ejemplo para enviar mensajes a un usuario mediante el enlace de valores devueltos.

[FunctionName("messages")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessageToUser(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        UserId = "<user_id>",
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

Desencadenador de conexión de cliente de SignalR

Para desencadenar una función cuando un cliente de SignalR se conecta o se desconecta, puede aplicar el SignalRTrigger atributo al InvocationContext parámetro .

Este es un ejemplo para registrar el identificador de conexión cuando un cliente de SignalR está conectado. Asegúrese de que el segundo parámetro del SignalRTrigger constructor es connections, que significa la categoría del desencadenador es connections. El tercero

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("<hubName>", "connections", "connected")] InvocationContext invocationContext, ILogger logger)
{
    logger.LogInformation($"{invocationContext.ConnectionId} was connected.");
}

Desencadenador de mensajes de cliente de SignalR

Para desencadenar una función cuando un cliente de SignalR envía un mensaje, puede aplicar el SignalRTrigger atributo al InvocationContext parámetro , aplicar el SignalRParameter atributo a cada parámetro cuyo nombre coincida con el nombre del parámetro en el mensaje.

Este es un ejemplo para registrar el contenido del mensaje cuando un cliente de SignalR envía un mensaje con el destino "SendMessage".

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("SignalRTest", "messages", "SendMessage")] InvocationContext invocationContext, [SignalRParameter] string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

Solución de problemas

Consulte Supervisión Azure Functions para obtener instrucciones para la solución de problemas de funciones.
Guía para la solución de problemas de Azure SignalR Service

Pasos siguientes

Lea la introducción a Azure Functions o creación de una guía de azure Functions.

Contribuciones

Consulte nuestra CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de