Conseils pour ASP.NET Core BlazorSignalR

Azure SignalR Service avec reconnexion avec état

La reconnexion avec état (WithStatefulReconnect) a été mise en production avec .NET 8, mais n’est actuellement pas prise en charge pour Azure SignalR Service. Pour plus d’informations, consultez l’article Prise en charge de la reconnexion avec état ? (Azure/azure-signalr #1878).

Compression WebSocket pour des composants de serveur interactif

Par défaut, les composants de serveur interactif :

• Activez la compression des connexions WebSocket. ConfigureWebsocketOptions contrôle la compression WebSocket.

• Adoptez une directive de stratégie de sécurité du contenu (CSP) frame-ancestors définie sur 'self', qui autorise uniquement l’incorporation de l’application dans un <iframe> de l’origine à partir de laquelle l’application est servie lorsque la compression est activée ou lorsqu’une configuration est fournie pour le contexte WebSocket. ContentSecurityFrameAncestorPolicy contrôle le CSP frame-ancestors.

Le CSP frame-ancestors peut être supprimé manuellement en définissant la valeur de ConfigureWebSocketOptions sur null, car vous souhaitez peut-être configurer le CSP de manière centralisée. Lorsque le CSP frame-ancestors est managé de manière centralisée, vous devez veiller à appliquer une stratégie chaque fois que le premier document est rendu. Nous déconseillons de supprimer complètement la stratégie, car cela peut rendre l’application vulnérable aux attaques.

Exemples d'utilisation :

Désactiver la compression en définissant ConfigureWebSocketOptions sur null, ce qui réduit la vulnérabilité de l’application aux attaques, mais peut entraîner une réduction des performances :

builder.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode(o => o.ConfigureWebSocketOptions = null)

Lorsque la compression est activée, configurez un CSP frame-ancestors plus strict avec une valeur de 'none' (guillemets simples obligatoires), qui autorise la compression WebSocket mais empêche les navigateurs d’incorporer l’application dans n’importe quel <iframe> :

builder.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode(o => o.ContentSecurityFrameAncestorsPolicy = "'none'")

Lorsque la compression est activée, supprimez le CSP frame-ancestors en définissant ContentSecurityFrameAncestorsPolicy sur null. Ce scénario est recommandé uniquement pour les applications qui définissent le CSP de manière centralisée :

builder.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode(o => o.ContentSecurityFrameAncestorsPolicy = null)

Pour plus d’informations sur la sécurité, consultez Aide sur l’atténuation des menaces pour le rendu interactif côté serveur ASP.NET Core Blazor. Pour plus d’informations sur la directive frame-ancestors, consultez CSP : frame-ancestors (documentation MDN).

Désactiver la compression des réponses pour le rechargement à chaud

Lorsque vous utilisez le Rechargement à chaud, désactivez l’intergiciel de compression de réponse dans l’environnement Development. Que le code par défaut d’un modèle de projet soit utilisé ou non, appelez toujours UseResponseCompression en premier dans le pipeline de traitement des requêtes.

Dans le fichier Program :

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

Si le prérendu est configuré, il se produit avant l’établissement de la connexion du client au serveur. Pour plus d’informations, consultez Prévisualiser les composants ASP.NET Core Razor.

Si le prérendu est configuré, il se produit avant l’établissement de la connexion du client au serveur. Pour plus d’informations, consultez les articles suivants :

• Tag Helper de composant dans ASP.NET Core
• Prérendu et intégration des composants Razor d’ASP.NET Core

Parcourez ou définissez les options dans le fichier Program avec un délégué d’options sur AddInteractiveServerComponents. L’espace réservé {OPTION} représente l’option et l’espace réservé {VALUE} est la valeur.

Dans le fichier Program :

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

Parcourez ou définissez les options dans le fichier Program avec un délégué d’options sur AddServerSideBlazor. L’espace réservé {OPTION} représente l’option et l’espace réservé {VALUE} est la valeur.

Dans le fichier Program :

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

Parcourez ou définissez les options dans Startup.ConfigureServices avec un délégué d’options sur AddServerSideBlazor. L’espace réservé {OPTION} représente l’option et l’espace réservé {VALUE} est la valeur.

Dans Startup.ConfigureServices de Startup.cs :

services.AddServerSideBlazor(options =>
{
    options.{OPTION} = {VALUE};
});

Dans le fichier Program :

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

Dans le fichier Program :

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

Dans Startup.ConfigureServices de Startup.cs :

services.AddServerSideBlazor().AddHubOptions(options =>
{
    options.{OPTION} = {VALUE};
});

Placez l’appel à app.MapBlazorHub après l’appel à app.MapRazorComponents dans le fichier Program de l’application :

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

La configuration du hub utilisé par AddInteractiveServerRenderMode avec MapBlazorHub échoue et lève une exception AmbiguousMatchException :

Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException: The request matched multiple endpoints.

Pour contourner le problème pour les applications ciblant .NET 8, accordez une priorité plus élevée au hub personnalisé Blazor configuré à l’aide de la méthode WithOrder :

app.MapBlazorHub(options =>
{
    options.CloseOnAuthenticationExpiration = true;
}).WithOrder(-1);

Pour plus d’informations, consultez les ressources suivantes :

• La configuration de MapBlazorHub dans NET8 renvoie une exception « La requête correspond à plusieurs points de terminaison » (dotnet/aspnetcore #51698)
• Les tentatives de mappage de plusieurs points d’entrée blazor avec MapBlazorHub provoquent une erreur « routage ambigu ». Cela fonctionnait avec net7 (dotnet/aspnetcore #52156)

Fournissez les options à app.MapBlazorHub dans le fichier Program de l’application :

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

Fournissez les options à app.MapBlazorHub dans la configuration du routage des points de terminaison :

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

Une approche consiste à augmenter la limite en définissant MaximumReceiveMessageSize dans le fichier Program. L’exemple suivant définit la taille maximale des messages de réception à 64 Ko :

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

L’augmentation de la taille des messages entrants SignalR est limitée par le coût d’exiger davantage de ressources serveur et augmente le risque d’attaques par déni de service (DoS). En outre, la lecture d’une grande quantité de contenu dans la mémoire sous forme de chaînes ou de tableaux d’octets peut également entraîner des allocations qui fonctionnent mal avec le récupérateur de mémoire, ce qui entraîne des pénalités de performances supplémentaires.

Une meilleure option de lecture de charges utiles volumineuses consiste à envoyer le contenu en blocs plus petits et à traiter la charge utile en tant que Stream. Cela peut être utilisé lors de la lecture de charges utiles JSON d’interopérabilité JavaScript (JS) volumineuses ou si les données d’interopérabilité JS sont disponibles sous forme d’octets bruts. Pour obtenir un exemple illustrant l’envoi de charges utiles binaires volumineuses dans des applications côté serveur à l’aide de techniques similaires au composant InputFile, consultez l’exemple d’application Envoi binaire et l’exemple de composant BlazorInputLargeTextArea.

Les formulaires qui traitent des charges utiles volumineuses sur SignalR peuvent également utiliser l’interopérabilité JS de diffusion en continu directement. Pour plus d’informations, consultez Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor. Pour obtenir un exemple de formulaire qui diffuse des <textarea> données vers le serveur, reportez-vous aux formulairesBlazor Résoudre les problèmes ASP.NET Core.

Une approche consiste à augmenter la limite en définissant MaximumReceiveMessageSize dans le fichier Program. L’exemple suivant définit la taille maximale des messages de réception à 64 Ko :

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

L’augmentation de la taille des messages entrants SignalR est limitée par le coût d’exiger davantage de ressources serveur et augmente le risque d’attaques par déni de service (DoS). En outre, la lecture d’une grande quantité de contenu dans la mémoire sous forme de chaînes ou de tableaux d’octets peut également entraîner des allocations qui fonctionnent mal avec le récupérateur de mémoire, ce qui entraîne des pénalités de performances supplémentaires.

Une meilleure option de lecture de charges utiles volumineuses consiste à envoyer le contenu en blocs plus petits et à traiter la charge utile en tant que Stream. Cela peut être utilisé lors de la lecture de charges utiles JSON d’interopérabilité JavaScript (JS) volumineuses ou si les données d’interopérabilité JS sont disponibles sous forme d’octets bruts. Pour obtenir un exemple illustrant l’envoi de charges utiles binaires volumineuses dans Blazor Server à l’aide de techniques similaires au composant InputFile, consultez l’exemple d’application Envoi binaire et l’exemple de composant BlazorInputLargeTextArea.

Les formulaires qui traitent des charges utiles volumineuses sur SignalR peuvent également utiliser l’interopérabilité JS de diffusion en continu directement. Pour plus d’informations, consultez Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor. Pour obtenir un exemple de formulaire qui diffuse des <textarea> données dans une Blazor Server application, reportez-vous aux Blazorformulaires Résoudre les problèmes ASP.NET formulaires Core.

Augmentez la limite en définissant MaximumReceiveMessageSize dans Startup.ConfigureServices :

services.AddServerSideBlazor()
    .AddHubOptions(options => options.MaximumReceiveMessageSize = 64 * 1024);

L’augmentation de la taille des messages entrants SignalR est limitée par le coût d’exiger davantage de ressources serveur et augmente le risque d’attaques par déni de service (DoS). En outre, la lecture d’une grande quantité de contenu dans la mémoire sous forme de chaînes ou de tableaux d’octets peut également entraîner des allocations qui fonctionnent mal avec le récupérateur de mémoire, ce qui entraîne des pénalités de performances supplémentaires.

• Tirez parti de la prise en charge de l’interopérabilité JS de diffusion en continu native pour transférer des données de taille supérieure à la limite de taille de message entrant SignalR :
  • Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor
  • Appeler des méthodes .NET à partir de fonctions JavaScript dans ASP.NET Core Blazor
  • Exemple de charge utile de formulaire : Résoudre les problèmes liés aux formulaires ASP.NET Core Blazor
• Conseils généraux :
  • N’allouez pas d’objets volumineux dans JS et le code C#.
  • Libérez la mémoire consommée lorsque le processus est terminé ou annulé.
  • Appliquez les exigences supplémentaires suivantes à des fins de sécurité :
    • Déclarez la taille de fichier ou de données maximale qui peut être transmise.
    • Déclarez le taux de chargement minimal du client vers le serveur.
  • Une fois les données reçues par le serveur, les données peuvent être :
    • Stockées temporairement dans une mémoire tampon jusqu’à ce que tous les segments soient collectés.
    • Consommées immédiatement. Par exemple, les données peuvent être stockées immédiatement dans une base de données ou écrites sur le disque à mesure que chaque segment est reçu.

• Découpez les données en morceaux plus petits et envoyez les segments de données séquentiellement jusqu’à ce que toutes les données soient reçues par le serveur.
• N’allouez pas d’objets volumineux dans JS et le code C#.
• Ne bloquez pas le thread d’interface utilisateur main pendant de longues périodes lors de l’envoi ou de la réception de données.
• Libérez la mémoire consommée lorsque le processus est terminé ou annulé.
• Appliquez les exigences supplémentaires suivantes à des fins de sécurité :
  • Déclarez la taille de fichier ou de données maximale qui peut être transmise.
  • Déclarez le taux de chargement minimal du client vers le serveur.
• Une fois les données reçues par le serveur, les données peuvent être :
  • Stockées temporairement dans une mémoire tampon jusqu’à ce que tous les segments soient collectés.
  • Consommées immédiatement. Par exemple, les données peuvent être stockées immédiatement dans une base de données ou écrites sur le disque à mesure que chaque segment est reçu.

Pour personnaliser l’interface utilisateur, définissez un élément unique avec un id de components-reconnect-modal. L’exemple suivant place l’élément dans le composant App.

App.razor :

Pour personnaliser l’interface utilisateur, définissez un élément unique avec un id de components-reconnect-modal. L’exemple suivant place l’élément dans la page hôte.

Pages/_Host.cshtml :

Pour personnaliser l’interface utilisateur, définissez un élément unique avec un id de components-reconnect-modal. L’exemple suivant place l’élément dans la page de disposition.

Pages/_Layout.cshtml :

Pour personnaliser l’interface utilisateur, définissez un élément unique avec un id de components-reconnect-modal. L’exemple suivant place l’élément dans la page hôte.

Pages/_Host.cshtml :

wwwroot/app.css :

wwwroot/css/site.css :

Personnalisez le délai avant l’affichage de l’interface utilisateur de reconnexion en définissant la propriété transition-delay dans le CSS du site pour l’élément modal. L’exemple suivant modifie le délai de transition de 500 ms (par défaut) à 1 000 ms (1 seconde).

wwwroot/app.css :

wwwroot/css/site.css :

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

Pour afficher la tentative de reconnexion actuelle, définissez un élément avec un id de components-reconnect-current-attempt. Pour afficher le nombre maximal de nouvelles tentatives de reconnexion, définissez un élément avec un id de components-reconnect-max-retries. L’exemple suivant place ces éléments à l’intérieur d’un élément modal de tentative de reconnexion à la suite de l’exemple précédent.

<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>

Lorsque la fenêtre modale de reconnexion personnalisée s’affiche, elle affiche un contenu similaire à ce qui suit en fonction du code précédent :

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

Par défaut, les composants sont prérendus sur le serveur avant l’établissement de la connexion cliente au serveur. Pour plus d’informations, consultez Prévisualiser les composants ASP.NET Core Razor.

Par défaut, les composants sont prérendus sur le serveur avant l’établissement de la connexion cliente au serveur. Pour plus d’informations, consultez assistance des balises de composant dans ASP.NET Core.

Surveiller l’activité du circuit côté serveur

Surveillez l’activité du circuit entrant à l’aide de la méthode CreateInboundActivityHandler sur CircuitHandler. L’activité du circuit entrant est toute activité envoyée du navigateur au serveur, comme les événements d’interface utilisateur ou les appels d’interopérabilité JavaScript-to-.NET.

Par exemple, vous pouvez utiliser un gestionnaire d’activités de circuit pour détecter si le client est inactif et journaliser son ID de circuit (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;
    }
}

Inscrivez le service dans le fichier Program. L’exemple suivant configure le délai d’inactivité par défaut de cinq minutes à cinq secondes pour tester l’implémentation de IdleCircuitHandler précédente :

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

Les gestionnaires d’activités de circuit proposent également une approche pour accéder aux services Blazor délimités à partir d’autres étendues d’injection de dépendances non Blazor. Pour plus d’informations et d’exemples, consultez :

• Injection de dépendances ASP.NET Core Blazor
• Autres scénarios de sécurité ASP.NET Core Blazor côté serveur

Configurez le démarrage manuel du circuit SignalR d’une application Blazor dans le fichier App.razor (Blazor Web App) :

Configurez le démarrage manuel du circuit SignalR d’une application Blazor dans le fichier Pages/_Host.cshtml (Blazor Server) :

Configurez le démarrage manuel du circuit SignalR d’une application Blazor dans le fichier Pages/_Layout.cshtml (Blazor Server) :

Configurez le démarrage manuel du circuit SignalR d’une application Blazor dans le fichier Pages/_Host.cshtml (Blazor Server) :

Configurez les valeurs suivantes pour le client :

• withServerTimeout : configure le délai d’attente du serveur en millisecondes. Si ce délai d’attente s’écoule sans réception de messages du serveur, la connexion se termine avec une erreur. La valeur de délai d'attente par défaut est de 30 secondes. Le délai d’expiration du serveur doit être au moins le double de la valeur affectée à l’intervalle Keep-Alive (withKeepAliveInterval).
• withKeepAliveInterval : configure l’intervalle Keep-Alive en millisecondes (intervalle par défaut auquel effectuer un test ping sur le serveur). Ce paramètre permet au serveur de détecter les déconnexions matérielles, par exemple lorsqu’un client débranche son ordinateur du réseau. Le ping se produit au maximum aussi souvent que le serveur envoie des pings. Si le serveur envoie un ping toutes les cinq secondes, l’affectation d’une valeur inférieure à 5000 (5 secondes) correspond à un test ping toutes les cinq secondes. La valeur par défaut est de 15 secondes. L’intervalle Keep-Alive doit être inférieur ou égal à la moitié de la valeur affectée au délai d’expiration du serveur (withServerTimeout).

L’exemple suivant pour le fichier App.razor (Blazor Web App) affiche l’affectation des valeurs par défaut.

Blazor Web App :

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

L’exemple suivant pour le fichier Pages/_Host.cshtml (Blazor Server, toutes les versions sauf ASP.NET Core dans .NET 6) ou le fichier Pages/_Layout.cshtml (Blazor Server, ASP.NET Core dans .NET 6).

Blazor Server :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script et le chemin d’accès à utiliser, consultez Structure de projet Blazor ASP.NET Core.

Lors de la création d’une connexion hub dans un composant, définissez ServerTimeout (valeur par défaut : 30 secondes) et KeepAliveInterval (valeur par défaut : 15 secondes) sur le HubConnectionBuilder. Définissez HandshakeTimeout (valeur par défaut : 15 secondes) au niveau de la HubConnection générée. L’exemple suivant montre l’affectation de valeurs par défaut :

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();
}

Configurez les valeurs suivantes pour le client :

• serverTimeoutInMilliseconds : délai d’attente du serveur en millisecondes. Si ce délai d’attente s’écoule sans réception de messages du serveur, la connexion se termine avec une erreur. La valeur de délai d'attente par défaut est de 30 secondes. Le délai d’expiration du serveur doit être au moins le double de la valeur affectée à l’intervalle Keep-Alive (keepAliveIntervalInMilliseconds).
• keepAliveIntervalInMilliseconds : intervalle par défaut auquel effectuer un ping sur le serveur. Ce paramètre permet au serveur de détecter les déconnexions matérielles, par exemple lorsqu’un client débranche son ordinateur du réseau. Le ping se produit au maximum aussi souvent que le serveur envoie des pings. Si le serveur envoie un ping toutes les cinq secondes, l’affectation d’une valeur inférieure à 5000 (5 secondes) correspond à un test ping toutes les cinq secondes. La valeur par défaut est de 15 secondes. L’intervalle Keep-Alive doit être inférieur ou égal à la moitié de la valeur affectée au délai d’expiration du serveur (serverTimeoutInMilliseconds).

L’exemple suivant pour le fichier Pages/_Host.cshtml (Blazor Server, toutes les versions sauf ASP.NET Core dans .NET 6) ou le fichier Pages/_Layout.cshtml (Blazor Server, ASP.NET Core dans .NET 6) :

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      let c = builder.build();
      c.serverTimeoutInMilliseconds = 30000;
      c.keepAliveIntervalInMilliseconds = 15000;
      builder.build = () => {
        return c;
      };
    }
  });
