Prerendere componenti ASP.NET Core Razor

Questo articolo illustra gli Razor scenari di pre-gestione dei componenti per i componenti sottoposti a rendering del server in Blazor Web Apps.

Il prerendering è il processo di rendering iniziale del contenuto della pagina nel server senza abilitare i gestori eventi per i controlli di cui è stato eseguito il rendering. Il server restituisce l'interfaccia utente HTML della pagina appena possibile in risposta alla richiesta iniziale, che rende l'app più reattiva agli utenti. Il prerendering può anche migliorare l'ottimizzazione del motore di ricerca (SEO) eseguendo il rendering del contenuto per la risposta HTTP iniziale usata dai motori di ricerca per calcolare la classificazione delle pagine.

Mantenere lo stato prerenderato

Senza rendere persistente lo stato prerenderato, lo stato usato durante il prerendering viene perso e deve essere ricreato quando l'app viene completamente caricata. Se uno stato viene creato in modo asincrono, l'interfaccia utente può sfarfallio perché l'interfaccia utente prerisorsa viene sostituita quando il componente viene rerendered.

Si consideri il componente contatore seguente PrerenderedCounter1 . Il componente imposta un valore iniziale del contatore casuale durante il prerendering nel OnInitialized metodo del ciclo di vita. Dopo aver stabilito la SignalR connessione al client, il rerender del componente e il valore del conteggio iniziale viene sostituito quando OnInitialized viene eseguito una seconda volta.

PrerenderedCounter1.razor:

@page "/prerendered-counter-1"
@rendermode @(new InteractiveServerRenderMode(prerender: true))
@inject ILogger<PrerenderedCounter1> Logger

<PageTitle>Prerendered Counter 1</PageTitle>

<h1>Prerendered Counter 1</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount;

    protected override void OnInitialized()
    {
        currentCount = Random.Shared.Next(100);
        Logger.LogInformation("currentCount set to {Count}", currentCount);
    }

    private void IncrementCount() => currentCount++;
}

Eseguire l'app ed esaminare la registrazione dal componente. Di seguito è riportato un output di esempio.

info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 41
info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 92

Il primo conteggio registrato si verifica durante il prerendering. Il conteggio viene nuovamente impostato dopo la pre-gestione quando il componente viene riabilitato. C'è anche uno sfarfallio nell'interfaccia utente quando il conteggio viene aggiornato da 41 a 92.

