Usar o Serviço Azure SignalR

Artigo
12/13/2024

Este artigo ensina como usar o SDK no lado do servidor de aplicativos para conectar-se ao Serviço do SignalR quando você estiver usando o SignalR no seu servidor de aplicativos.

Importante

As cadeias de conexão brutas aparecem neste artigo somente para fins de demonstração.

Uma cadeia de conexão inclui as informações de autorização necessárias para que o seu aplicativo acesse o serviço Azure Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha raiz para o serviço. Em ambientes de produção, sempre proteja suas chaves de acesso. Use o Azure Key Vault para gerenciar e rotacionar suas chaves com segurança, proteja sua cadeia de conexão usando o Microsoft Entra ID e autorize o acesso com o Microsoft Entra ID.

Evite distribuir chaves de acesso para outros usuários, fazer hard-coding com elas ou salvá-las em qualquer lugar em texto sem formatação que seja acessível a outras pessoas. Gire suas chaves se você acredita que elas podem ter sido comprometidas.

Criar uma instância do Serviço Azure SignalR

Siga o Guia de início rápido: Use um modelo do ARM para implantar o Azure SignalR para criar uma instância de serviço do SignalR.

Para ASP.NET Core SignalR

Instalar o SDK

Execute o comando para instalar o SDK do Serviço do SignalR em seu projeto ASP.NET Core.

dotnet add package Microsoft.Azure.SignalR

Na sua classe Startup, utilize o SDK do Serviço do SignalR conforme o trecho de código a seguir.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR()
            .AddAzureSignalR();
}

public void Configure(IApplicationBuilder app)
{
    app.UseEndpoints(routes =>
    {
        routes.MapHub<YourHubClass>("/path_for_your_hub");
    });
}

Configurar a cadeia de conexão

Cadeias de conexão brutas aparecem neste artigo somente para fins de demonstração. Em ambientes de produção, sempre proteja suas chaves de acesso. Use o Azure Key Vault para gerenciar e rotacionar suas chaves com segurança, proteja sua cadeia de conexão usando o Microsoft Entra ID e autorize o acesso com o Microsoft Entra ID.

Há duas maneiras de configurar a cadeia de conexão do Serviço do SignalR no seu aplicativo.

Defina uma variável de ambiente com nome Azure:SignalR:ConnectionString ou Azure__SignalR__ConnectionString.
- No Serviço de Aplicativo do Azure, coloque-a nas configurações de aplicativo.

Passe a cadeia de conexão como um parâmetro de AddAzureSignalR().

services.AddSignalR()
        .AddAzureSignalR("<replace with your connection string>");

services.AddSignalR()
        .AddAzureSignalR(options => options.ConnectionString = "<replace with your connection string>");

Configurar opções

Existem algumas opções que você pode personalizar ao usar o SDK do Serviço do Azure SignalR.

`ConnectionString`

O valor padrão é Azure:SignalR:ConnectionString connectionString ou appSetting no arquivo web.config.
Pode ser reconfigurado, mas verifique se o valor NÃO está codificado diretamente no código.

`InitialHubServerConnectionCount`

O valor padrão é 5.
Essa opção controla o número inicial de conexões por hub entre o servidor de aplicativos e o Serviço do Azure SignalR. Normalmente, manter o valor padrão é suficiente. Durante o runtime, o SDK pode iniciar novas conexões de servidor para ajuste de desempenho ou balanceamento de carga. Quando você possui um grande número de clientes, pode atribuir um número maior para garantir uma melhor taxa de transferência. Por exemplo, se você tem 100.000 clientes no total, o número de conexões pode ser aumentado para 10 ou 15.

`MaxHubServerConnectionCount`

O valor padrão é null.
Esta opção controla o número máximo de conexões permitidas por hub entre o servidor de aplicativos e o Serviço do Azure SignalR. Durante o runtime, o SDK pode iniciar novas conexões de servidor para ajuste de desempenho ou balanceamento de carga. Por padrão, uma nova conexão de servidor é estabelecida sempre que necessário. Quando o limite máximo de conexões de servidor permitidas é configurado, o SDK não inicia novas conexões ao atingir esse limite.

`ApplicationName`