</script>

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script et le chemin d’accès à utiliser, consultez Structure de projet Blazor ASP.NET Core.

Lors de la création d’une connexion hub dans un composant, définissez ServerTimeout (valeur par défaut : 30 secondes), HandshakeTimeout (valeur par défaut : 15 secondes) et KeepAliveInterval (valeur par défaut : 15 secondes) sur la HubConnection générée. L’exemple suivant montre l’affectation de valeurs par défaut :

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

    hubConnection.ServerTimeout = TimeSpan.FromSeconds(30);
    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(15);
    hubConnection.KeepAliveInterval = TimeSpan.FromSeconds(15);

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

    await hubConnection.StartAsync();
}

Blazor Web App :

<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 :

Actualiser automatiquement la page en cas d’échec de reconnexion côté serveur

Le comportement de reconnexion par défaut nécessite que l’utilisateur effectue une action manuelle pour actualiser la page après l’échec de la reconnexion. Toutefois, un gestionnaire de reconnexion personnalisé peut être utilisé pour actualiser automatiquement la page :

App.razor :

Pages/_Host.cshtml :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script et le chemin d’accès à utiliser, consultez Structure de projet Blazor ASP.NET Core.

Créez le fichier wwwroot/boot.js suivant.

Blazor Web App :

(() => {
  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;
      }
    }
  });
})();

