Condividi tramite

Prerendere componenti ASP.NET Core Razor

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Questo articolo illustra gli scenari di pre-rendering dei componenti per i componenti renderizzati dal server in Razors.

Il prerendering è il processo di rendering iniziale del contenuto della pagina sul server senza abilitare i gestori eventi per i controlli renderizzati. 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ò sfarfallare perché l'interfaccia utente prerenderizzata viene sostituita quando il componente viene rendirizzato nuovamente.

Si consideri il componente contatore seguente PrerenderedCounter1 . Il componente imposta un valore iniziale casuale del contatore durante il prerendering nel OnInitialized metodo del ciclo di vita. Dopo che è stata stabilita la connessione al client, il componente viene rerenderizzato e il conteggio iniziale viene sostituito quando SignalR 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 i log dal componente. Di seguito è riportato un output di esempio.

Nota

Se l'app adotta il routing interattivo e la pagina viene raggiunta tramite una navigazione avanzata interna , il prerendering non si verifica. Pertanto, è necessario eseguire un ricaricamento di pagina completo per il PrerenderedCounter1 componente per visualizzare l'output seguente. Per ulteriori informazioni, consultare la sezione Routing interattivo e prerendering.

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 il prerendering quando il componente viene nuovamente renderizzato. 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 consente la persistenza dello stato in una pagina prerenderata usando il servizio PersistentComponentState (e per i componenti incorporati nelle pagine o nelle visualizzazioni di pagine Razor o app MVC, l'Helper Tag Persistenza Stato del Componente).

Per mantenere lo stato prerenderato, usare l'attributo [SupplyParameterFromPersistentComponentState] per rendere persistente lo stato nelle proprietà. Le proprietà con questo attributo vengono memorizzate automaticamente usando il servizio PersistentComponentState durante il prerendering. Lo stato viene recuperato quando il componente esegue il rendering interattivo o viene creata un'istanza del servizio.

Per impostazione predefinita, le proprietà vengono serializzate usando il System.Text.Json serializzatore con le impostazioni predefinite. La serializzazione non è sicura per i trimmer e richiede la conservazione dei tipi utilizzati. Per altre informazioni, vedere Configurare Trimmer per ASP.NET Core Blazor.

Il componente contatore seguente mantiene lo stato del contatore durante il prerendering e recupera lo stato per inizializzare il componente:

  • L'attributo [SupplyParameterFromPersistentComponentState] viene applicato al CounterState tipo (State).
  • Lo stato del contatore viene assegnato quando si trova il null all'interno del OnInitialized, e viene ripristinato automaticamente quando il componente viene renderizzato in modo interattivo.

PrerenderedCounter2.razor:

@page "/prerendered-counter-2"
@inject ILogger<PrerenderedCounter2> Logger

<PageTitle>Prerendered Counter 2</PageTitle>

<h1>Prerendered Counter 2</h1>

<p role="status">Current count: @State?.CurrentCount</p>

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

@code {
    [SupplyParameterFromPersistentComponentState]
    public CounterState? State { get; set; }

    protected override void OnInitialized()
    {
        if (State is null)
        {
            State = new() { CurrentCount = Random.Shared.Next(100) };
            Logger.LogInformation("CurrentCount set to {Count}", 
                State.CurrentCount);
        }
        else
        {
            Logger.LogInformation("CurrentCount restored to {Count}", 
                State.CurrentCount);
        }
    }

    private void IncrementCount()
    {
        if (State is not null)
        {
            State.CurrentCount++;
        }
    }

    public class CounterState
    {
        public int CurrentCount { get; set; }
    }
}

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.

Nota

Se l'app adotta il routing interattivo e la pagina viene raggiunta tramite una navigazione avanzata interna , il prerendering non si verifica. Pertanto, è necessario eseguire un ricaricamento di pagina completo per il componente per visualizzare l'output seguente. Per ulteriori informazioni, consultare la sezione Routing interattivo e prerendering.

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

Nell'esempio seguente che serializza lo stato per più componenti dello stesso tipo:

  • Le proprietà annotate con l'attributo [SupplyParameterFromPersistentComponentState] vengono serializzate e deserializzate durante il prerendering.
  • L'attributo@key di direttiva viene usato per assicurarsi che lo stato sia associato correttamente all'istanza del componente.
  • La Element proprietà viene inizializzata nel OnInitialized metodo del ciclo di vita per evitare eccezioni di riferimento Null, in modo analogo al modo in cui i riferimenti Null vengono evitati per i parametri di query e i dati del modulo.

PersistentChild.razor:

<div>
    <p>Current count: @Element.CurrentCount</p>
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</div>

@code {
    [SupplyParameterFromPersistentComponentState]
    public State Element { get; set; }

    protected override void OnInitialized()
    {
        Element ??= new State();
    }

    private void IncrementCount()
    {
        Element.CurrentCount++;
    }

    private class State
    {
        public int CurrentCount { get; set; }
    }
}

Parent.razor:

@page "/parent"

@foreach (var element in elements)
{
    <PersistentChild @key="element.Name" />
}

Nell'esempio seguente che serializza dello stato per un servizio di iniezione delle dipendenze:

  • Le proprietà annotate con l'attributo [SupplyParameterFromPersistentComponentState] vengono serializzate durante il prerendering e deserializzate quando l'app diventa interattiva.
  • Il AddPersistentService metodo viene usato per registrare il servizio per la persistenza. La modalità di rendering è necessaria perché la modalità di rendering non può essere dedotta dal tipo di servizio. Usare uno dei valori seguenti:
    • RenderMode.Server: il servizio è disponibile per la modalità di rendering di Interactive Server.
    • RenderMode.Webassembly: il servizio è disponibile per la modalità di rendering Interactive Webassembly.
    • RenderMode.InteractiveAuto: il servizio è disponibile per le modalità di rendering Interactive Server e Interactive Webassembly se un componente esegue il rendering in una di queste modalità.
  • Il servizio viene risolto durante l'inizializzazione di una modalità di rendering interattiva e le proprietà annotate con l'attributo [SupplyParameterFromPersistentComponentState] vengono deserializzate.

Nota

È supportata solo la persistenza dei servizi con ambito.

CounterService.cs:

public class CounterService
{
    [SupplyParameterFromPersistentComponentState]
    public int CurrentCount { get; set; }

    public void IncrementCount()
    {
        CurrentCount++;
    }
}

In Program.cs:

builder.Services.AddPersistentService<CounterService>(RenderMode.InteractiveAuto);

Le proprietà serializzate vengono identificate dall'istanza del servizio effettiva:

  • Questo approccio consente di contrassegnare un'astrazione come servizio permanente.
  • Consente alle implementazioni effettive di essere tipi interni o diversi.
  • Supporta il codice condiviso in assembly diversi.
  • Ogni istanza risulta nel mostrare le stesse proprietà.

In alternativa all'uso del modello dichiarativo per rendere persistente lo stato con l'attributo [SupplyParameterFromPersistentComponentState] , è possibile usare direttamente il PersistentComponentState servizio, che offre maggiore flessibilità per scenari di persistenza dello stato complesso. Chiamare PersistentComponentState.RegisterOnPersisting per registrare un callback per mantenere lo stato del componente durante la pre-renderizzazione. Lo stato viene recuperato quando il componente esegue il rendering interattivo. Effettuare la chiamata alla fine del codice di inizializzazione per evitare una potenziale race condition durante l'arresto dell'app.

Nell'esempio seguente del componente contatore, lo stato del contatore viene mantenuto durante la pre-renderizzazione e recuperato per inizializzare il componente.

PrerenderedCounter3.razor:

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

<PageTitle>Prerendered Counter 3</PageTitle>

<h1>Prerendered Counter 3</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()
    {
        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);
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistCount);
    }

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

        return Task.CompletedTask;
    }

    private void IncrementCount() => currentCount++;

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

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.

