Pokyny pro ASP.NET Core BlazorSignalR

Služba Azure SignalR s stavovým opětovným připojením

Stavové opětovné připojení (WithStatefulReconnect) bylo vydáno s .NET 8, ale v současné době se nepodporuje pro službu Azure SignalR . Další informace najdete v tématu Podpora stavových opětovného připojení? (Azure/azure-signalr č. 1878).

Komprese protokolu WebSocket pro komponenty interaktivního serveru

Ve výchozím nastavení jsou součásti interaktivního serveru:

• Povolte kompresi připojení WebSocket. ConfigureWebsocketOptions řídí kompresi protokolu WebSocket.

• Přijměte direktivu frame-ancestors CSP (Content Security Policy), která 'self'povoluje pouze vložení aplikace do <iframe> zdroje, ze kterého se aplikace obsluhuje při povolení komprese nebo při poskytnutí konfigurace kontextu WebSocket. ContentSecurityFrameAncestorPolicy řídí CSP frame-ancestors .

Poskytovatel frame-ancestors CSP je možné odebrat ručně nastavením hodnoty ConfigureWebSocketOptions na nullhodnotu , protože můžete chtít poskytovatele CSP nakonfigurovat centralizovaným způsobem. frame-ancestors Když je CSP spravován centralizovaným způsobem, je nutné při každém vykreslení prvního dokumentu použít zásadu. Nedoporučujeme úplně odebírat zásady, protože by mohla být aplikace zranitelná vůči útokům.

Příklady použití:

Zakažte kompresi nastavením ConfigureWebSocketOptions , což snižuje ohrožení zabezpečení aplikace na útok, ale může vést ke nullsnížení výkonu:

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

Pokud je povolená komprese, nakonfigurujte přísnější frame-ancestors CSP s hodnotou 'none' (vyžaduje se jednoduché uvozovky), která umožňuje kompresi Protokolu WebSocket, ale brání prohlížečům v vložení aplikace do libovolné <iframe>:

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

Pokud je povolena komprese, odeberte frame-ancestors CSP nastavením ContentSecurityFrameAncestorsPolicy na null. Tento scénář se doporučuje jenom pro aplikace, které nastavují CSP centralizovaným způsobem:

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

Vliv na zabezpečení najdete v doprovodných materiálech ke zmírnění hrozeb pro interaktivní vykreslování na straně serveru ASP.NET CoreBlazor. Další informace o direktivě frame-ancestors najdete v tématu CSP: frame-ancestors (Dokumentace k MDN).

Zakázání komprese odpovědí pro Opětovné načítání za provozu

Při použití Opětovné načítání za provozu zakažte middleware pro kompresi odpovědí v Development prostředí. Bez ohledu na to, jestli se používá výchozí kód ze šablony projektu, vždy volejte UseResponseCompression nejprve v kanálu zpracování požadavků.

V souboru Program:

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

Pokud je nakonfigurované předrenderování, před navázáním připojení klienta k serveru dojde k předběžnému vytvoření. Další informace naleznete v tématu Prerender ASP.NET Základní Razor komponenty.

Pokud je nakonfigurované předrenderování, před navázáním připojení klienta k serveru dojde k předběžnému vytvoření. Další informace najdete v následujících článcích:

• Pomocná rutina značek komponent v ASP.NET Core
• Předběžné vykreslování a integrace komponent ASP.NET Core Razor

Přečtěte si nebo nastavte možnosti v Program souboru s delegátem možností na AddInteractiveServerComponents. Zástupný {OPTION} symbol představuje možnost a {VALUE} zástupný symbol je hodnota.

V souboru Program:

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

Přečtěte si nebo nastavte možnosti v Program souboru s delegátem možností na AddServerSideBlazor. Zástupný {OPTION} symbol představuje možnost a {VALUE} zástupný symbol je hodnota.

V souboru Program:

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

