Diretrizes do ASP.NET Core BlazorSignalR

Este artigo explica como configurar e gerenciar conexões SignalR em aplicativos Blazor.

Para obter diretrizes gerais sobre a configuração do ASP.NET Core SignalR, consulte os tópicos na Visão Geral do ASP.NET Core SignalR na área de documentação, especialmente configuração do ASP.NET Core SignalR.

Os aplicativos do lado do servidor usam o ASP.NET Core SignalR para se comunicar com o navegador. As condições de hospedagem e dimensionamento do SignalR se aplicam a aplicativos do lado do servidor.

Blazor funciona melhor ao usar WebSockets como transporte de SignalR devido à menor latência, confiabilidade e segurança. A Sondagem Longa é usada por SignalR quando WebSockets não está disponível ou quando o aplicativo é configurado explicitamente para usar a Sondagem Longa.

Desabilitar a compactação de resposta para Recarga Dinâmica

Desabilite o Middleware de Compactação de Resposta no ambiente ao usar a Recarga DinâmicaDevelopment. Se o código padrão de um modelo de projeto for usado ou não, sempre chame UseResponseCompression primeiro no pipeline de processamento de solicitação.

No arquivo Program:

if (!app.Environment.IsDevelopment())
{
    app.UseResponseCompression();
}

Negociação entre origens do SignalR para autenticação do lado do cliente

Para configurar o cliente subjacente do SignalR para enviar credenciais, como cookies ou cabeçalhos de autenticação ou HTTP.

Use SetBrowserRequestCredentials para definir Include em solicitações fetch entre origens.

IncludeRequestCredentialsMessageHandler.cs:

using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Components.WebAssembly.Http;

public class IncludeRequestCredentialsMessageHandler : DelegatingHandler
{
    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);
        return base.SendAsync(request, cancellationToken);
    }
}

Quando uma conexão de hub for criada, atribua a HttpMessageHandler à opção HttpMessageHandlerFactory:

private HubConnectionBuilder? hubConnection;

...

hubConnection = new HubConnectionBuilder()
    .WithUrl(new Uri(Navigation.ToAbsoluteUri("/chathub")), options =>
    {
        options.HttpMessageHandlerFactory = innerHandler => 
            new IncludeRequestCredentialsMessageHandler { InnerHandler = innerHandler };
    }).Build();

O exemplo anterior configura a URL de conexão do hub para o endereço URI absoluto em /chathub. O URI também pode ser definido por meio de uma cadeia de caracteres, por exemplo https://signalr.example.com, ou por meio de configuração. Navigation é um injetado NavigationManager.

Para obter mais informações, consulte Configuração no ASP.NET Core SignalR.

Renderização do lado do cliente

Se a pré-renderização estiver configurada, ela ocorrerá antes que a conexão do cliente com o servidor seja estabelecida. Para mais informações, confira Pré-renderizar componentes Razor do ASP.NET Core.

Tamanho do estado pré-renderizado e SignalR limite da mensagem

Um estado pré-renderizado grande pode exceder o limite de tamanho da SignalR mensagem do circuito, o que resulta no seguinte:

• O circuito SignalR falha ao inicializar com um erro no cliente: Circuit host not initialized.
• A caixa de diálogo de reconexão no cliente é exibida quando o circuito falha. Não foi possível recuperar.

Para resolver o problema, use ou uma das seguintes abordagens:

• Reduza a quantidade de dados que você está colocando no estado pré-renderizado.
• Aumente o limite daSignalR mensagem. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos adicionais do lado do cliente

• Proteger um hub doSignalR
• Visão geral do ASP.NET CoreSignalR
• Configuração do ASP.NET Core SignalR
• Repositório GitHub de amostras do Blazor (dotnet/blazor-samples) (como baixar)

Usar sessões autoadesivas para hospedagem de webfarm do lado do servidor

Um aplicativo Blazor é pré-remetido em resposta à primeira solicitação do cliente, que cria o estado da interface do usuário no servidor. Quando o cliente tenta criar uma SignalR conexão, o cliente deve se reconectar ao mesmo servidor. Quando mais de um servidor de back-end está em uso, o aplicativo deve implementar sessões autoadesivas para conexões do SignalR.

Observação

O seguinte erro é gerado por um aplicativo que não habilitou sessões autoadesivas em um webfarm:

blazor.server.js:1 Erro não capturado (em promessa): invocação cancelada devido ao fechamento da conexão subjacente.

Serviço do Azure SignalR do lado do servidor

É recomendável usar o Serviço do Azure SignalR para desenvolvimento do lado do servidor hospedado no Microsoft Azure. O serviço funciona em conjunto com o Hub Blazor do aplicativo para escalar verticalmente até um aplicativo do lado do servidor para um grande número de conexões SignalR simultâneas. Além disso, o alcance global do Serviço SignalR e os data centers de alto desempenho ajudam significativamente a reduzir a latência devido à geografia.

