Associação de gatilho do Serviço do SignalR para Azure Functions

Use a associação de gatilho do SignalR para responder às mensagens enviadas do Serviço do Azure SignalR. Quando a função é acionada, as mensagens transmitidas à função são analisadas como um objeto json.

No modo sem servidor do Serviço do SignalR, o Serviço do SignalR usa o recurso Upstream para enviar mensagens do cliente ao aplicativo de funções. Já o aplicativo de funções usa a associação de gatilho do Serviço do SignalR para lidar com essas mensagens. A arquitetura geral é exibida abaixo:

Para obter informações sobre a instalação e detalhes de configuração, confira a visão geral.

Exemplo

A função C# pode ser criada por meio de um dos seguintes modos C#:

• Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework.
• Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions.
• Script C#: usado principalmente ao criar funções C# no portal do Azure.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

Modelo de trabalho isolado

O exemplo a seguir mostra uma função C# que recebe um evento de mensagem de clientes e registra o conteúdo da mensagem.

[Function(nameof(OnClientMessage))]
public static void OnClientMessage(
    [SignalRTrigger("Hub", "messages", "sendMessage", "content", ConnectionStringSetting = "SignalRConnection")]
        SignalRInvocationContext invocationContext, string content, FunctionContext functionContext)
{
    var logger = functionContext.GetLogger(nameof(OnClientMessage));
    logger.LogInformation("Connection {connectionId} sent a message. Message content: {content}", invocationContext.ConnectionId, content);
}

Importante

O modelo baseado em classe de ligações do Serviço SignalR no trabalhador isolado em C# não otimiza a forma como você grava gatilhos do SignalR devido à limitação do modelo de trabalho do C#. Para obter mais informações sobre o modelo baseado em classe, consulte Modelo baseado em classe.

Modelo em processo

A vinculação de gatilho do Serviço SignalR para o modelo em processo C# tem dois modelos de programação. modelo com base em classes e modelo tradicional. O modelo baseado em classes proporciona uma experiência consistente de programação no servidor do SignalR. O modelo tradicional oferece mais flexibilidade e é semelhante a outras associações de função.

Com o modelo com base em classes

Confira Modelo com base em classes para obter detalhes.

public class HubName1 : ServerlessHub
{
    [FunctionName("SignalRTest")]
    public Task SendMessage([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
    {
        logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
    }
}

Com um modelo tradicional

O modelo tradicional obedece à convenção do Azure Functions desenvolvida por C#. Se você não estiver familiarizado com ela, poderá aprender com os documentos.

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

Como pode ser difícil de usar ParameterNames no gatilho, o exemplo a seguir mostra como usar o atributo SignalRParameter para definir o atributo message.

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

Atualmente, não há suporte para o gatilho do SignalR para Java.

Aqui estão os dados de associação no arquivo function.json:

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "hubName1",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}

Modelo v4

app.generic("function1",
    {
        trigger: { "type": "signalRTrigger", "name": "invocation", "direction": "in", "hubName": "hubName1", "event": "SendMessage", "category": "messages" },
        handler: (triggerInput, context) => {
            context.log(`Receive ${context.Arguments[0]} from ${triggerInput.ConnectionId}.`)
        }
    })

Modelo v3

Aqui estão os dados de associação no arquivo function.json:

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "hubName1",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}

Aqui está o código JavaScript:

module.exports = function (context, invocation) {
    context.log(`Receive ${context.bindingData.message} from ${invocation.ConnectionId}.`)
};

Exemplos completos do PowerShell estão pendentes.

Aqui está o código Python:

import logging
import json
import azure.functions as func

def main(invocation) -> None:
    invocation_json = json.loads(invocation)
    logging.info("Receive {0} from {1}".format(invocation_json['Arguments'][0], invocation_json['ConnectionId']))

Atributos

As bibliotecas C# em processo e de processo de trabalho isolado usam o atributo SignalRTrigger para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json.

Modelo de trabalho isolado

A tabela a seguir explica as propriedades do atributo SignalRTrigger.

Propriedade de atributo	Descrição
HubName	Esse valor deve ser definido como o nome do hub do SignalR para que a função seja acionada.
Categoria	Esse valor deve ser definido como a categoria de mensagens para que a função seja acionada. A categoria pode ser um dos seguintes valores: connections: que inclui eventos conectados e desconectados messages: que inclui todos os outros eventos, exceto os da categoria connections
Evento	Esse valor deve ser definido como o evento das mensagens para que a função seja acionada. Na categoria messages, o evento é o destino da mensagem de invocação que os clientes enviam. Na categoria connections, somente são usados os valores conectado e desconectado.
ParameterNames	(Opcional) Uma lista de nomes que se associa aos parâmetros.
ConnectionStringSetting	O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço do SignalR (o padrão é AzureSignalRConnectionString).

Modelo em processo

A tabela a seguir explica as propriedades do atributo SignalRTrigger.