Přečtěte si nebo nastavte možnosti Startup.ConfigureServices pomocí delegáta možností na AddServerSideBlazor. Zástupný {OPTION} symbol představuje možnost a {VALUE} zástupný symbol je hodnota.

In Startup.ConfigureServices of Startup.cs:

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

V souboru Program:

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

V souboru Program:

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

In Startup.ConfigureServices of Startup.cs:

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

app.MapBlazorHub Volání umístěte za voláním app.MapRazorComponents do souboru aplikaceProgram:

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

Konfigurace centra používaného AddInteractiveServerRenderMode s MapBlazorHub chybou s chybou AmbiguousMatchException:

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

Pokud chcete tento problém vyřešit u aplikací, které cílí na .NET 8, dejte vlastní nakonfigurované Blazor rozbočovači vyšší prioritu WithOrder pomocí metody:

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

Další informace naleznete v následujících zdrojích:

• Konfigurace MapBlazorHubu v NET8 vyvolá žádost spárovanou s několika výjimkami koncových bodů (dotnet/aspnetcore #51698).
• Pokusy o mapování více blazor vstupních bodů pomocí MapBlazorHubu způsobí nejednoznačné chyby trasy. To fungovalo s net7 (dotnet/aspnetcore č. 52156)

Do souboru aplikace Program zadejte možnostiapp.MapBlazorHub:

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

Zadejte možnosti app.MapBlazorHub konfigurace směrování koncového bodu:

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

Jedním z přístupů je zvýšení limitu nastavením MaximumReceiveMessageSize v Program souboru. Následující příklad nastaví maximální velikost příjmu zprávy na 64 kB:

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

Zvýšení limitu SignalR velikosti příchozích zpráv je nákladné vyžadovat více prostředků serveru a zvyšuje riziko útoků DoS (DoS). Navíc čtení velkého množství obsahu do paměti jako řetězců nebo bajtových polí může také vést k přidělení, která pracují špatně s uvolňováním paměti, což vede k dalším sankcím za výkon.

Lepší možností pro čtení velkých datových částí je odeslat obsah v menších blocích a zpracovat datovou část jako .Stream To se dá použít při čtení velkých datových částí JSON zprostředkovatele komunikace JavaScriptuJS nebo při JS dostupnosti dat zprostředkovatele komunikace jako nezpracovaných bajtů. Příklad, který ukazuje odesílání velkých binárních datových částí v serverových aplikacích, které používají techniky podobné InputFile komponentě, najdete v ukázkové aplikaci Binary Submit a BlazorInputLargeTextArea v ukázce komponenty.

Formuláře, které zpracovávají velké datové části, SignalR můžou také přímo používat komunikaci streamování JS . Další informace naleznete v tématu Volání metod .NET z funkcí JavaScriptu v ASP.NET Core Blazor. Příklad formulářů, který streamuje <textarea> data na server, najdete v tématu Řešení potíží s formuláři ASP.NET CoreBlazor.

Jedním z přístupů je zvýšení limitu nastavením MaximumReceiveMessageSize v Program souboru. Následující příklad nastaví maximální velikost příjmu zprávy na 64 kB:

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

Zvýšení limitu SignalR velikosti příchozích zpráv je nákladné vyžadovat více prostředků serveru a zvyšuje riziko útoků DoS (DoS). Navíc čtení velkého množství obsahu do paměti jako řetězců nebo bajtových polí může také vést k přidělení, která pracují špatně s uvolňováním paměti, což vede k dalším sankcím za výkon.

Lepší možností pro čtení velkých datových částí je odeslat obsah v menších blocích a zpracovat datovou část jako .Stream To se dá použít při čtení velkých datových částí JSON zprostředkovatele komunikace JavaScriptuJS nebo při JS dostupnosti dat zprostředkovatele komunikace jako nezpracovaných bajtů. Příklad, který ukazuje odesílání velkých binárních datových částí, které Blazor Server používají techniky podobné InputFile komponentě, najdete v ukázkové aplikaci Binary Submit aInputLargeTextArea Blazorv ukázce komponenty.

Formuláře, které zpracovávají velké datové části, SignalR můžou také přímo používat komunikaci streamování JS . Další informace naleznete v tématu Volání metod .NET z funkcí JavaScriptu v ASP.NET Core Blazor. Příklad formulářů, který streamuje <textarea> data v aplikaci, najdete v Blazor Server tématu Řešení potíží s formuláři ASP.NET CoreBlazor.

Zvýšení limitu nastavením MaximumReceiveMessageSize v Startup.ConfigureServices:

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

Zvýšení limitu SignalR velikosti příchozích zpráv je nákladné vyžadovat více prostředků serveru a zvyšuje riziko útoků DoS (DoS). Navíc čtení velkého množství obsahu do paměti jako řetězců nebo bajtových polí může také vést k přidělení, která pracují špatně s uvolňováním paměti, což vede k dalším sankcím za výkon.

• Využijte nativní podporu spolupráce streamování JS k přenosu dat větších než SignalR limitu velikosti příchozích zpráv:
  • Volání funkcí JavaScriptu z metod .NET v ASP.NET Core Blazor
  • Volání metod .NET z funkcí JavaScriptu v ASP.NET Core Blazor
  • Příklad datové části formuláře: Řešení potíží s formuláři ASP.NET Core Blazor
• Obecné tipy:
  • Nepřidělujte velké objekty v JS kódu jazyka C#.
  • Volné spotřebované paměti po dokončení nebo zrušení procesu
  • Vynucujte následující další požadavky pro účely zabezpečení:
    • Deklarujte maximální velikost souboru nebo dat, které lze předat.
    • Deklarujte minimální rychlost nahrávání z klienta na server.
  • Po přijetí dat serverem mohou být tato data následující:
    • Dočasně uložené v vyrovnávací paměti, dokud se neshromáždí všechny segmenty.
    • Spotřebováno okamžitě. Data se například dají okamžitě uložit do databáze nebo zapisovat na disk při přijetí jednotlivých segmentů.

• Rozdělte data na menší části a posílejte datové segmenty postupně, dokud server neobdrží všechna data.
• Nepřidělujte velké objekty v JS kódu jazyka C#.
• Při odesílání nebo přijímání dat neblokujte hlavní vlákno uživatelského rozhraní po dlouhou dobu.
• Volné spotřebované paměti po dokončení nebo zrušení procesu
• Vynucujte následující další požadavky pro účely zabezpečení:
  • Deklarujte maximální velikost souboru nebo dat, které lze předat.
  • Deklarujte minimální rychlost nahrávání z klienta na server.
• Po přijetí dat serverem mohou být tato data následující:
  • Dočasně uložené v vyrovnávací paměti, dokud se neshromáždí všechny segmenty.
  • Spotřebováno okamžitě. Data se například dají okamžitě uložit do databáze nebo zapisovat na disk při přijetí jednotlivých segmentů.

Chcete-li přizpůsobit uživatelské rozhraní, definujte jeden prvek pomocí znaku id .components-reconnect-modal Následující příklad umístí prvek do App komponenty.

App.razor:

Chcete-li přizpůsobit uživatelské rozhraní, definujte jeden prvek pomocí znaku id .components-reconnect-modal Následující příklad umístí prvek na stránku hostitele.

Pages/_Host.cshtml:

Chcete-li přizpůsobit uživatelské rozhraní, definujte jeden prvek pomocí znaku id .components-reconnect-modal Následující příklad umístí prvek na stránku rozložení.

Pages/_Layout.cshtml:

Chcete-li přizpůsobit uživatelské rozhraní, definujte jeden prvek pomocí znaku id .components-reconnect-modal Následující příklad umístí prvek na stránku hostitele.

Pages/_Host.cshtml:

wwwroot/app.css:

wwwroot/css/site.css:

Přizpůsobte zpoždění před zobrazením uživatelského rozhraní pro opětovné připojení nastavením transition-delay vlastnosti v šabloně stylů CSS webu pro modální prvek. Následující příklad nastaví zpoždění přechodu z 500 ms (výchozí) na 1 000 ms (1 sekunda).

wwwroot/app.css:

wwwroot/css/site.css:

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

Chcete-li zobrazit aktuální pokus o opětovné připojení, definujte prvek s hodnotou .id components-reconnect-current-attempt Chcete-li zobrazit maximální počet opakovaných pokusů o opětovné připojení, definujte prvek s znakem id components-reconnect-max-retries. Následující příklad umístí tyto prvky do modálního prvku pokusu o opětovné připojení za předchozím příkladem.

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

Když se zobrazí modální modál vlastního opětovného připojení, vykreslí obsah podobný následujícímu na základě předchozího kódu:

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

Ve výchozím nastavení jsou komponenty předváděné na serveru před navázáním připojení klienta k serveru. Další informace naleznete v tématu Prerender ASP.NET Základní Razor komponenty.

Ve výchozím nastavení jsou komponenty předváděné na serveru před navázáním připojení klienta k serveru. Další informace naleznete v nápovědě značky komponenty v ASP.NET Core.

Monitorování aktivity okruhu na straně serveru

Monitorování příchozí aktivity okruhu CreateInboundActivityHandler pomocí metody on CircuitHandler. Příchozí aktivita okruhu je jakákoli aktivita odesílaná z prohlížeče na server, například události uživatelského rozhraní nebo JavaScript-to-.NET volání zprostředkovatele komunikace.

Pomocí obslužné rutiny aktivity okruhu můžete například zjistit, jestli je klient nečinný, a protokolovat ID jeho okruhu (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;
    }
}