O valor padrão é null.
Essa opção pode ser útil quando você quer compartilhar a mesma instância do Azure SignalR para diferentes servidores de aplicativos que contêm os mesmos nomes de hub. Se não estiver configurado, todos os servidores de aplicativos conectados serão considerados instâncias do mesmo aplicativo.

`ClaimsProvider`

O valor padrão é null.
Essa opção controla quais declarações você deseja associar à conexão do cliente. Ela é usada quando o SDK de Serviço gera o token de acesso para o cliente na solicitação de negociação do cliente. Por padrão, todas as declarações do HttpContext.User da solicitação negociada são reservadas. Elas podem ser acessados em Hub.Context.User.
Normalmente, você deve manter essa opção como está. Antes de personalizá-la, procure entender o que acontece.

`AccessTokenLifetime`

O valor padrão é 1 hour.
Essa opção controla a validade do tempo de vida do token de acesso gerado pelo SDK de Serviço para cada cliente. O token de acesso é retornado na resposta à solicitação de negociação do cliente.
Quando ServerSentEvent ou LongPolling são usados como transporte, a conexão do cliente será encerrada devido por falha de autenticação após o tempo de expiração. Você pode aumentar este valor para evitar desconexões do cliente.

`AccessTokenAlgorithm`

O valor padrão é HS256
Esta opção oferece a escolha de SecurityAlgorithms ao gerar o token de acesso. No momento, os valores opcionais com suporte são HS256 e HS512. Observe que HS512 é mais seguro, mas o token gerado é relativamente mais longo do que isso usando HS256.

`ServerStickyMode`

O valor padrão é Disabled.
Essa opção especifica o modo de aderência ao servidor. Quando o cliente é roteado para o servidor com o qual ele negociou pela primeira vez, chamamos de aderência ao servidor ("server sticky", em inglês).
Em cenários distribuídos, podem existir vários servidores de aplicativos conectados a uma instância do Azure SignalR. Como explica a seção internos das conexões de cliente, o cliente primeiro negocia com o servidor de aplicativos e, em seguida, é redirecionado para o Azure SignalR para estabelecer a conexão persistente. O Azure SignalR então localiza um servidor de aplicativos para atender ao cliente, conforme explicado na seção Dados de transporte entre o cliente e o servidor.
- Quando Disabled, o cliente é roteado para um servidor de aplicativos aleatório. Geralmente, os servidores de aplicativos têm conexões de cliente equilibradas com esse modo. Se seus cenários são de transmissão ou envio em grupo, usar esta opção padrão é suficiente.
- Quando Preferred, o Azure SignalR tenta encontrar o servidor de aplicativos com o qual o cliente negociou inicialmente de forma que nenhum outro custo ou roteamento global seja necessário. Isso pode ser útil quando seu cenário é de envio para conexão*. Enviar para a conexão pode ter um melhor desempenho e menor latência quando o remetente e o destinatário são roteados para o mesmo servidor de aplicativos.
- Quando Required, o Azure SignalR sempre tenta encontrar o servidor de aplicativos com o qual o cliente negociou pela primeira vez. Essa opção pode ser útil quando algum contexto do cliente é obtido da etapa de negotiate e armazenado na memória, para então ser utilizado dentro de Hubs. Entretanto, essa opção pode ter impactos negativos no desempenho, pois exige que o Azure SignalR faça esforços adicionais para localizar esse servidor de aplicativos específico globalmente e manter o tráfego de roteamento global entre cliente e servidor.

`GracefulShutdown`

`GracefulShutdown.Mode`

O valor padrão é Off
Essa opção especifica o comportamento após o servidor de aplicativos receber um SIGINT (CTRL + C).
Quando definido como WaitForClientsClose, em vez de parar o servidor imediatamente, nós o removemos do Serviço do Azure SignalR para impedir que novas conexões de cliente sejam atribuídas a esse servidor.
Quando definido como MigrateClients, além disso, tentamos migrar conexões de clientes para outro servidor válido. A migração só será disparada após a entrega de uma mensagem.
- OnConnected e OnDisconnected são disparados quando as conexões são migradas para dentro ou para fora.
- IConnectionMigrationFeature pode ajudar a identificar se a conexão é migrada para dentro ou para fora.
- Confira nossos códigos de exemplo para entender o uso detalhadamente.