As sessões autoadesivas são habilitadas para o Serviço SignalR do Azure definindo a opção ServerStickyMode do serviço ou o valor de configuração como Required. Para obter mais informações, consulte Hospedar e implantar aplicativos do ASP.NET Core no lado do servidorBlazor.

Opções de manipulador de circuito do lado do servidor

Configure o circuito com CircuitOptions. Exibir valores padrão na fonte de referência.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Leia ou defina as opções no arquivo Program com um delegado de opções para AddInteractiveServerComponents. O espaço reservado {OPTION} representa a opção, e o espaço reservado {VALUE} é o valor.

No arquivo Program:

builder.Services.AddRazorComponents().AddInteractiveServerComponents(options =>
{
    options.{OPTION} = {VALUE};
});

Para configurar o HubConnectionContext, use HubConnectionContextOptions com AddHubOptions. Exiba os padrões para as opções de contexto de conexão do hub na fonte de referência. Para obter descrições de opção na documentação SignalR, confira Configuração do ASP.NET Core SignalR. O espaço reservado {OPTION} representa a opção, e o espaço reservado {VALUE} é o valor.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

No arquivo Program:

builder.Services.AddRazorComponents().AddInteractiveServerComponents().AddHubOptions(options =>
{
    options.{OPTION} = {VALUE};
});

Aviso

O valor padrão de MaximumReceiveMessageSize é 32. O aumento do valor pode aumentar o risco de ataques de negação de serviço.

Para obter informações sobre o gerenciamento de memória, consulte Hospedar e implantar Blazoraplicativos do ASP.NET Core no lado do servidor.

Blazor opções de hub

Configure as opções MapBlazorHub para controlar o HttpConnectionDispatcherOptions do hub Blazor. Exiba os padrões para as opções do dispatcher de conexão do hub na fonte de referência. O espaço reservado {OPTION} representa a opção, e o espaço reservado {VALUE} é o valor.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Faça a chamada para depois da chamada para app.MapBlazorHubapp.MapRazorComponents no arquivo do Program aplicativo:

app.MapBlazorHub(options =>
{
    options.{OPTION} = {VALUE};
});

Tamanho máximo da mensagem de recebimento

Esta seção só se aplica a projetos que implementam o SignalR.

O tamanho máximo da mensagem de entrada do SignalR permitida para métodos de hub é limitado pelo HubOptions.MaximumReceiveMessageSize (padrão: 32 KB). As mensagens do SignalR maiores que MaximumReceiveMessageSize geram um erro. A estrutura não impõe um limite no tamanho de uma mensagem SignalR do hub para um cliente.

Quando o log SignalR não está definido como Depuração ou Rastreamento, um erro de tamanho de mensagem é exibido apenas no console de ferramentas para desenvolvedores do navegador:

Erro: conexão perdida com 'Erro: o servidor retornou um erro ao fechar: conexão fechada com um erro.'.

Quando log do lado do servidor SignalR é definido como Depuração ou Rastreamento, o log do lado do servidor exibe um InvalidDataException para um erro de tamanho de mensagem.

appsettings.Development.json:

{
  "DetailedErrors": true,
  "Logging": {
    "LogLevel": {
      ...
      "Microsoft.AspNetCore.SignalR": "Debug"
    }
  }
}

Erro:

System.IO.InvalidDataException: o tamanho máximo da mensagem de 32768B foi excedido. O tamanho da mensagem pode ser configurado em AddHubOptions.

Uma abordagem envolve aumentar o limite definindo MaximumReceiveMessageSize no arquivo Program. O exemplo a seguir define o tamanho máximo da mensagem recebida como 64 KB:

builder.Services.AddRazorComponents().AddInteractiveServerComponents()
    .AddHubOptions(options => options.MaximumReceiveMessageSize = 64 * 1024);

O aumento do limite de tamanho da mensagem de entrada do SignalR significa sacrificar mais recursos do servidor e eleva o risco de ataques de negação de serviço. Além disso, ler um conteúdo maior na memória como cadeias de caracteres ou matrizes de bytes também pode resultar em alocações que funcionam incorretamente com o coletor de lixo, resultando em penalidades de desempenho adicionais.

Uma boa opção para ler grandes conteúdos é enviar o conteúdo em partes menores e processá-lo como um Stream. Isso pode ser usado ao ler grandes conteúdos JSON de interoperabilidade javaScript ( JS) ou se os dados de interoperabilidade JS estiverem disponíveis como bytes brutos. Para obter um exemplo que demonstra o envio de cargas binárias grandes em aplicativos do lado do servidor que usa técnicas semelhantes ao componente InputFile, confira o aplicativo de exemplo Envio Binário e o BlazorInputLargeTextAreaExemplo de Componente.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Formulários que processam grande conteúdo acima de SignalR também podem usar a interoperabilidade JS de streaming diretamente. Para obter mais informações, consulte Chamar métodos do .NET das funções JavaScript no ASP.NET Core Blazor. Para obter um exemplo de formulários que transmitem dados <textarea> para o servidor, confira Solucionar problemas de formulários do ASP.NET Core Blazor.