Nota

Se l'app adotta il routing interattivo e la pagina viene raggiunta tramite una navigazione avanzata interna , il prerendering non si verifica. Pertanto, è necessario eseguire un ricaricamento di pagina completo per il componente per visualizzare l'output seguente. Per ulteriori informazioni, consultare la sezione Routing interattivo e prerendering.

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

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 durante il pre-riavvio. Lo stato viene recuperato quando il componente esegue il rendering interattivo. Effettuare la chiamata alla fine del codice di inizializzazione per evitare una potenziale race condition durante l'arresto dell'app.

Nell'esempio seguente del componente contatore, lo stato del contatore viene mantenuto durante la pre-renderizzazione e recuperato 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()
    {
        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);
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistCount);
    }

    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.

Nota

Se l'app adotta il routing interattivo e la pagina viene raggiunta tramite una navigazione avanzata interna , il prerendering non si verifica. Pertanto, è necessario eseguire un ricaricamento di pagina completo per il componente per visualizzare l'output seguente. Per ulteriori informazioni, consultare la sezione Routing interattivo e prerendering.

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 renderizzata corrisponde anche all'interfaccia utente prerenderizzata, 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), la protezione dei dati ASP.NET Core garantisce che i dati vengano trasferiti in modo sicuro. La InteractiveAuto modalità di rendering combina l'interattività di WebAssembly e del 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 il Tag Helper "Persist Component State" con il tag HTML all'interno del tag di chiusura <persist-component-state /> 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>

Instradamento 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 sul pre-rendering

Le indicazioni per il prerendering sono organizzate nella documentazione in base all'argomento Blazor. I collegamenti seguenti illustrano tutte le linee guida di prerendering in tutta la documentazione suddivisa per argomento:

Per .NET 7 o versioni precedenti, vedere Blazor WebAssembly Scenari di sicurezza aggiuntivi: Prerendering con autenticazione. Dopo aver visualizzato il contenuto in questa sezione, reimpostare l'elenco a discesa del selettore della versione dell'articolo della documentazione sulla versione più recente di .NET per assicurarsi che le pagine della documentazione vengano caricate per la versione più recente nelle visite successive.