Pour plus d’informations sur le démarrage de Blazor, consultez Démarrage d’ASP.NET Core Blazor.

Blazor Web App :

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

Blazor Server :

Lorsque l’utilisateur retourne à une application avec un circuit déconnecté, la reconnexion est tentée immédiatement plutôt que d’attendre pendant la durée du prochain intervalle de reconnexion. Ce comportement s’efforce de reprendre la connexion aussi rapidement que possible pour l’utilisateur.

Le minutage de reconnexion par défaut utilise une stratégie de backoff calculée. Les premières tentatives de reconnexion se produisent rapidement avant l’introduction de délais calculés entre les tentatives. La logique par défaut pour calculer l’intervalle avant nouvelle tentative est un détail d’implémentation susceptible de changer sans préavis, mais vous trouverez la logique par défaut utilisée par l’infrastructure Blazor dans la fonction computeDefaultRetryInterval (source de référence).

Personnalisez le comportement d’intervalle avant nouvelle tentative en spécifiant une fonction de calcul d’intervalle avant nouvelle tentative. Dans l’exemple de backoff exponentiel suivant, le nombre de tentatives de reconnexion précédent est multipliée par 1 000 ms pour calculer l’intervalle avant nouvelle tentative. Lorsque le nombre de tentatives précédentes pour la reconnexion (previousAttempts) est supérieur à la limite maximale de nouvelle tentative (maxRetries), null est affecté à l’intervalle avant nouvelle tentative (retryIntervalMilliseconds) pour arrêter davantage de tentatives de reconnexion :