Per mantenere il valore iniziale del contatore durante il prerendering, Blazor supporta lo stato persistente in una pagina prerenderata usando il PersistentComponentState servizio (e per i componenti incorporati in pagine o visualizzazioni di Razor pagine o app MVC, l'helper Persist Component State Tag helper).

Per mantenere lo stato prerenderato, decidere quale stato rendere persistente usando il PersistentComponentState servizio. PersistentComponentState.RegisterOnPersisting registra un callback per rendere persistente lo stato del componente prima che l'app venga sospesa. Lo stato viene recuperato quando l'app riprende.

L'esempio seguente illustra il modello generale:

• Il {TYPE} segnaposto rappresenta il tipo di dati da mantenere.
• Il {TOKEN} segnaposto è una stringa di identificatore di stato. Prendere in considerazione l'uso nameof({VARIABLE})di , dove il {VARIABLE} segnaposto è il nome della variabile che contiene lo stato. L'uso nameof() di per l'identificatore di stato evita l'uso di una stringa tra virgolette.

@implements IDisposable
@inject PersistentComponentState ApplicationState

...

@code {
    private {TYPE} data;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistData);

        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("{TOKEN}", data);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Nell'esempio seguente del componente contatore viene mantenuto lo stato del contatore durante la prerendering e viene recuperato lo stato per inizializzare il componente.

PrerenderedCounter2.razor:

@page "/prerendered-counter-2"
@implements IDisposable
@inject ILogger<PrerenderedCounter2> Logger
@inject PersistentComponentState ApplicationState

<PageTitle>Prerendered Counter 2</PageTitle>

<h1>Prerendered Counter 2</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override void OnInitialized()
    {
        persistingSubscription =
            ApplicationState.RegisterOnPersisting(PersistCount);

        if (!ApplicationState.TryTakeFromJson<int>(
            nameof(currentCount), out var restoredCount))
        {
            currentCount = Random.Shared.Next(100);
            Logger.LogInformation("currentCount set to {Count}", currentCount);
        }
        else
        {
            currentCount = restoredCount!;
            Logger.LogInformation("currentCount restored to {Count}", currentCount);
        }
    }

    private Task PersistCount()
    {
        ApplicationState.PersistAsJson(nameof(currentCount), currentCount);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose() => persistingSubscription.Dispose();

    private void IncrementCount() => currentCount++;
}

Quando il componente viene eseguito, currentCount viene impostato una sola volta durante la pre-esecuzione. Il valore viene ripristinato quando il componente viene sottoposto a rerendering. Di seguito è riportato un output di esempio.

info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount restored to 96

Inizializzando i componenti con lo stesso stato usato durante la pre-esecuzione, tutti i passaggi di inizializzazione costosi vengono eseguiti una sola volta. L'interfaccia utente sottoposta a rendering corrisponde anche all'interfaccia utente prerisorsa, quindi non si verifica alcun sfarfallio nel browser.

Lo stato prerenderato persistente viene trasferito al client, in cui viene usato per ripristinare lo stato del componente. Durante il rendering lato client (CSR, InteractiveWebAssembly), i dati vengono esposti al browser e non devono contenere informazioni riservate e private. Durante il rendering lato server interattivo (SSR interattivo, InteractiveServer), ASP.NET Protezione dati di base garantisce che i dati vengano trasferiti in modo sicuro. La InteractiveAuto modalità di rendering combina l'interattività WebAssembly e Server, quindi è necessario considerare l'esposizione dei dati al browser, come nel caso csr.

Componenti incorporati in pagine e visualizzazioni (Razor Pages/MVC)

Per i componenti incorporati in una pagina o in una visualizzazione di un'app Razor Pages o MVC, devi aggiungere l'helperTag Persist Component State Tag con il <persist-component-state /> tag HTML all'interno del tag di chiusura </body> del layout dell'app. Questa operazione è necessaria solo per Razor le app Pages e MVC. Per altre informazioni, vedere Persist Component State Tag Helper in ASP.NET Core.For more information, see Persist Component State Tag Helper in ASP.NET Core.

Pages/Shared/_Layout.cshtml:

<body>
    ...

    <persist-component-state />
</body>

Routing interattivo e prerendering

Quando il componente Routes non definisce una modalità di rendering, l'app usa interattività e navigazione per pagina/componente. Usando la navigazione per pagina/componente, la navigazione interna† viene gestita dall'instradamento avanzato dopo che l'app diventa interattiva. †Interno in questo contesto significa che l'URL di destinazione dell'evento di navigazione è un endpoint Blazor all'interno dell'app.

Il servizio PersistentComponentState funziona solo sul caricamento della pagina iniziale e non sugli eventi di spostamento di pagina avanzati interni.

Se l'app esegue uno spostamento completo (non avanzato) a una pagina che usa lo stato del componente persistente, lo stato persistente viene reso disponibile per l'uso dell'app quando diventa interattivo.

Se è già stato stabilito un circuito interattivo e viene eseguita una navigazione avanzata in una pagina che utilizza lo stato del componente persistente, lo stato non viene reso disponibile nel circuito esistente per il componente da usare. Non c'è pre-rendering per la richiesta di pagina interna e il servizio PersistentComponentState non è a conoscenza del fatto che si è verificata una navigazione migliorata. Non esiste alcun meccanismo per distribuire gli aggiornamenti dello stato ai componenti già in esecuzione in un circuito esistente. Il motivo è che Blazor supporta solo il passaggio dello stato dal server al client al momento dell'inizializzazione del runtime, non dopo l'avvio del runtime.

Ulteriori operazioni sul framework di Blazor per risolvere questo scenario sono in considerazione per .NET 10 (novembre 2025). Per ulteriori informazioni e discussioni della community sulle soluzioni alternative non supportate‡, consultare il supporto dello stato costante del componente attraverso navigazioni pagine avanzate (dotnet/aspnetcore #51584). *Le soluzioni alternative non supportate non sono approvate da Microsoft per l'uso nelle app Blazor. Usare pacchetti di terze parti, approcci e codice a proprio rischio.

La disabilitazione della navigazione avanzata, che riduce le prestazioni, ma evita anche il problema di caricamento dello stato con PersistentComponentState per le richieste di pagine interne, è descritta in ASP.NET core Blazor routing e navigazione.

Indicazioni di pre-ordinamento

Le indicazioni preliminari sono organizzate nella documentazione in base all'argomento Blazor . I collegamenti seguenti illustrano tutte le linee guida di pre-ordinamento in tutta la documentazione impostata dall'oggetto:

• Nozioni fondamentali

  • OnNavigateAsync viene eseguito due volte quando si esegue la pre-esecuzione: gestire gli eventi di spostamento asincroni con OnNavigateAsync
  • Avvio: Controllare le intestazioni nel codice C#
  • Gestire gli errori: Prerendering
  • SignalR: dimensioni dello stato prerisorse e SignalR limite di dimensioni dei messaggi

• Modalità di rendering: Prerendering

• Componenti

  • Controllare il <head> contenuto durante la pre-distribuzione
  • Razor soggetti del ciclo di vita dei componenti che riguardano il prerendering
    • Inizializzazione dei componenti (OnInitialized{Async})
    • Dopo il rendering del componente (OnAfterRender{Async})
    • Riconnessione con stato dopo il prerendering
    • Prerendering con interoperabilità JavaScript: questa sezione viene visualizzata anche nei due JS articoli di interoperabilità su come chiamare JavaScript da .NET e chiamare .NET da JavaScript.
    • Gestire azioni asincrone incomplete durante il rendering: linee guida per il rendering ritardato a causa di attività del ciclo di vita a esecuzione prolungata durante la pre-esecuzione sul server.
  • App di esempio del componente QuickGrid: l'app QuickGrid per l'esempio Blazor è ospitata in GitHub Pages. Il sito viene caricato rapidamente grazie al prerendering statico usando il progettoBlazorWasmPrerendering.Build community.
  • Prerendering durante l'integrazione di componenti nelle Razor app Pages e MVC

• Autenticazione e autorizzazione

  • Mitigazione delle minacce lato server: scripting tra siti (XSS)
  • Visualizzazione di contenuto non autorizzato sul lato server durante la pre-gestione con un oggetto personalizzato AuthenticationStateProvider
  • Blazor WebAssembly autenticazione dei componenti di cui è stato eseguito il rendering con prerendering

• Gestione dello stato: gestire la prerendering: oltre alla sezione Gestione prerendering , diverse delle altre sezioni dell'articolo includono osservazioni sulla prerendering.