Considere as diretrizes a seguir ao desenvolver um código que transfere um grande volume de dados:

• Aproveite o suporte à interoperabilidade JS de streaming nativo para transferir dados maiores que o limite de tamanho da mensagem de entrada do SignalR:
  • Chamar funções JavaScript de métodos .NET no ASP.NET Core Blazor
  • Chamar métodos .NET de funções JavaScript no ASP.NET Core Blazor
  • Exemplo de conteúdo de formulário: Solucionar problemas de formulários do ASP.NET Core Blazor
• Dicas gerais:
  • Não aloque objetos grandes no JS e no código C#.
  • Memória consumida liberada quando o processo é concluído ou cancelado.
  • Imponha os seguintes requisitos adicionais para fins de segurança:
    • Declare o tamanho máximo de arquivos ou dados que podem ser passados.
    • Declare a taxa mínima de upload do cliente para o servidor.
  • Depois que os dados são recebidos pelo servidor, os dados podem ser:
    • Armazenados temporariamente em um buffer de memória até que todos os segmentos sejam coletados.
    • Consumidos imediatamente. Por exemplo, os dados podem ser armazenados imediatamente em um banco de dados ou gravados em disco, à medida que cada segmento é recebido.

Configuração de rota do ponto de extremidade do Hub do lado do servidor do Blazor

No arquivo Program, chame MapBlazorHub para mapear o BlazorHub para o caminho padrão do aplicativo. O script Blazor (blazor.*.js) aponta automaticamente para o ponto de extremidade criado por MapBlazorHub.

Refletir o estado da conexão do lado do servidor na interface do usuário

Quando o cliente detecta que a conexão foi perdida, uma interface do usuário padrão é exibida para o usuário enquanto o cliente tenta se reconectar. Se a reconexão falhar, o usuário receberá a opção de tentar novamente.

Para personalizar a interface do usuário, defina um único elemento com um id de components-reconnect-modal. O exemplo a seguir coloca o elemento no componente App.

App.razor:

<div id="components-reconnect-modal">
    There was a problem with the connection!
</div>

Observação

Se mais de um elemento com um id do components-reconnect-modal for renderizado pelo aplicativo, somente o primeiro elemento renderizado receberá alterações de classe CSS para exibir ou ocultar o elemento.

Adicione os estilos CSS a seguir à folha de estilos do site.

wwwroot/app.css:

#components-reconnect-modal {
    display: none;
}

#components-reconnect-modal.components-reconnect-show, 
#components-reconnect-modal.components-reconnect-failed, 
#components-reconnect-modal.components-reconnect-rejected {
    display: block;
}

A tabela a seguir descreve as classes CSS aplicadas ao elemento components-reconnect-modal pela estrutura Blazor.

Classe CSS	Indica...
components-reconnect-show	Uma conexão perdida. O cliente está tentando se reconectar. Mostra o modal.
components-reconnect-hide	Uma conexão ativa é restabelecida para o servidor. Oculta o modal.
components-reconnect-failed	Falha na reconexão, provavelmente devido a uma falha de rede. Para tentar reconexão, chame window.Blazor.reconnect() no JavaScript.
components-reconnect-rejected	Reconexão rejeitada. O servidor foi atingido, mas recusou a conexão e o estado do usuário no servidor foi perdido. Para recarregar o aplicativo, chame location.reload() no JavaScript. Esse estado de conexão pode resultar quando: Ocorre uma falha no circuito do lado do servidor. O cliente é desconectado tempo suficiente para que o servidor desative o estado do usuário. As instâncias dos componentes do usuário são descartadas. O servidor é reiniciado ou o processo de trabalho do aplicativo é reciclado.

Personalize o atraso antes que a exibição de reconexão apareça definindo a propriedade transition-delay no CSS do site para o elemento modal. O exemplo a seguir define o atraso de transição de 500 ms (padrão) para 1.000 ms (1 segundo).

wwwroot/app.css:

#components-reconnect-modal {
    transition: visibility 0s linear 1000ms;
}

Para exibir a tentativa de reconexão atual, defina um elemento com um id de components-reconnect-current-attempt. Para exibir o número máximo de repetições de reconexão, defina um elemento com um id de components-reconnect-max-retries. O exemplo a seguir coloca esses elementos dentro de um elemento modal de tentativa de reconexão seguindo o exemplo anterior.

<div id="components-reconnect-modal">
    There was a problem with the connection!
    (Current reconnect attempt: 
    <span id="components-reconnect-current-attempt"></span> /
    <span id="components-reconnect-max-retries"></span>)