Blazor.start({
  circuit: {
    reconnectionOptions: {
      retryIntervalMilliseconds: (previousAttempts, maxRetries) => 
        previousAttempts >= maxRetries ? null : previousAttempts * 1000
    },
  },
});

Une solution de rechange consiste à spécifier la séquence exacte des intervalles avant nouvelles tentative. Après le dernier intervalle avant nouvelle tentative spécifié, les nouvelles tentatives s’arrêtent car la fonction retryIntervalMilliseconds renvoie undefined :

Blazor.start({
  circuit: {
    reconnectionOptions: {
      retryIntervalMilliseconds: 
        Array.prototype.at.bind([0, 1000, 2000, 5000, 10000, 15000, 30000]),
    },
  },
});

Contrôler quand l’interface utilisateur de reconnexion s’affiche

Contrôler quand l’interface utilisateur de reconnexion s’affiche peut être utile dans les situations suivantes :

• Une application déployée affiche fréquemment l’interface utilisateur de reconnexion à cause des pauses de ping provoquées par une latence réseau interne ou Internet, et vous souhaitez augmenter le délai.
• Une application doit signaler aux utilisateurs que la connexion a été supprimée plus tôt et que vous souhaitez raccourcir le délai.

Le délai de l’interface utilisateur de reconnexion est influencé par l’ajustement de l’intervalle Keep-Alive et des délais d’expiration sur le client. L’interface utilisateur de reconnexion s’affiche lorsque le délai d’expiration du serveur est atteint sur le client (withServerTimeout, section configuration du client ). Toutefois, la modification de la valeur de withServerTimeout nécessite des modifications apportées à d’autres paramètres Keep-Alive, de délai d’attente et d’établissement d’une liaison décrits dans les instructions suivantes.

