ASP.NET Minimal SignalR

Transportes suportados

O SignalR suporta três transportes, nesta ordem de fallback: WebSockets, Server-Sent Events e Long Polling. Assim, a biblioteca escolhe automaticamente o melhor método disponível entre servidor e client.

O WebSockets é o transporte preferido, porque geralmente entrega a melhor performance. Isso vale tanto para o modelo antigo quanto para o SignalR com minimal APIs, já que o transporte não depende da forma de hospedagem.

Ainda sobre esse ponto, a conexão sempre começa com uma requisição HTTP de negociação. No entanto, se algum proxy ou navegador não suportar WebSockets, a conexão continua funcionando com as outras opções.

Hubs e protocolos

A comunicação acontece por meio de Hubs, que funcionam como um pipeline de alto nível. Com isso, o client chama métodos no servidor e o servidor chama métodos no client.

O SignalR traz dois protocolos nativos: um baseado em JSON, que é o padrão, e outro binário baseado em MessagePack. Em geral, o MessagePack gera mensagens menores que o JSON.

Iniciando o projeto

Vamos começar criando nosso servidor com o template web, que é o template vazio das Minimal APIs.

dotnet new web -o SignalServer
cd SignalServer
dotnet add package Microsoft.AspNetCore.SignalR

O comando dotnet new web gera um Program.cs mínimo, com apenas um endpoint de exemplo. Em seguida, entramos na pasta e adicionamos o pacote do SignalR.

O pacote do SignalR no servidor

O pacote Microsoft.AspNetCore.SignalR é tudo que precisamos para trabalhar com SignalR no servidor. Na prática, porém, desde o ASP.NET Core 3.0 as bibliotecas do servidor fazem parte do shared framework Microsoft.AspNetCore.App.

Em outras palavras, um projeto web do .NET 6 já enxerga as classes do SignalR mesmo sem esse comando. Portanto, a referência explícita ao pacote é opcional no servidor.

O ciclo de vida do Hub

Um detalhe importante: cada chamada de método roda em uma nova instância do Hub. Por isso, a documentação recomenda não guardar estado em propriedades da classe.

Essa regra continua igual no SignalR com minimal APIs, porque o modelo de hospedagem não altera o ciclo de vida do Hub.

Se você precisar enviar mensagens de fora do Hub, use o IHubContext. Da mesma forma, nunca instancie o Hub manualmente pela injeção de dependência.

O papel do CancellationToken

É importante notar o uso do CancellationToken, que permite cancelar a ação a qualquer momento. Na prática, o SignalR dispara esse token quando o client cancela a inscrição no stream.

Com isso, o servidor para o loop e libera recursos assim que o client se desconecta. Sem o token, o while (true) continuaria rodando à toa.

O que o yield faz

Em adicional, usamos o yield (produtor) para definir que o retorno é um iterador. Desse modo, o client consome nosso conteúdo direto, sem precisar de uma classe para armazenar o estado.

Além disso, os métodos iteradores assíncronos evitam problemas comuns dos Channels. Por exemplo, devolver o ChannelReader tarde demais ou sair do método sem completar o ChannelWriter.

Código final do SignalR com minimal APIs

O código final completo do nosso servidor com SignalR fica assim.

using Microsoft.AspNetCore.SignalR;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSignalR();

var app = builder.Build();
app.MapHub<MyHub>("/chat");
app.Run();

class MyHub : Hub
{
    public async IAsyncEnumerable<DateTime> Streaming(CancellationToken cancellationToken)
    {
        while (true)
        {
            yield return DateTime.UtcNow;
            await Task.Delay(1000, cancellationToken);
        }
    }
}

Repare que o arquivo inteiro tem pouco mais de vinte linhas. Esse é justamente o ganho do SignalR com minimal APIs: a infraestrutura some e sobra apenas o que importa.

Note também que a classe MyHub fica no mesmo arquivo, logo depois das top level statements. Em um projeto real, porém, o ideal é mover o Hub para um arquivo próprio.