Zaregistrujte službu v Program souboru. Následující příklad nakonfiguruje výchozí časový limit nečinnosti pět minut až pět sekund, aby bylo možné otestovat předchozí IdleCircuitHandler implementaci:

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

Obslužné rutiny aktivit okruhu také poskytují přístup k vymezeným Blazor službám z jinýchBlazor oborů injektáže závislostí (DI). Další informace a příklady najdete tady:

• injektáž závislostí jádra Blazor ASP.NET
• Další scénáře zabezpečení na straně serveru ASP.NET Core Blazor

Nakonfigurujte ruční spuštění okruhu Blazor aplikace SignalR v App.razor souboru Blazor Web App:

Nakonfigurujte ruční spuštění okruhu Blazor aplikace SignalR v Pages/_Host.cshtml souboru (Blazor Server):

Nakonfigurujte ruční spuštění okruhu Blazor aplikace SignalR v Pages/_Layout.cshtml souboru (Blazor Server):

Nakonfigurujte ruční spuštění okruhu Blazor aplikace SignalR v Pages/_Host.cshtml souboru (Blazor Server):

Nakonfigurujte pro klienta následující hodnoty:

• withServerTimeout: Nakonfiguruje časový limit serveru v milisekundách. Pokud tento časový limit uplynou bez příjmu zpráv ze serveru, připojení se ukončí s chybou. Výchozí hodnota časového limitu je 30 sekund. Časový limit serveru by měl být alespoň dvojnásobný, než je hodnota přiřazená intervalu keep-Alive (withKeepAliveInterval).
• withKeepAliveInterval: Nakonfiguruje interval Keep-Alive v milisekundách (výchozí interval, ve kterém se má server otestovat příkazem ping). Toto nastavení umožňuje serveru rozpoznat pevné odpojení, například když klient odpojí počítač od sítě. Příkaz ping se vyskytuje nejčastěji jako příkaz ping na serveru. Pokud server odešle příkaz ping každých pět sekund, přiřazování hodnoty nižší než 5000 (5 sekund) odešle příkaz ping každých pět sekund. Výchozí hodnota je 15 sekund. Interval Keep-Alive by měl být menší nebo roven polovině hodnoty přiřazené k vypršení časového limitu serveru (withServerTimeout).