En guise de recommandations générales pour les conseils suivants :

• L’intervalle Keep-Alive doit correspondre entre les configurations client et serveur.
• Les délais d’expiration doivent être au moins le double de la valeur affectée à l’intervalle Keep-Alive.

Configurer le serveur

Spécifiez les paramètres suivants :

• ClientTimeoutInterval (valeur par défaut : 30 secondes) : les clients de fenêtre de temps doivent envoyer un message avant que le serveur ferme la connexion.
• HandshakeTimeout (valeur par défaut : 15 secondes) : intervalle utilisé par le serveur pour l’expiration des demandes d’établissement de liaison entrantes par les clients.
• KeepAliveInterval (valeur par défaut : 15 secondes) : intervalle utilisé par le serveur pour envoyer des pings Keep Alive aux clients connectés. Notez qu’il existe également un paramètre d’intervalle Keep-Alive sur le client, qui doit correspondre à la valeur du serveur.

Les intervalles ClientTimeoutInterval et HandshakeTimeout peuvent être augmentés, et KeepAliveInterval peut rester le même. L’important est que si vous modifiez les valeurs. Assurez-vous que les délais d’expiration sont au moins deux fois la valeur de l’intervalle Keep-Alive et que celui-ci correspond entre le serveur et le client. Pour plus d’informations, consultez la section Configurer les délais d’expiration SignalR et Keep-Alive sur le client.