Executando o servidor

Agora basta executar o programa usando o comando abaixo.

dotnet watch run

O dotnet watch reinicia ou recarrega a aplicação sempre que você salva um arquivo. Assim, você testa as mudanças no Hub sem parar o servidor manualmente.

Não esqueça de anotar a URL na qual seu servidor está rodando. Vamos precisar dela para nos conectar no client a seguir.

Conectando ao servidor

Para se conectar ao servidor, precisamos apenas do HubConnectionBuilder.

using Microsoft.AspNetCore.SignalR.Client;

// troque pela URL anotada ao executar o servidor
var uri = "https://localhost:7182/chat";

await using var connection = new HubConnectionBuilder().WithUrl(uri).Build();

O await using garante o descarte da conexão quando o programa termina. Em seguida, podemos iniciar a conexão.

await connection.StartAsync();

Nesse momento, o client negocia com o servidor qual transporte usar. Na maioria dos ambientes locais, o resultado é uma conexão WebSocket.

Recebendo dados em streaming

Como utilizamos o IAsyncEnumerable no servidor, podemos chamar a função StreamAsync<TYPE>("STREAM") para receber os dados.

await foreach (var date in connection.StreamAsync<DateTime>("Streaming"))
{
    Console.WriteLine(date);
}

O parâmetro genérico de StreamAsync<T> define o tipo dos objetos que o método do Hub devolve. Já o texto "Streaming" precisa bater com o nome do método no Hub.

Como resultado final, temos o seguinte código no client.

using Microsoft.AspNetCore.SignalR.Client;

var uri = "https://localhost:7182/chat";

await using var connection = new HubConnectionBuilder().WithUrl(uri).Build();

await connection.StartAsync();

await foreach (var date in connection.StreamAsync<DateTime>("Streaming"))
{
    Console.WriteLine(date);
}

Ao executar o client, uma nova data aparece no terminal a cada segundo. Então, você tem a prova de que o SignalR com minimal APIs está entregando o stream em tempo real.

Outros clients do SignalR

O Console Application é apenas um dos clients possíveis. O SignalR também oferece client JavaScript, distribuído pelo pacote npm @microsoft/signalr, além de clients para Java e outras plataformas.

Dessa maneira, o mesmo servidor de SignalR com minimal APIs atende uma página web, um app mobile e um serviço em background ao mesmo tempo. O contrato continua sendo o nome do método e o tipo dos dados.

No navegador, por exemplo, o client JavaScript também conhece o conceito de stream. Então, a página consegue assinar o método Streaming e atualizar a tela a cada nova data recebida.

Cancelando o stream pelo client

O StreamAsync também aceita um CancellationToken. Quando você chama Cancel no CancellationTokenSource, o client envia uma mensagem de cancelamento ao servidor.

// cancela o stream automaticamente após 10 segundos
using var cancellationTokenSource = new CancellationTokenSource(TimeSpan.FromSeconds(10));

var stream = connection.StreamAsync<DateTime>("Streaming", cancellationTokenSource.Token);

await foreach (var date in stream)
{
    Console.WriteLine(date);
}

Com isso, o token do método Streaming no Hub dispara e o loop do servidor termina. Esse é exatamente o comportamento que preparamos lá atrás com o CancellationToken.

Habilitando logs detalhados

Quando algo não funciona, os logs ajudam muito. O SignalR usa duas categorias de log: Microsoft.AspNetCore.SignalR e Microsoft.AspNetCore.Http.Connections.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore.SignalR": "Debug",
      "Microsoft.AspNetCore.Http.Connections": "Debug"
    }
  }
}

A primeira categoria registra a ativação dos Hubs e a invocação dos métodos. Já a segunda mostra detalhes dos transportes, como WebSockets e Long Polling.

Contudo, evite publicar logs de produção em fóruns públicos, porque eles podem conter informações sensíveis. Use o nível Debug apenas durante o diagnóstico.