Azure WebJobs Serviço do SignalR biblioteca de clientes para .NET – versão 1.11.2

Artigo
09/15/2023

Essa extensão fornece funcionalidade para acessar Serviço do Azure SignalR de uma função do Azure.

Introdução

Instalar o pacote

Instale o cliente Serviço do SignalR com o NuGet:

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

Pré-requisitos

Assinatura do Azure: Para usar os serviços do Azure, incluindo Serviço do Azure SignalR, você precisará de uma assinatura. Se você não tiver uma conta existente do Azure, poderá se inscrever para uma avaliação gratuita ou usar seus benefícios de assinatura do Visual Studio ao criar uma conta.
Recurso do Azure SignalR: Para usar Serviço do SignalR biblioteca de clientes, você também precisará de um recurso do Azure SignalR. Se você não estiver familiarizado com a criação de recursos do Azure, convém seguir o guia passo a passo para criar um recurso do SignalR usando o portal do Azure. Lá, você também pode encontrar instruções detalhadas para usar os modelos da CLI do Azure, Azure PowerShell ou ARM (Azure Resource Manager) para criar um recurso do SignalR.

Para criar rapidamente o recurso do SignalR necessário no Azure e receber uma cadeia de conexão para eles, você pode implantar nosso modelo de exemplo clicando em:

Depois que a instância é implantada, abra-a no portal e localize sua página de Configurações. Altere a configuração do Modo de Serviço para Sem servidor.

Autenticar o cliente

Para que Serviço do SignalR cliente acesse o recurso do SignalR, ele precisará entender como autenticar com ele. O meio mais fácil para fazer isso é usar uma cadeia de conexão que pode ser encontrada no Portal do Azure ou usando a CLI / do Azure Azure PowerShell snippet abaixo.

Snippet da CLI do Azure:

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

Azure PowerShell snippet:

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

A ConnectionStringSetting propriedade de associações signalR (incluindo SignalRAttribute, SignalRConnectionInfoAttributeetc SignalRTriggerAttribute .) é usada para especificar a propriedade de configuração que armazena a cadeia de conexão. Se não for especificado, espera-se que a propriedade AzureSignalRConnectionString contenha a cadeia de conexão.

Para desenvolvimento local, use o local.settings.json arquivo para armazenar a cadeia de conexão:

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

Quando implantado, use as configurações do aplicativo para definir a cadeia de conexão.

Principais conceitos

Cliente do Serviço do SignalR versus cliente SignalR

Cliente do Serviço do SignalR: significa essa biblioteca. Ele fornece funcionalidades do servidor SignalR em um estilo sem servidor.

Cliente SignalR: um conceito oposto do servidor SignalR. Consulte ASP.NET Core clientes do SignalR para obter mais informações.

Associação de entrada de informações da conexão do SignalR

SignalRConnectionInfoA associação de entrada facilita a geração do token necessário para que os clientes do SignalR iniciem uma conexão com Serviço do Azure SignalR.

Siga o tutorial de associação de entrada de Informações de Conexão do Azure SignalR para saber mais sobre a associação de entrada de Informações de Conexão do SignalR.

Associação de saída do SignalR

SignalR A associação de saída permite :

enviar mensagens para todas as conexões, para uma conexão, para um usuário, para um grupo.
adicionar/remover conexões/usuários em um grupo.

Siga a associação de saída do Azure SignalR para saber mais sobre a associação de saída do SignalR.

Gatilho do SignalR

O gatilho SignalR permite que uma função seja executada quando uma mensagem é enviada para Serviço do Azure SignalR.

Siga o gatilho do Azure SignalR para saber mais sobre o gatilho do SignalR.

Cenários com suporte

Negocie por um cliente do SignalR.
Gerencie um grupo como adicionar/remover um único usuário/conexão em um grupo.
Envie mensagens para um único usuário/conexão, para um grupo, para todos os usuários/conexões.
Use várias instâncias Serviço do Azure SignalR para resiliência e recuperação de desastre em Azure Functions. Consulte detalhes em Suporte a várias instâncias de Serviço do Azure SignalR em Azure Functions.

Exemplos

Negociação para o cliente SignalR

Para que um cliente se conecte ao SignalR, ele precisa obter a URL do hub cliente do SignalR e um token de acesso. Chamamos o processo de "negociação".

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

Transmitir mensagens individuais

Para transmitir mensagens para todas as conexões em um hub de uma única invocação de Função do Azure, você pode aplicar o SignalR atributo ao valor retornado da função. O valor retornado deve ser do 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>" }
    };
}

Você também pode usar um out parâmetro do 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>" }
    };
}

Transmitir várias mensagens

Para transmitir várias mensagens para todas as conexões em um hub de uma única invocação de Função do Azure, você pode aplicar o SignalR atributo ao 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>" }
    });
}

Enviar mensagens para uma conexão, usuário ou grupo

Para enviar mensagens para uma conexão, usuário ou grupo, a função é semelhante à transmissão de mensagens acima, exceto que você especifica ConnectionId, UserId ou GroupName nas propriedades de SignalRMessage.

Aqui está um exemplo para enviar mensagens a um usuário usando a associação de valor retornado.

[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>" }
    };
}

Gatilho de conexão do cliente SignalR

Para disparar uma função quando um cliente SignalR é conectado ou desconectado, você pode aplicar o SignalRTrigger atributo ao InvocationContext parâmetro .

Aqui está um exemplo para registrar a ID de conexão quando um cliente SignalR está conectado. Verifique se o segundo parâmetro do SignalRTrigger construtor é connections, que significa que a categoria do gatilho são conexões. O terceiro

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

Gatilho de mensagem do cliente SignalR

Para disparar uma função quando um cliente SignalR envia uma mensagem, você pode aplicar o SignalRTrigger atributo ao InvocationContext parâmetro , aplicar o SignalRParameter atributo a cada parâmetro cujo nome corresponde ao nome do parâmetro em sua mensagem.

Aqui está um exemplo para registrar o conteúdo da mensagem quando um cliente do SignalR envia uma mensagem com o 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}.");
}

Solução de problemas

Consulte Monitorar Azure Functions para obter diretrizes de solução de problemas de função.
Guia de solução de problemas para Serviço do Azure SignalR

Próximas etapas

Leia a introdução ao Azure Functions ou à criação de um guia de funções do Azure

Participante

Confira nosso CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Compartilhar via