Dans l’exemple suivant :

• L’intervalle ClientTimeoutInterval est augmenté à 60 secondes (valeur par défaut : 30 secondes).
• Le délai HandshakeTimeout est augmenté à 30 secondes (valeur par défaut : 15 secondes).
• L’intervalle KeepAliveInterval n’est pas défini dans le code du développeur et utilise sa valeur par défaut de 15 secondes. La diminution de la valeur de l’intervalle Keep-Alive augmente la fréquence des pings de communication, ce qui augmente la charge sur l’application, le serveur et le réseau. Veillez à éviter d’introduire de mauvaises performances lors de l’abaissement de l’intervalle Keep-Alive.

Blazor Web App (.NET 8 ou version ultérieure) dans le fichier Program du projet de serveur :

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

Blazor Server dans le fichierProgram :

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

Pour plus d’informations, consultez la section Options de gestionnaire de circuit côté serveur.

Configuration de client

Spécifiez les paramètres suivants :

• withServerTimeout (valeur par défaut : 30 secondes) : configure le délai d’expiration du serveur, indiqué en millisecondes, pour la connexion hub du circuit.
• withKeepAliveInterval (valeur par défaut : 15 secondes) : intervalle, spécifié en millisecondes, auquel la connexion envoie des messages Keep-Alive.