Následující příklad souboru App.razor (Blazor Web App) ukazuje přiřazení výchozích hodnot.

Blazor Web App:

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

Následující příklad souboru Pages/_Host.cshtml (Blazor Servervšechny verze kromě ASP.NET Core v .NET 6) nebo Pages/_Layout.cshtml soubor (Blazor ServerASP.NET Core v .NET 6).

Blazor Server:

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

V předchozím příkladu {BLAZOR SCRIPT} je Blazor zástupný symbol cesta ke skriptu a název souboru. Umístění skriptu a cesty, které se má použít, najdete v tématu ASP.NET Struktura projektu CoreBlazor.

Při vytváření připojení rozbočovače v komponentě nastavte ServerTimeout (výchozí: 30 sekund) a KeepAliveInterval (výchozí: 15 sekund) na kartě HubConnectionBuilder. HandshakeTimeout Nastavte (výchozí: 15 sekund) na sestavené HubConnection. Následující příklad ukazuje přiřazení výchozích hodnot:

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

Nakonfigurujte pro klienta následující hodnoty:

• serverTimeoutInMilliseconds: Časový limit serveru v milisekundách. Pokud tento časový limit uplynou bez příjmu zpráv ze serveru, připojení se ukončí s chybou. Výchozí hodnota časového limitu je 30 sekund. Časový limit serveru by měl být alespoň dvojnásobný, než je hodnota přiřazená intervalu keep-Alive (keepAliveIntervalInMilliseconds).
• keepAliveIntervalInMilliseconds: Výchozí interval, ve kterém se má server otestovat příkazem ping. Toto nastavení umožňuje serveru rozpoznat pevné odpojení, například když klient odpojí počítač od sítě. Příkaz ping se vyskytuje nejčastěji jako příkaz ping na serveru. Pokud server odešle příkaz ping každých pět sekund, přiřazování hodnoty nižší než 5000 (5 sekund) odešle příkaz ping každých pět sekund. Výchozí hodnota je 15 sekund. Interval Keep-Alive by měl být menší nebo roven polovině hodnoty přiřazené k vypršení časového limitu serveru (serverTimeoutInMilliseconds).