`GracefulShutdown.Timeout`

O valor padrão é 30 seconds
Essa opção especifica o tempo máximo de espera para que os clientes sejam encerrados/migrados.

`ServiceScaleTimeout`

O valor padrão é 5 minutes
Essa opção especifica o tempo mais longo de espera para a escala dinâmica dos pontos de extremidade de serviço, minimizando o impacto nos clientes online. Normalmente, a escala dinâmica entre o servidor de aplicativo único e um ponto de extremidade de serviço pode ser concluída em segundos.No entanto, se você tiver vários servidores de aplicativos e vários pontos de extremidade de serviço com variação de rede e quiser garantir a estabilidade do cliente, você poderá configurar esse valor da forma mais adequada.

`MaxPollIntervalInSeconds`

O valor padrão é 5
Essa opção define o intervalo máximo de sondagem permitido para conexões LongPolling no Serviço do Azure SignalR. Se a próxima solicitação de sondagem não chegar dentro de MaxPollIntervalInSeconds, o Serviço do Azure SignalR encerra a conexão do cliente.
O valor é limitado a [1, 300].

`TransportTypeDetector`

Valor padrão: todos os transportes estão habilitados.
Essa opção define uma função para personalizar os transportes que os clientes podem usar para enviar solicitações HTTP.
Use essas opções em vez de HttpConnectionDispatcherOptions.Transports para configurar os transportes.

`AllowStatefulReconnects`

O valor padrão é null
Essa opção habilita ou desabilita reconexões com estado para todos os hubs.
Se null, o SDK lerá as configurações do hub.
Se true, o Serviço do Azure SignalR habilitará reconexões com estado em todos os hubs declarados. E os clientes precisam habilitar reconexões com estado no lado do cliente.
Se false, o Serviço do Azure SignalR desabilitará reconexões com estado em todos os hubs declarados.

Amostra

Você pode configurar as opções acima como no exemplo de código a seguir.

services.AddSignalR()
        .AddAzureSignalR(options =>
            {
                options.InitialHubServerConnectionCount = 10;
                options.AccessTokenLifetime = TimeSpan.FromDays(1);
                options.ClaimsProvider = context => context.User.Claims;

                options.GracefulShutdown.Mode = GracefulShutdownMode.WaitForClientsClose;
                options.GracefulShutdown.Timeout = TimeSpan.FromSeconds(10);
                options.TransportTypeDetector = httpContext => AspNetCore.Http.Connections.HttpTransportType.WebSockets | AspNetCore.Http.Connections.HttpTransportType.LongPolling;
            });

Para o ASP.NET SignalR herdado

Observação

Se esta é a sua primeira experiência com o SignalR, recomendamos que você use o ASP.NET Core SignalR, pois é mais simples, mais confiável e mais fácil de usar.

Instalar o SDK

Instale o SDK do Serviço do SignalR no seu projeto ASP.NET usando o Console do Gerenciador de Pacotes:

Install-Package Microsoft.Azure.SignalR.AspNet

Na sua classe Startup, utilize o SDK do Serviço do SignalR conforme o trecho de código a seguir, substituindo MapSignalR() por MapAzureSignalR({your_applicationName}). Substitua {YourApplicationName} pelo nome do seu aplicativo, este é o nome exclusivo para diferenciar este aplicativo dos seus outros aplicativos. Você pode usar this.GetType().FullName como o valor.

public void Configuration(IAppBuilder app)
{
    app.MapAzureSignalR(this.GetType().FullName);
}

Configurar a cadeia de conexão

Configure a cadeia de conexão no arquivo web.config, na seção connectionStrings:

<configuration>
    <connectionStrings>
        <add name="Azure:SignalR:ConnectionString" connectionString="Endpoint=...;AccessKey=..."/>
    </connectionStrings>
    ...
</configuration>

Configurar opções

Existem algumas opções que você pode personalizar ao usar o SDK do Serviço do Azure SignalR.

`ConnectionString`