Le délai d’expiration du serveur peut être augmenté et l’intervalle Keep-Alive peut rester le même. L’important est que si vous modifiez les valeurs. Assurez-vous que le délai d’expiration du serveur est au moins deux fois la valeur de l’intervalle Keep-Alive et que celle-ci correspond entre le serveur et le client. Pour plus d’informations, consultez la section Configurer les délais d’expiration SignalR et Keep-Alive sur le client.

Dans l’exemple de configuration de démarrage suivant (emplacement du script Blazor), une valeur personnalisée de 60 secondes est utilisée pour le délai d’expiration du serveur. L’intervalle Keep-Alive (withKeepAliveInterval) n’est pas défini et utilise sa valeur par défaut de 15 secondes.

Blazor Web App :

<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>

Lorsque vous créez une connexion hub dans un composant, définissez le délai d’expiration du serveur (WithServerTimeout, par défaut : 30 secondes) au niveau de HubConnectionBuilder. Définissez HandshakeTimeout (valeur par défaut : 15 secondes) au niveau de la HubConnection générée. Vérifiez que les délais d’expiration sont au moins deux fois l’intervalle Keep-Alive (WithKeepAliveInterval/KeepAliveInterval) et que la valeur Keep-Alive correspond entre le serveur et le client.

L’exemple suivant est basé sur le composant Index dans le didacticiel SignalR avec Blazor. Le délai d’expiration du serveur est augmenté à 60 secondes, et le délai d’établissement d’une liaison est augmenté à 30 secondes. L’intervalle Keep-Alive n’est pas défini et utilise sa valeur par défaut de 15 secondes.

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();
}

Spécifiez les paramètres suivants :

• serverTimeoutInMilliseconds (valeur par défaut : 30 secondes) : configure le délai d’expiration du serveur, indiqué en millisecondes, pour la connexion hub du circuit.
• keepAliveIntervalInMilliseconds (valeur par défaut : 15 secondes) : intervalle, spécifié en millisecondes, auquel la connexion envoie des messages Keep-Alive.

Le délai d’expiration du serveur peut être augmenté et l’intervalle Keep-Alive peut rester le même. L’important est que si vous modifiez les valeurs. Assurez-vous que le délai d’expiration du serveur est au moins deux fois la valeur de l’intervalle Keep-Alive et que celle-ci correspond entre le serveur et le client. Pour plus d’informations, consultez la section Configurer les délais d’expiration SignalR et Keep-Alive sur le client.

Dans l’exemple de configuration de démarrage suivant (emplacement du script Blazor), une valeur personnalisée de 60 secondes est utilisée pour le délai d’expiration du serveur. L’intervalle Keep-Alive (keepAliveIntervalInMilliseconds) n’est pas défini et utilise sa valeur par défaut de 15 secondes.

Dans Pages/_Host.cshtml :