Následující příklad souboru Pages/_Host.cshtml (Blazor Servervšechny verze kromě ASP.NET Core v .NET 6) nebo Pages/_Layout.cshtml soubor (Blazor ServerASP.NET Core v .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>

V předchozím příkladu {BLAZOR SCRIPT} je Blazor zástupný symbol cesta ke skriptu a název souboru. Umístění skriptu a cesty, které se má použít, najdete v tématu ASP.NET Struktura projektu CoreBlazor.

Při vytváření připojení rozbočovače v komponentě nastavte ServerTimeout (výchozí: 30 sekund), HandshakeTimeout (výchozí: 15 sekund) a KeepAliveInterval (výchozí: 15 sekund) na sestavené HubConnection. Následující příklad ukazuje přiřazení výchozích hodnot:

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:

Automatická aktualizace stránky při selhání opětovného připojení na straně serveru

Výchozí chování opětovného připojení vyžaduje, aby uživatel po selhání opětovného připojení ručně aktualizoval stránku. K automatické aktualizaci stránky se ale dá použít vlastní obslužná rutina opětovného připojení:

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>

V předchozím příkladu {BLAZOR SCRIPT} je Blazor zástupný symbol cesta ke skriptu a název souboru. Umístění skriptu a cesty, které se má použít, najdete v tématu ASP.NET Struktura projektu CoreBlazor.

Vytvořte následující wwwroot/boot.js soubor.

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

Další informace o spuštění architektury Blazor najdete v tématu Spuštění 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:

Když se uživatel vrátí do aplikace s odpojeným okruhem, pokusí se o opětovné připojení okamžitě, a nečeká na dobu trvání dalšího intervalu opětovného připojení. Toto chování se snaží obnovit připojení co nejrychleji pro uživatele.

Výchozí časování opětovného připojení používá vypočítanou strategii zpětného odpojení. K prvnímu několika opakovaným pokusům o opětovné připojení dochází v rychlém sledu před uvedením vypočítaných zpoždění mezi pokusy. Výchozí logika pro výpočet intervalu opakování je podrobnosti implementace, která se může bez předchozího upozornění změnit, ale můžete najít výchozí logiku, kterou Blazor architektura používá ve computeDefaultRetryInterval funkci (referenční zdroj).

Přizpůsobte chování intervalu opakování zadáním funkce pro výpočet intervalu opakování. V následujícím exponenciálním příkladu opakování se počet předchozích pokusů o opětovné připojení vynásobí číslem 1 000 ms pro výpočet intervalu opakování. Pokud je počet předchozích pokusů o opětovné připojení (previousAttempts) větší než maximální limit opakování (maxRetries), null je přiřazen k intervalu opakování (retryIntervalMilliseconds), aby se zastavily další pokusy o opětovné připojení:

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

Alternativou je určit přesnou sekvenci intervalů opakování. Po posledním zadaném intervalu opakování se opakování zastaví, protože retryIntervalMilliseconds funkce vrátí undefined:

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

Ovládací prvek, když se zobrazí uživatelské rozhraní pro opětovné připojení

Řízení, kdy se zobrazí uživatelské rozhraní pro opětovné připojení, může být užitečné v následujících situacích:

• Nasazená aplikace často zobrazuje uživatelské rozhraní pro opětovné připojení kvůli vypršení časového limitu příkazu ping způsobeným latencí interní sítě nebo internetu a chcete zpoždění zvýšit.
• Aplikace by měla nahlásit uživatelům, že připojení se dříve ukončilo, a chcete zkrátit zpoždění.

Načasování vzhledu uživatelského rozhraní pro opětovné připojení je ovlivněno úpravou intervalu zachování a časových limitů v klientovi. Uživatelské rozhraní pro opětovné připojení se zobrazí po dosažení časového limitu serveru v klientovi (withServerTimeoutoddíl Konfigurace klienta). Změna hodnoty vyžaduje změny jiných nastavení funkce Keep-Alive, timeout a handshake popsaných withServerTimeout v následujících doprovodných materiálech.

Obecné doporučení pro následující pokyny:

• Interval uchování by se měl shodovat mezi konfigurací klienta a serveru.
• Časové limity by měly být alespoň dvojnásobné, než je hodnota přiřazená intervalu Keep-Alive.

Konfigurace serveru

Nastavte následující:

• ClientTimeoutInterval (výchozí hodnota: 30 sekund): Klienti časového intervalu musí odeslat zprávu předtím, než server připojení zavře.
• HandshakeTimeout (výchozí hodnota: 15 sekund): Interval používaný serverem k vypršení časového limitu příchozích požadavků handshake klienty.
• KeepAliveInterval (výchozí hodnota: 15 sekund): Interval používaný serverem k odesílání aktivních příkazů ping připojeným klientům. Všimněte si, že v klientovi je také nastavení intervalu Keep-Alive, které by mělo odpovídat hodnotě serveru.

HandshakeTimeout A ClientTimeoutInterval může být zvýšen a KeepAliveInterval může zůstat stejný. Důležité je, že pokud změníte hodnoty, ujistěte se, že časové limity jsou alespoň dvojnásobné hodnoty intervalu Keep-Alive a že interval Keep-Alive odpovídá mezi serverem a klientem. Další informace najdete v části Konfigurace SignalR časových limitů a udržování naživu v části klienta .

V následujícím příkladu:

• Hodnota ClientTimeoutInterval se zvýší na 60 sekund (výchozí hodnota: 30 sekund).
• Hodnota HandshakeTimeout se zvýší na 30 sekund (výchozí hodnota: 15 sekund).
• Není KeepAliveInterval nastaven v kódu vývojáře a používá výchozí hodnotu 15 sekund. Snížení hodnoty intervalu Keep-Alive zvyšuje frekvenci příkazů ping pro komunikaci, což zvyšuje zatížení aplikace, serveru a sítě. Je třeba dbát na to, abyste se vyhnuli nízkému výkonu při snížení intervalu Udržování naživu.

Blazor Web App (.NET 8 nebo novější) v souboru projektu Program serveru:

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

Blazor ServerProgram v souboru:

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

Další informace najdete v části Možnosti obslužné rutiny okruhu na straně serveru.

Konfigurace klienta

Nastavte následující:

• withServerTimeout (výchozí hodnota: 30 sekund): Nakonfiguruje časový limit serveru zadaný v milisekundách pro připojení rozbočovače okruhu.
• withKeepAliveInterval (výchozí hodnota: 15 sekund): Interval zadaný v milisekundách, ve kterém připojení odesílá zprávy Keep-Alive.

Časový limit serveru je možné zvýšit a interval Keep-Alive může zůstat stejný. Důležité je, že pokud změníte hodnoty, ujistěte se, že časový limit serveru je alespoň dvojnásobná hodnota intervalu Keep-Alive a že hodnoty intervalu Keep-Alive odpovídají mezi serverem a klientem. Další informace najdete v části Konfigurace SignalR časových limitů a udržování naživu v části klienta .

V následujícím příkladu konfigurace spuštění (umístění Blazor skriptu) se pro vypršení časového limitu serveru použije vlastní hodnota 60 sekund. Interval Keep-Alive (withKeepAliveInterval) není nastavený a používá výchozí hodnotu 15 sekund.

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>

Při vytváření připojení rozbočovače v komponentě nastavte časový limit serveru (WithServerTimeoutvýchozí hodnota: 30 sekund) na kartě HubConnectionBuilder. HandshakeTimeout Nastavte (výchozí: 15 sekund) na sestavené HubConnection. Ověřte, že časové limity jsou alespoň dvakrát interval keep-alive (WithKeepAliveInterval/KeepAliveInterval) a že hodnota Keep-Alive odpovídá mezi serverem a klientem.

Následující příklad je založen na Index komponentěSignalR v kurzu.Blazor Časový limit serveru se zvýší na 60 sekund a časový limit handshake se zvýší na 30 sekund. Interval Keep-Alive není nastavený a používá výchozí hodnotu 15 sekund.

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

Nastavte následující:

• serverTimeoutInMilliseconds (výchozí hodnota: 30 sekund): Nakonfiguruje časový limit serveru zadaný v milisekundách pro připojení rozbočovače okruhu.
• keepAliveIntervalInMilliseconds (výchozí hodnota: 15 sekund): Interval zadaný v milisekundách, ve kterém připojení odesílá zprávy Keep-Alive.

Časový limit serveru je možné zvýšit a interval Keep-Alive může zůstat stejný. Důležité je, že pokud změníte hodnoty, ujistěte se, že časový limit serveru je alespoň dvojnásobná hodnota intervalu Keep-Alive a že hodnoty intervalu Keep-Alive odpovídají mezi serverem a klientem. Další informace najdete v části Konfigurace SignalR časových limitů a udržování naživu v části klienta .

V následujícím příkladu konfigurace spuštění (umístění Blazor skriptu) se pro vypršení časového limitu serveru použije vlastní hodnota 60 sekund. Interval Keep-Alive (keepAliveIntervalInMilliseconds) není nastavený a používá výchozí hodnotu 15 sekund.

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

Při vytváření připojení rozbočovače v komponentě nastavte ServerTimeout (výchozí: 30 sekund) a HandshakeTimeout (výchozí: 15 sekund) na sestavené HubConnection. Ověřte, že časové limity jsou alespoň dvojité intervalu Keep-Alive. Ověřte, že interval udržování naživu odpovídá mezi serverem a klientem.

Následující příklad je založen na Index komponentěSignalR v kurzu.Blazor Zvýší se ServerTimeout na 60 sekund a HandshakeTimeout zvýší se na 30 sekund. Interval Keep-Alive (KeepAliveInterval) není nastavený a používá výchozí hodnotu 15 sekund.

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

Odpojení okruhu Blazor od klienta

Okruh Blazor se odpojí při unload aktivaci události stránky. Pokud chcete odpojit okruh pro jiné scénáře v klientovi, vyvolejte Blazor.disconnect ho v příslušné obslužné rutině události. V následujícím příkladu se okruh odpojí, když je stránka skrytá (pagehide událost):

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

Další informace o spuštění architektury Blazor najdete v tématu Spuštění ASP.NET Core Blazor.

V souboru Program:

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

In Startup.ConfigureServices of Startup.cs:

services.AddSingleton<CircuitHandler, TrackingCircuitHandler>();

Uzavření okruhů, pokud neexistují žádné zbývající součásti interaktivního serveru

Komponenty interaktivního serveru zpracovávají události webového uživatelského rozhraní pomocí připojení v reálném čase s prohlížečem označovaným jako okruh. Okruh a jeho přidružený stav se vytvoří, když se vykreslí kořenová součást Interactive Serveru. Okruh se zavře, pokud na stránce nejsou žádné zbývající součásti interaktivního serveru, které uvolní prostředky serveru.

IHttpContextAccessor musí se vyhnout interaktivnímu vykreslování, protože není k dispozici platný HttpContext .

IHttpContextAccessor lze použít pro součásti, které jsou staticky vykresleny na serveru. Pokud je to ale možné, doporučujeme ho vyhnout.

HttpContext lze použít jako kaskádový parametr pouze v staticky vykreslovaných kořenových komponentách pro obecné úlohy, jako je kontrola a úprava hlaviček nebo jiných vlastností v komponentě App (Components/App.razor). Hodnota je vždy null určená pro interaktivní vykreslování.

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

Pro scénáře, ve HttpContext kterých se vyžaduje v interaktivních komponentách, doporučujeme tok dat přes trvalý stav komponenty ze serveru. Další informace najdete v tématu Další scénáře zabezpečení na straně serveru ASP.NET CoreBlazor.

Nepoužívejte IHttpContextAccessor/HttpContext přímo ani nepřímo v Razor komponentách serverových Blazor aplikací. Blazor aplikace běží mimo kontext kanálu ASP.NET Core. Není HttpContext zaručeno, že bude k dispozici v rámci aplikace IHttpContextAccessora HttpContext není zaručeno, že bude obsahovat kontext, který aplikaci spustil Blazor .

Doporučený postup pro předávání stavu požadavku do Blazor aplikace je prostřednictvím parametrů kořenové komponenty během počátečního vykreslování aplikace. Případně může aplikace zkopírovat data do vymezené služby v události životního cyklu inicializace kořenové komponenty pro použití v celé aplikaci. Další informace najdete v tématu Další scénáře zabezpečení na straně serveru ASP.NET CoreBlazor.

Důležitým aspektem zabezpečení na straně Blazor serveru je, že se uživatel připojený k danému okruhu může v určitém okamžiku Blazor po navázání okruhu aktualizovat, ale IHttpContextAccessor neaktualizuje se. Další informace o řešení této situace s vlastními službami najdete v tématu Další scénáře zabezpečení na straně serveru ASP.NET CoreBlazor.