Propriedade de atributo	Descrição
HubName	Esse valor deve ser definido como o nome do hub do SignalR para que a função seja acionada.
Categoria	Esse valor deve ser definido como a categoria de mensagens para que a função seja acionada. A categoria pode ser um dos seguintes valores: connections: que inclui eventos conectados e desconectados messages: que inclui todos os outros eventos, exceto os da categoria connections
Evento	Esse valor deve ser definido como o evento das mensagens para que a função seja acionada. Na categoria messages, o evento é o destino da mensagem de invocação que os clientes enviam. Na categoria connections, somente são usados os valores conectado e desconectado.
ParameterNames	(Opcional) Uma lista de nomes que se associa aos parâmetros.
ConnectionStringSetting	O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço do SignalR (o padrão é AzureSignalRConnectionString).

Anotações

Atualmente, não há uma anotação Java compatível com um gatilho SignalR.

Configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json	Descrição
tipo	Deve ser definido como SignalRTrigger.
direction	Deve ser definido como in.
name	Nome da variável usada no código da função para o objeto de contexto da invocação do gatilho.
hubName	Esse valor deve ser definido como o nome do hub do SignalR para que a função seja acionada.
category	Esse valor deve ser definido como a categoria de mensagens para que a função seja acionada. A categoria pode ser um dos seguintes valores: connections: que inclui eventos conectados e desconectados messages: que inclui todos os outros eventos, exceto os da categoria connections
event	Esse valor deve ser definido como o evento das mensagens para que a função seja acionada. Na categoria messages, o evento é o destino da mensagem de invocação que os clientes enviam. Na categoria connections, somente são usados os valores conectado e desconectado.
parameterNames	(Opcional) Uma lista de nomes que se associa aos parâmetros.
connectionStringSetting	O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço do SignalR (o padrão é AzureSignalRConnectionString).

Consulte a Seção de exemplo para obter exemplos completos.

Uso

Payloads

O tipo de entrada do gatilho é declarado como InvocationContext ou um tipo personalizado. Se você escolher InvocationContext, terá acesso total ao conteúdo da solicitação. Para um tipo personalizado, o runtime tenta analisar o corpo da solicitação JSON para definir as propriedades do objeto.

InvocationContext

InvocationContext contém o conteúdo na mensagem enviada de um serviço do SignalR, que inclui as seguintes propriedades:

Propriedade	Descrição
Argumentos	Disponível para a categoria messages. Contém argumentos na mensagem de invocação
Erro	Disponível para o evento desconectado. Poderá ficar vazio se a conexão for fechada sem erros ou contiver as mensagens de erro.
Hub	O nome do hub ao qual a mensagem pertence.
Categoria	A categoria da mensagem.
Evento	O evento da mensagem.
ConnectionId	A ID de conexão do cliente que envia a mensagem.
UserId	Identidade de usuário do cliente que envia a mensagem.
Cabeçalhos	Os cabeçalhos da solicitação.
Consulta	A consulta da solicitação quando os clientes se conectam ao serviço.
Declarações	As declarações do cliente.

Usando ParameterNames

A propriedade ParameterNames em SignalRTrigger permite que você associe argumentos das mensagens de invocação aos parâmetros das funções. É possível usar o nome que você definiu como parte das expressões de associação de outra associação ou como parâmetros no seu código. Isso oferece a você uma forma mais prática de acessar argumentos de InvocationContext.

Digamos que você tenha um cliente SignalR do JavaScript que está tentando invocar o método broadcast no Azure Functions com os dois argumentos message1 e message2.

await connection.invoke("broadcast", message1, message2);

Depois de definir parameterNames, o nome que você definiu corresponderá aos argumentos enviados no lado do cliente.

[SignalRTrigger(parameterNames: new string[] {"arg1, arg2"})]

Em seguida, o arg1 contém o conteúdo de message1, e arg2 contém o conteúdo de message2.

Considerações sobre ParameterNames

Na associação de parâmetros, a ordem é importante. Se você estiver usando ParameterNames, a ordem de ParameterNames corresponde à ordem dos argumentos que você invoca no cliente. Se você estiver usando o atributo [SignalRParameter] de C#, a ordem dos argumentos nos métodos do Azure Functions corresponderá à ordem dos argumentos nos clientes.

ParameterNames e atributo [SignalRParameter]não pode ser usado ao mesmo tempo, ou você terá uma exceção.

Integração ao Serviço do SignalR

O Serviço do SignalR precisa de uma URL para acessar o aplicativo de funções quando você está usando a associação de gatilho do Serviço do SignalR. É necessário configurar a URL em Configurações de upstream no lado do Serviço do SignalR.

Ao usar o gatilho do Serviço SignalR, a URL pode ser simples e formatada da seguinte maneira:

<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>

O Function_App_URL pode ser encontrado na página Visão Geral do Aplicativo de Função e é API_KEY gerado pelo Azure Function. Você pode obter a API_KEY de signalr_extension na folha API_KEY do aplicativo de funções.

Se você quiser usar mais de um aplicativo de funções junto com um Serviço do SignalR, o upstream também poderá dar suporte a regras de roteamento complexas. Encontre mais detalhes em Configurações de upstream.

Exemplo passo a passo

Você pode seguir a amostra do GitHub para implantar uma sala de chat no aplicativo de funções com o recurso de upstream e associação de gatilho do Serviço do SignalR: Amostra de sala de chat bidirecional

Próximas etapas

• Desenvolvimento de funções do Azure e a configuração com o serviço do Azure SignalR
• Amostra de associação de gatilho do Serviço do SignalR
• Exemplo de associação de Gatilho de Serviço do SignalR no processo de trabalho isolado