<script src="_framework/blazor.server.js" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      let c = builder.build();
      c.serverTimeoutInMilliseconds = 60000;
      builder.build = () => {
        return c;
      };
    }
  });
</script>

Lors de la création d’une connexion hub dans un composant, définissez ServerTimeout (valeur par défaut : 30 secondes) et HandshakeTimeout (valeur par défaut : 15 secondes) sur le HubConnection généré. Vérifiez que les délais d’expiration sont au moins deux fois l’intervalle Keep-Alive. Vérifiez que l’intervalle Keep-Alive correspond entre le serveur et le client.

L’exemple suivant est basé sur le composant Index dans le didacticiel SignalR avec Blazor. Le délai ServerTimeout est augmenté à 60 secondes et le délai HandshakeTimeout est augmenté à 30 secondes. L’intervalle Keep-Alive (KeepAliveInterval) n’est pas défini et utilise sa valeur par défaut de 15 secondes.

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

    hubConnection.ServerTimeout = TimeSpan.FromSeconds(60);
    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(30);

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

    await hubConnection.StartAsync();
}

Déconnecter le circuit Blazor du client

Un circuit Blazor est déconnecté lorsque l’événement de page unload est déclenché. Pour déconnecter le circuit pour d’autres scénarios sur le client, appelez Blazor.disconnect dans le gestionnaire d’événements approprié. Dans l’exemple suivant, le circuit est déconnecté lorsque la page est masquée (événement pagehide) :

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

Pour plus d’informations sur le démarrage de Blazor, consultez Démarrage d’ASP.NET Core Blazor.

Dans le fichier Program :

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

Dans Startup.ConfigureServices de Startup.cs :

services.AddSingleton<CircuitHandler, TrackingCircuitHandler>();

Fermeture des circuits quand il ne reste plus de composants de serveur interactif

Les composants de serveur interactif gèrent les événements de l’interface utilisateur web en utilisant une connexion en temps réel avec le navigateur, appelée un circuit. Un circuit et son état associé sont créés quand un composant de serveur interactif racine est rendu. Le circuit est fermé quand il ne reste plus de composants de serveur interactif sur la page, ce qui libère des ressources du serveur.

IHttpContextAccessor doit être évité avec le rendu interactif, car il n’existe pas de HttpContext valide disponible.

IHttpContextAccessor peut être utilisé pour les composants rendus statiquement sur le serveur. Toutefois, nous vous recommandons de l’éviter si possible.

HttpContext peut être utilisé comme paramètre en cascade uniquement dans les composants racines rendus statiquement pour les tâches générales, telles que l’inspection et la modification d’en-têtes ou d’autres propriétés dans le composant App (Components/App.razor). La valeur est toujours null pour le rendu interactif.

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

Pour les scénarios où HttpContext est requis dans les composants interactifs, nous vous recommandons de transmettre les données via l’état du composant persistant à partir du serveur. Pour plus d’informations, consultez Autres scénarios de sécurité ASP.NET Core Blazor côté serveur.

N’utilisez pas IHttpContextAccessor/HttpContext directement ou indirectement dans les composants Razor des applications Blazor côté serveur. Les applications Blazor s’exécutent en dehors du contexte de pipeline ASP.NET Core. Le HttpContext n’est pas garanti d’être disponible dans le IHttpContextAccessor, et HttpContext n’est pas garanti de conserver le contexte qui a démarré l’application Blazor.

L’approche recommandée pour passer l’état de la requête à l’application Blazor consiste à utiliser les paramètres de composant racine pendant le rendu initial de l’application. L’application peut également copier les données dans un service délimité dans l’événement de cycle de vie d’initialisation du composant racine pour une utilisation dans l’application. Pour plus d’informations, consultez Autres scénarios de sécurité ASP.NET Core Blazor côté serveur.

Un aspect essentiel de la sécurité de Blazor côté serveur est que l’utilisateur attaché à un circuit donné peut être mis à jour à un moment donné après l’établissement du circuit Blazor, mais que le IHttpContextAccessor n’est pas mis à jour. Pour plus d’informations sur la résolution de cette situation avec des services personnalisés, consultez Autres scénarios de sécurité ASP.NET Core Blazor côté serveur.