O valor padrão é Azure:SignalR:ConnectionString connectionString ou appSetting no arquivo web.config.
Pode ser reconfigurado, mas verifique se o valor NÃO está codificado diretamente no código.

`InitialHubServerConnectionCount`

O valor padrão é 5.
Essa opção controla o número inicial de conexões por hub entre o servidor de aplicativos e o Serviço do Azure SignalR. Normalmente, manter o valor padrão é suficiente. Durante o runtime, o SDK pode iniciar novas conexões de servidor para ajuste de desempenho ou balanceamento de carga. Quando você possui um grande número de clientes, pode atribuir um número maior para garantir uma melhor taxa de transferência. Por exemplo, se você tem 100.000 clientes no total, o número de conexões pode ser aumentado para 10 ou 15.

`MaxHubServerConnectionCount`

O valor padrão é null.
Esta opção controla o número máximo de conexões permitidas por hub entre o servidor de aplicativos e o Serviço do Azure SignalR. Durante o runtime, o SDK pode iniciar novas conexões de servidor para ajuste de desempenho ou balanceamento de carga. Por padrão, uma nova conexão de servidor é estabelecida sempre que necessário. Quando o limite máximo de conexões de servidor permitidas é configurado, o SDK não inicia novas conexões ao atingir esse limite.

`ApplicationName`

O valor padrão é null.
Essa opção pode ser útil quando você quer compartilhar a mesma instância do Azure SignalR para diferentes servidores de aplicativos que contêm os mesmos nomes de hub. Se não estiver configurado, todos os servidores de aplicativos conectados serão considerados instâncias do mesmo aplicativo.

`ClaimProvider`

O valor padrão é null.
Essa opção controla quais declarações você deseja associar à conexão do cliente. Ela é usada quando o SDK de Serviço gera o token de acesso para o cliente na solicitação de negociação do cliente. Por padrão, todas as declarações de IOwinContext.Authentication.User da solicitação negociada são reservadas.
Normalmente, você deve manter essa opção como está. Antes de personalizá-la, procure entender o que acontece.

`AccessTokenLifetime`

O valor padrão é 1 hour.
Essa opção controla a validade do tempo de vida do token de acesso gerado pelo SDK de Serviço para cada cliente. O token de acesso é retornado na resposta à solicitação de negociação do cliente.
Quando ServerSentEvent ou LongPolling são usados como transporte, a conexão do cliente será encerrada devido por falha de autenticação após o tempo de expiração. Você pode aumentar este valor para evitar desconexões do cliente.

`AccessTokenAlgorithm`

O valor padrão é HS256
Esta opção oferece a escolha de SecurityAlgorithms ao gerar o token de acesso. No momento, os valores opcionais com suporte são HS256 e HS512. Observe que HS512 é mais seguro, mas o token gerado é relativamente mais longo do que isso usando HS256.

`ServerStickyMode`

O valor padrão é Disabled.
Essa opção especifica o modo de aderência ao servidor. Quando o cliente é roteado para o servidor com o qual ele negociou pela primeira vez, chamamos de aderência ao servidor ("server sticky", em inglês).
Em cenários distribuídos, podem existir vários servidores de aplicativos conectados a uma instância do Azure SignalR. Como explica a seção internos das conexões de cliente, o cliente primeiro negocia com o servidor de aplicativos e, em seguida, é redirecionado para o Azure SignalR para estabelecer a conexão persistente. O Azure SignalR então localiza um servidor de aplicativos para atender ao cliente, conforme explicado na seção Dados de transporte entre o cliente e o servidor.
- Quando Disabled, o cliente é roteado para um servidor de aplicativos aleatório. Geralmente, os servidores de aplicativos têm conexões de cliente equilibradas com esse modo. Se seus cenários são de transmissão ou envio em grupo, usar esta opção padrão é suficiente.
- Quando Preferred, o Azure SignalR tenta encontrar o servidor de aplicativos com o qual o cliente negociou inicialmente de forma que nenhum outro custo ou roteamento global seja necessário. Isso pode ser útil quando seu cenário é de envio para conexão*. Enviar para a conexão pode ter um melhor desempenho e menor latência quando o remetente e o destinatário são roteados para o mesmo servidor de aplicativos.
- Quando Required, o Azure SignalR sempre tenta encontrar o servidor de aplicativos com o qual o cliente negociou pela primeira vez. Essa opção pode ser útil quando algum contexto do cliente é obtido da etapa de negotiate e armazenado na memória, para então ser utilizado dentro de Hubs. Entretanto, essa opção pode ter impactos negativos no desempenho, pois exige que o Azure SignalR faça esforços adicionais para localizar esse servidor de aplicativos específico globalmente e manter o tráfego de roteamento global entre cliente e servidor.