</div>

Quando o modal de reconexão personalizado é exibido, ele renderiza conteúdo semelhante ao seguinte com base no código anterior:

There was a problem with the connection! (Current reconnect attempt: 3 / 8)

Renderização do lado do servidor

Por padrão, os componentes são pré-renderizados antes que a conexão do cliente com o servidor seja estabelecida. Para mais informações, confira Pré-renderizar componentes Razor do ASP.NET Core.

Monitorar a atividade do circuito do lado do servidor

Monitorar a atividade do circuito de entrada usando o método CreateInboundActivityHandler em CircuitHandler. Uma atividade de circuito de entrada é qualquer atividade enviada do navegador para o servidor, como eventos de interface do usuário ou chamadas de interoperabilidade JavaScript para o .NET.

Por exemplo, você pode usar um manipulador de atividade de circuito para detectar se o cliente está ocioso e registrar seu ID de circuito (Circuit.Id):

using Microsoft.AspNetCore.Components.Server.Circuits;
using Microsoft.Extensions.Options;
using Timer = System.Timers.Timer;

public sealed class IdleCircuitHandler : CircuitHandler, IDisposable
{
    private Circuit? currentCircuit;
    private readonly ILogger logger;
    private readonly Timer timer;

    public IdleCircuitHandler(ILogger<IdleCircuitHandler> logger, 
        IOptions<IdleCircuitOptions> options)
    {
        timer = new Timer
        {
            Interval = options.Value.IdleTimeout.TotalMilliseconds,
            AutoReset = false
        };

        timer.Elapsed += CircuitIdle;
        this.logger = logger;
    }

    private void CircuitIdle(object? sender, System.Timers.ElapsedEventArgs e)
    {
        logger.LogInformation("{CircuitId} is idle", currentCircuit?.Id);
    }

    public override Task OnCircuitOpenedAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        currentCircuit = circuit;

        return Task.CompletedTask;
    }

    public override Func<CircuitInboundActivityContext, Task> CreateInboundActivityHandler(
        Func<CircuitInboundActivityContext, Task> next)
    {
        return context =>
        {
            timer.Stop();
            timer.Start();

            return next(context);
        };
    }

    public void Dispose() => timer.Dispose();
}

public class IdleCircuitOptions
{
    public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromMinutes(5);
}

public static class IdleCircuitHandlerServiceCollectionExtensions
{
    public static IServiceCollection AddIdleCircuitHandler(
        this IServiceCollection services, 
        Action<IdleCircuitOptions> configureOptions)
    {
        services.Configure(configureOptions);
        services.AddIdleCircuitHandler();

        return services;
    }

    public static IServiceCollection AddIdleCircuitHandler(
        this IServiceCollection services)
    {
        services.AddScoped<CircuitHandler, IdleCircuitHandler>();

        return services;
    }
}

Cadastre o serviço no arquivo Program. O exemplo a seguir configura o tempo limite de inatividade padrão de cinco minutos a cinco segundos para testar a IdleCircuitHandler implementação anterior:

builder.Services.AddIdleCircuitHandler(options => 
    options.IdleTimeout = TimeSpan.FromSeconds(5));

Os manipuladores de atividade de circuito também fornecem uma abordagem para acessar serviços Blazor com escopo de outros escopos não Blazor de DI (injeção de dependência). Para obter mais informações e exemplos, consulte:

• Injeção de dependência no ASP.NET Core Blazor
• ASP.NET Core do lado do servidor Blazor cenários de segurança adicionais

Inicialização do Blazor

Configure o início manual do circuito do SignalR de um aplicativo Blazor no arquivo App.razor de um aplicativo Web Blazor:

• Adicione um atributo autostart="false" à marca <script> para o script blazor.*.js.
• Coloque um script que chama Blazor.start() depois que o script Blazor for carregado e dentro da marca </body> de fechamento.

Quando autostart estiver desabilitado, qualquer aspecto do aplicativo que não dependa do circuito funciona normalmente. Quando, por exemplo, o roteamento do lado do cliente estiver operacional. No entanto, qualquer aspecto que dependa do circuito não estará operacional até Blazor.start() que seja chamado. O comportamento do aplicativo é imprevisível sem um circuito estabelecido. Os métodos de componente, por exemplo, não são executados enquanto o circuito estiver desconectado.

Para obter mais informações, incluindo como inicializar o Blazor quando o documento estiver pronto e como encadear para um JS Promise, consulte Inicialização do ASP.NET Core Blazor.

Configurar tempos-limite SignalR e manter-se ativo no cliente

Configure os seguintes valores para o cliente:

• withServerTimeout: configura o tempo limite do servidor em milissegundos. Se esse tempo limite passar sem receber nenhuma mensagem do servidor, a conexão será encerrada com um erro. O valor padrão do tempo limite é de 30 segundos. O tempo limite do servidor deve ser pelo menos o dobro do valor atribuído ao intervalo de Keep Alive (withKeepAliveInterval).
• withKeepAliveInterval: configura o intervalo Keep-Alive em milissegundos (intervalo padrão no qual executar ping no servidor). Essa configuração permite que o servidor detecte desconexões físicas, como quando um cliente desconecta o computador da rede. O ping ocorre no máximo com a frequência em que o servidor realiza o ping. Se o servidor executar pings a cada cinco segundos, atribuir um valor menor que 5000 (5 segundos) executará pings a cada cinco segundos. O valor padrão é 15 segundos. O intervalo de Keep Alive deve ser inferior ou igual à metade do valor atribuído ao tempo limite do servidor (withServerTimeout).

O exemplo a seguir para o arquivo App.razor (Aplicativo Web Blazor) mostra a atribuição de valores padrão.

Aplicativo Web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      configureSignalR: function (builder) {
        builder.withServerTimeout(30000).withKeepAliveInterval(15000);
      }
    }
  });
</script>

O exemplo a seguir para o arquivo Pages/_Host.cshtml (Blazor Server, todas as versões, exceto ASP.NET Core em .NET 6) ou Pages/_Layout.cshtml (Blazor Server, ASP.NET Core em .NET 6).

Blazor Server:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
        builder.withServerTimeout(30000).withKeepAliveInterval(15000);
  });
</script>

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter o local do script e o caminho a ser usado, confira Estrutura do projeto ASP.NET Blazor.

Ao criar uma conexão de hub em um componente, defina o ServerTimeout (padrão: 30 segundos) e o KeepAliveInterval (padrão: 15 segundos) no HubConnectionBuilder. Defina o HandshakeTimeout (padrão: 15 segundos) no compilado HubConnection. O exemplo a seguir mostra a atribuição de valores padrão:

protected override async Task OnInitializedAsync()
{
    hubConnection = new HubConnectionBuilder()
        .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
        .WithServerTimeout(TimeSpan.FromSeconds(30))
        .WithKeepAliveInterval(TimeSpan.FromSeconds(15))
        .Build();

    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(15);

    hubConnection.On<string, string>("ReceiveMessage", (user, message) => ...

    await hubConnection.StartAsync();
}

Ao alterar os valores do tempo limite do servidor (ServerTimeout) ou do intervalo de Keep Alive (KeepAliveInterval):

• O tempo limite do servidor deve ser pelo menos o dobro do valor atribuído ao intervalo de Keep Alive.
• O intervalo de Keep Alive deve ser inferior ou igual à metade do valor atribuído ao tempo limite do servidor.

Para obter mais informações, consulte as seções Falhas globais de implantação e conexão dos seguintes artigos:

• Hospedar e implantar Blazor aplicativos do ASP.NET Core no lado do servidor
• Hospedar e implantar o ASP.NET Core Blazor WebAssembly

Modificar o manipulador de reconexão do lado do servidor

Os eventos de conexão de circuito do manipulador de reconexão podem ser modificados para comportamentos personalizados, tais como:

• Notificar o usuário se a conexão for descartada.
• Executar o registro em log (do cliente) quando um circuito estiver conectado.

Modificar os eventos de conexão, registre retornos de chamada para as seguintes alterações de conexão:

• As conexões descartadas usam onConnectionDown.
• As conexões estabelecidas/restabelecidas usam onConnectionUp.

Ambos onConnectionDown e onConnectionUp devem ser especificados.

Aplicativo Web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      reconnectionHandler: {
        onConnectionDown: (options, error) => console.error(error),
        onConnectionUp: () => console.log("Up, up, and away!")
      }
    }
  });
</script>

Blazor Server:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    reconnectionHandler: {
      onConnectionDown: (options, error) => console.error(error),
      onConnectionUp: () => console.log("Up, up, and away!")
    }
  });
</script>

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter o local do script e o caminho a ser usado, confira Estrutura do projeto ASP.NET Blazor.

Atualize automaticamente a página quando a reconexão do lado do servidor falhar

O comportamento de reconexão padrão exige que o usuário execute uma ação manual para atualizar a página após a falha na reconexão. No entanto, um manipulador de reconexão personalizado pode ser usado para atualizar automaticamente a página:

App.razor:

<div id="reconnect-modal" style="display: none;"></div>
<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script src="boot.js"></script>

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter o local do script e o caminho a ser usado, confira Estrutura do projeto ASP.NET Blazor.

Crie o seguinte arquivo wwwroot/boot.js.

Aplicativo Web Blazor:

(() => {
  const maximumRetryCount = 3;
  const retryIntervalMilliseconds = 5000;
  const reconnectModal = document.getElementById('reconnect-modal');

  const startReconnectionProcess = () => {
    reconnectModal.style.display = 'block';

    let isCanceled = false;

    (async () => {
      for (let i = 0; i < maximumRetryCount; i++) {
        reconnectModal.innerText = `Attempting to reconnect: ${i + 1} of ${maximumRetryCount}`;

        await new Promise(resolve => setTimeout(resolve, retryIntervalMilliseconds));

        if (isCanceled) {
          return;
        }

        try {
          const result = await Blazor.reconnect();
          if (!result) {
            // The server was reached, but the connection was rejected; reload the page.
            location.reload();
            return;
          }

          // Successfully reconnected to the server.
          return;
        } catch {
          // Didn't reach the server; try again.
        }
      }

      // Retried too many times; reload the page.
      location.reload();
    })();

    return {
      cancel: () => {
        isCanceled = true;
        reconnectModal.style.display = 'none';
      },
    };
  };

  let currentReconnectionProcess = null;

  Blazor.start({
    circuit: {
      reconnectionHandler: {
        onConnectionDown: () => currentReconnectionProcess ??= startReconnectionProcess(),
        onConnectionUp: () => {
          currentReconnectionProcess?.cancel();
          currentReconnectionProcess = null;
        }
      }
    }
  });
})();

Blazor Server:

(() => {
  const maximumRetryCount = 3;
  const retryIntervalMilliseconds = 5000;
  const reconnectModal = document.getElementById('reconnect-modal');

  const startReconnectionProcess = () => {
    reconnectModal.style.display = 'block';

    let isCanceled = false;

    (async () => {
      for (let i = 0; i < maximumRetryCount; i++) {
        reconnectModal.innerText = `Attempting to reconnect: ${i + 1} of ${maximumRetryCount}`;

        await new Promise(resolve => setTimeout(resolve, retryIntervalMilliseconds));

        if (isCanceled) {
          return;
        }

        try {
          const result = await Blazor.reconnect();
          if (!result) {
            // The server was reached, but the connection was rejected; reload the page.
            location.reload();
            return;
          }

          // Successfully reconnected to the server.
          return;
        } catch {
          // Didn't reach the server; try again.
        }
      }

      // Retried too many times; reload the page.
      location.reload();
    })();

    return {
      cancel: () => {
        isCanceled = true;
        reconnectModal.style.display = 'none';
      },
    };
  };

  let currentReconnectionProcess = null;

  Blazor.start({
    reconnectionHandler: {
      onConnectionDown: () => currentReconnectionProcess ??= startReconnectionProcess(),
      onConnectionUp: () => {
        currentReconnectionProcess?.cancel();
        currentReconnectionProcess = null;
      }
    }
  });
})();

Para obter mais informações sobre a inicialização de Blazor, veja Inicialização de Blazor no ASP.NET Core.

Ajustar a contagem e o intervalo de repetição de reconexão do lado do servidor

Para ajustar a contagem e o intervalo de repetição de reconexão, defina o número de repetições (maxRetries) e o período em milissegundos permitidos para cada tentativa de repetição (retryIntervalMilliseconds).

Aplicativo Web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      reconnectionOptions: {
        maxRetries: 3,
        retryIntervalMilliseconds: 2000
      }
    }
  });
</script>

Blazor Server:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    reconnectionOptions: {
      maxRetries: 3,
      retryIntervalMilliseconds: 2000
    }
  });
</script>

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter o local do script e o caminho a ser usado, confira Estrutura do projeto ASP.NET Blazor.

Para obter mais informações sobre a inicialização de Blazor, veja Inicialização de Blazor no ASP.NET Core.

Controle quando a interface do usuário de reconexão é exibida

O controle de quando a interface do usuário de reconexão é exibida pode ser útil nas seguintes situações:

• Um aplicativo implantado exibe frequentemente a interface do usuário de reconexão devido a tempos limite de ping causados pela latência da rede interna ou da Internet, e você gostaria de aumentar o atraso.
• Um aplicativo deve informar aos usuários que a conexão caiu mais cedo e você gostaria de reduzir o atraso.

O tempo de aparecimento da interface do usuário de reconexão é influenciado pelo ajuste do intervalo Keep-Alive e dos tempos limite no cliente. A interface do usuário de reconexão é exibida quando o tempo limite do servidor é atingido no cliente (withServerTimeout, seção Configuração do cliente). No entanto, alterar o valor de withServerTimeout exige alterações em outras configurações de keep alive, tempo limite e handshake descritas nas diretrizes a seguir.

Como recomendações gerais para as diretrizes a seguir:

• O intervalo Keep-Alive deve corresponder entre as configurações do cliente e do servidor.
• Os tempos limite devem ser pelo menos o dobro do valor atribuído ao intervalo Keep-Alive.

Configuração de Servidor

Defina o seguinte:

• ClientTimeoutInterval (padrão: 30 segundos): os clientes da janela de tempo precisam enviar uma mensagem antes que o servidor feche a conexão.
• HandshakeTimeout (padrão: 15 segundos): o intervalo usado pelo servidor para tempo limite de solicitações de handshake de entrada por clientes.
• KeepAliveInterval (padrão: 15 segundos): o intervalo usado pelo servidor para enviar pings de keep alive para clientes conectados. Observe que também há uma configuração de intervalo Keep-Alive no cliente, que deve corresponder ao valor do servidor.

O ClientTimeoutInterval e o HandshakeTimeout podem ser aumentados e o KeepAliveInterval pode permanecer o mesmo. A consideração importante é que, se você alterar os valores, verifique se os tempos limite são pelo menos o dobro do valor do intervalo Keep-Alive e se o intervalo Keep-Alive corresponde entre o servidor e o cliente. Para obter mais informações, consulte a seção Configurar SignalR tempos limite e Keep-Alive no cliente.

No exemplo a seguir:

• O ClientTimeoutInterval é aumentado para 60 segundos (valor padrão: 30 segundos).
• O HandshakeTimeout é aumentado para 30 segundos (valor padrão: 15 segundos).
• O KeepAliveInterval não está definido no código do desenvolvedor e usa seu valor padrão de 15 segundos. Diminuir o valor do intervalo Keep-Alive aumenta a frequência de pings de comunicação, o que aumenta a carga no aplicativo, servidor e rede. Deve-se tomar cuidado para evitar a introdução de um desempenho ruim ao reduzir o intervalo Keep-Alive.

BlazorAplicativo Web (.NET 8 ou posterior) no arquivo Program do projeto do servidor:

builder.Services.AddRazorComponents().AddInteractiveServerComponents()
    .AddHubOptions(options =>
{
    options.ClientTimeoutInterval = TimeSpan.FromSeconds(60);
    options.HandshakeTimeout = TimeSpan.FromSeconds(30);
});

Blazor Server no arquivo Program:

builder.Services.AddServerSideBlazor()
    .AddHubOptions(options =>
    {
        options.ClientTimeoutInterval = TimeSpan.FromSeconds(60);
        options.HandshakeTimeout = TimeSpan.FromSeconds(30);
    });

Para obter mais informações, consulte a seção Opções do manipulador de circuito do lado do servidor.

Configuração do cliente

Defina o seguinte:

• withServerTimeout (padrão: 30 segundos): configura o tempo limite do servidor, especificado em milissegundos, para a conexão do hub do circuito.
• withKeepAliveInterval (padrão: 15 segundos): o intervalo, especificado em milissegundos, no qual a conexão envia mensagens Keep-Alive.

O tempo limite do servidor pode ser aumentado e o intervalo Keep-Alive pode permanecer o mesmo. A consideração importante é que, se você alterar os valores, verifique se os tempos limite são pelo menos o dobro do valor do intervalo Keep-Alive e se os valores do intervalo Keep-Alive correspondem entre o servidor e o cliente. Para obter mais informações, consulte a seção Configurar SignalR tempos limite e Keep-Alive no cliente.

No exemplo de configuração de inicialização a seguir (localização do Blazor script), um valor personalizado de 60 segundos é usado para o tempo limite do servidor. O intervalo Keep-Alive (withKeepAliveInterval) não é definido e usa seu valor padrão de 15 segundos.

Aplicativo Web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      configureSignalR: function (builder) {
        builder.withServerTimeout(60000);
      }
    }
  });
</script>

Blazor Server:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      builder.withServerTimeout(60000);
    }
  });
</script>

Ao criar uma conexão de hub em um componente, defina o tempo limite do servidor (WithServerTimeout, padrão: 30 segundos) no HubConnectionBuilder. Defina o HandshakeTimeout (padrão: 15 segundos) no compilado HubConnection. Confirme se os tempos limite são pelo menos o dobro do intervalo Keep-Alive (WithKeepAliveInterval/KeepAliveInterval) e se o valor Keep-Alive corresponde entre o servidor e o cliente.

O exemplo a seguir baseia-se no Index componente no SignalR com o tutorial do Blazor. O tempo limite do servidor é aumentado para 60 segundos e o tempo limite do handshake é aumentado para 30 segundos. O intervalo Keep-Alive não está definido e usa seu valor padrão de 15 segundos.