`MaxPollIntervalInSeconds`

O valor padrão é 5
Esta opção define o tempo máximo de inatividade permitido para conexões inativas no Serviço do Azure SignalR. No ASP.NET SignalR, isso se aplica ao tipo de transporte de sondagem longa ou à reconexão. Se a próxima solicitação /reconnect ou /poll não for recebida dentro de MaxPollIntervalInSeconds, o Serviço do Azure SignalR encerra a conexão do cliente.
O valor é limitado a [1, 300].

Amostra

Você pode configurar as opções acima como no exemplo de código a seguir.

app.Map("/signalr",subApp => subApp.RunAzureSignalR(this.GetType().FullName, new HubConfiguration(), options =>
{
    options.InitialHubServerConnectionCount = 1;
    options.AccessTokenLifetime = TimeSpan.FromDays(1);
    options.ClaimProvider = context => context.Authentication?.User.Claims;
}));

Escalar horizontalmente o servidor de aplicativos

Com o Serviço do Azure SignalR, as conexões persistentes são transferidas do servidor de aplicativos, para que você possa se concentrar em implementar sua lógica de negócios nas classes de hub. No entanto, ainda é necessário escalar horizontalmente os servidores de aplicativos para melhorar o desempenho ao gerenciar um grande número de conexões de clientes. Abaixo estão algumas dicas para escalar horizontalmente os servidores de aplicativos.

Vários servidores de aplicativos podem se conectar à mesma instância do Serviço do Azure SignalR.
Se você quiser compartilhar a mesma instância do Azure SignalR para diferentes aplicativos diferentes com os mesmos nomes de hub, configure-os com diferentes opções de ApplicationName. Se não estiver configurado, todos os servidores de aplicativos conectados serão considerados instâncias do mesmo aplicativo.
Desde que a opção ApplicationName e o nome da classe de hub sejam iguais, as conexões de diferentes servidores de aplicativos são agrupadas no mesmo hub.
Cada conexão de cliente só é criada em um dos servidores de aplicativos, e as mensagens desse cliente são enviadas somente para esse mesmo servidor de aplicativos. Se você deseja acessar informações dos clientes de forma global (a partir de todos os servidores de aplicativos), é necessário usar algum armazenamento centralizado para guardar as informações dos clientes de todos os servidores de aplicativos.

Próximas etapas

Neste artigo, você aprendeu como usar o Serviço do SignalR em seus aplicativos. Consulte os seguintes artigos para saber mais sobre o Serviço do SignalR.

Componentes internos do Serviço do Azure SignalR

Início Rápido: Criar uma sala de chat usando o Serviço do SignalR

Compartilhar via

Usar o Serviço Azure SignalR

Criar uma instância do Serviço Azure SignalR

Para ASP.NET Core SignalR

Instalar o SDK

Configurar a cadeia de conexão

Configurar opções

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimsProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

GracefulShutdown

GracefulShutdown.Mode

GracefulShutdown.Timeout

ServiceScaleTimeout

MaxPollIntervalInSeconds

TransportTypeDetector

AllowStatefulReconnects

Amostra

Para o ASP.NET SignalR herdado

Instalar o SDK

Configurar a cadeia de conexão

Configurar opções

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

MaxPollIntervalInSeconds

Amostra

Escalar horizontalmente o servidor de aplicativos

Próximas etapas

Comentários

Recursos adicionais

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimsProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`GracefulShutdown`

`GracefulShutdown.Mode`

`GracefulShutdown.Timeout`

`ServiceScaleTimeout`

`MaxPollIntervalInSeconds`

`TransportTypeDetector`

`AllowStatefulReconnects`

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`MaxPollIntervalInSeconds`