protected override async Task OnInitializedAsync()
{
    hubConnection = new HubConnectionBuilder()
        .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
        .WithServerTimeout(TimeSpan.FromSeconds(60))
        .Build();

    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(30);

    hubConnection.On<string, string>("ReceiveMessage", (user, message) => ...

    await hubConnection.StartAsync();
}

Desconectar o circuito Blazor do cliente

Por padrão, um circuito Blazor é desconectado quando o unloadevento da página é disparado. Para desconectar o circuito para outros cenários no cliente, invoque Blazor.disconnect no manipulador de eventos apropriado. No exemplo a seguir, o circuito é desconectado quando a página está oculta ( eventopagehide):

window.addEventListener('pagehide', () => {
  Blazor.disconnect();
});

Para obter mais informações sobre a inicialização de Blazor, veja Inicialização de Blazor no ASP.NET Core.

Manipulador de circuito do lado do servidor

Você pode definir um manipulador de circuito, o que permite a execução de código em alterações no estado do circuito de um usuário. Um manipulador de circuito é implementado derivando do CircuitHandler e registrando a classe no contêiner de serviço do aplicativo. O exemplo a seguir de um manipulador de circuito rastreia conexões SignalR abertas.

TrackingCircuitHandler.cs:

using Microsoft.AspNetCore.Components.Server.Circuits;

public class TrackingCircuitHandler : CircuitHandler
{
    private HashSet<Circuit> circuits = new();

    public override Task OnConnectionUpAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        circuits.Add(circuit);

        return Task.CompletedTask;
    }

    public override Task OnConnectionDownAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        circuits.Remove(circuit);

        return Task.CompletedTask;
    }

    public int ConnectedCircuits => circuits.Count;
}

Os manipuladores de circuito são registrados usando DI. As instâncias com escopo são criadas por instância de um circuito. Usando o TrackingCircuitHandler no exemplo anterior, um serviço singleton é criado porque o estado de todos os circuitos deve ser rastreado.

No arquivo Program:

builder.Services.AddSingleton<CircuitHandler, TrackingCircuitHandler>();

Se os métodos de um manipulador de circuito personalizado gerarem uma exceção sem tratamento, a exceção será fatal para o circuito. Para tolerar exceções no código de um manipulador ou métodos chamados, encapsule o código em uma ou mais instruções try-catch com tratamento de erros e registro em log.

Quando um circuito termina porque um usuário se desconectou e a estrutura está limpando o estado do circuito, a estrutura descarta o escopo DI do circuito. Descartar o escopo elimina todos os serviços DI com escopo de circuito que implementam System.IDisposable. Se qualquer serviço DI gerar uma exceção sem tratamento durante o descarte, a estrutura registrará a exceção em log. Para saber mais, confira Injeção de dependência do Blazor no ASP.NET Core.

Manipulador de circuito para capturar usuários para serviços personalizados

Use um CircuitHandler para capturar um usuário do AuthenticationStateProvider e definir esse usuário em um serviço. Para obter mais informações e exemplos de código, consulte ASP.NET Core do lado do servidor Blazor cenários de segurança adicionais.

Fechamento de circuitos quando não existem componentes do Servidor Interativo restantes

Os componentes do Servidor Interativo lidam com eventos da interface do usuário da Web utilizando uma conexão em tempo real com o navegador conhecida como circuito. Um circuito e seu estado associado são criados quando um componente do Servidor Interativo raiz é renderizado. O circuito é fechado quando não existem componentes do Servidor Interativo restantes na página, o que libera recursos do servidor.

IHttpContextAccessor/HttpContext em Razor componentes

IHttpContextAccessor deve ser evitado com a renderização interativa porque não há um HttpContext disponível válido.

IHttpContextAccessor pode ser usado para componentes que são renderizados estaticamente no servidor. No entanto, recomendamos evitá-lo, se possível.

HttpContext pode ser usado como um parâmetro em cascata apenas em componentes raiz renderizados estaticamente para tarefas gerais, como inspecionar e modificar cabeçalhos ou outras propriedades no componente App (Components/App.razor). O valor é sempre null para renderização interativa.

[CascadingParameter]
public HttpContext? HttpContext { get; set; }

Para cenários em que o componente HttpContext é necessário em componentes interativos, recomendamos fluir os dados por meio do estado de componente persistente do servidor. Para obter mais informações, confira Cenários de segurança adicionais Blazor do ASP.NET Core do lado do servidor.

Recursos adicionais do lado do servidor

• Diretrizes de hospedagem e implantação do lado do servidor: configuração do SignalR
• Visão geral do ASP.NET CoreSignalR
• Configuração do ASP.NET Core SignalR
• Documentação de segurança do lado do servidor
  • Autenticação e autorização de Blazor no ASP.NET Core
  • Segurança no ASP.NET Core do lado do servidor Blazor aplicativos
  • Diretrizes de mitigação de ameaças para a renderização interativa do ASP.NET Core Blazor do lado do servidor
  • ASP.NET Core do lado do servidor Blazor cenários de segurança adicionais
• Eventos de reconexão e eventos de ciclo de vida do componente do lado do servidor
• O que é o Serviço SignalR do Azure ?
• Guia de desempenho do Serviço SignalR do Azure
• Publicar um aplicativo SignalR ASP.NET Core no Serviço de Aplicativo do Azure
• Repositório GitHub de amostras do Blazor (dotnet/blazor-samples) (como baixar)