Prerendere componenti ASP.NET Core Razor

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

La pre-gestione è il processo di rendering statico del contenuto della pagina dal server per distribuire HTML al browser il più rapidamente possibile. Dopo che il contenuto prerenderato viene visualizzato rapidamente all'utente, viene eseguito il rendering del contenuto interattivo con gestori eventi attivi, sostituendo qualsiasi contenuto di cui è stato eseguito il rendering in precedenza. 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.

Il prerendering è abilitato per impostazione predefinita per i componenti interattivi.

Lo spostamento interno con routing interattivo non usa il prerendering perché la pagina è già interattiva. Per altre informazioni, vedere Routing statico e interattivoe routing interattivo e prerendering.

OnAfterRender{Async} Gli eventi del ciclo di vita dei componenti non vengono chiamati durante la pre-gestione, solo dopo il rendering interattivo del componente.

Disabilitare la prerendering

Il prerendering può complicare un'app perché i componenti dell'app devono essere sottoposti a rendering due volte: una volta per la prerendering e una volta per la configurazione dell'interattività Razor . Se i componenti sono configurati per l'esecuzione in WebAssembly, è necessario progettare anche i componenti in modo che possano essere eseguiti sia dal server che dal client.

Per disabilitare il prerendering per un'istanza del componente , passare l'opzione prerender con un valore di false alla modalità di rendering:

• <... @rendermode="new InteractiveServerRenderMode(prerender: false)" />
• <... @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />
• <... @rendermode="new InteractiveAutoRenderMode(prerender: false)" />

Per disabilitare la prerendering in una definizione di componente:

• @rendermode @(new InteractiveServerRenderMode(prerender: false))
• @rendermode @(new InteractiveWebAssemblyRenderMode(prerender: false))
• @rendermode @(new InteractiveAutoRenderMode(prerender: false))

Per disabilitare la prerendering per l'intera app, indicare la modalità di rendering al componente interattivo di livello più alto nella gerarchia dei componenti dell'app che non è un componente radice.

Per le app basate sul modello di Blazor Web App progetto, viene specificata una modalità di rendering assegnata all'intera app in cui il Routes componente viene usato nel App componente (Components/App.razor). L'esempio seguente imposta la modalità di rendering dell'app su Interactive Server con prerendering disabilitato:

<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />

Disabilitare anche la prerendering per il HeadOutlet nel :

<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />

La creazione di un componente radice, come il componente App, interattivo con la direttiva @rendermode all'inizio del file di definizione del componente radice (.razor) non è supportata. Di conseguenza, il prerendering non può essere disabilitato direttamente dal App componente.

La disabilitazione della prerendering con le tecniche precedenti ha effetto solo per le modalità di rendering di primo livello. Se un componente padre specifica una modalità di rendering, le impostazioni di prerendering dei suoi elementi figli vengono ignorate.

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. Per indicazioni su come rendere persistente lo stato durante la pre-distribuzione, vedere ASP.NET persistenza dello stato prerenderato coreBlazor.

I servizi sul lato client non vengono risolti durante la prerenderizzazione

Supponendo che il prerendering non sia disabilitato per un componente o per l'app, un componente nel .Client progetto viene pre-predefinito nel server. Poiché il server non ha accesso ai servizi lato client Blazor registrati, non è possibile iniettare questi servizi in un componente senza ricevere un errore che indica che il servizio non può essere trovato durante il prerebering.

Si consideri, ad esempio, il seguente componente Home nel progetto .Client in un ambiente Blazor Web App con rendering globale o automatico Interattivo WebAssembly. Il componente tenta di inserire IWebAssemblyHostEnvironment per ottenere il nome dell'ambiente.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    Environment: @Environment.Environment
</p>

Non si verifica alcun errore in fase di compilazione, ma si verifica un errore di runtime durante la pre-esecuzione:

Impossibile specificare un valore per la proprietà 'Environment' nel tipo 'BlazorSample.Client.Pages'Home. Non esiste alcun servizio registrato di tipo 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Questo errore si verifica perché il componente deve essere compilato ed eseguito nel server durante la pre-esecuzione, ma IWebAssemblyHostEnvironment non è un servizio registrato nel server.

Prendere in considerazione uno degli approcci seguenti per risolvere questo scenario:

• Registrare il servizio nel server oltre al client
• Inserire un servizio che l'app può usare durante il pre-rendering
• Rendere il servizio facoltativo
• Creare un'astrazione del servizio
• Disabilitare il pre-rendering per il componente

Registrare il servizio nel server oltre al client

Se il servizio supporta l'esecuzione sul server, registrare il servizio sul server oltre che sul client in modo che sia disponibile durante il pre-rendering. Per un esempio di questo scenario, vedere le linee guida per HttpClient i servizi nella Blazor Web App sezione API Web esterna dell'articolo Chiamare l'API Web .

Inserire un servizio che l'app può utilizzare durante il prerendering

In alcuni casi, l'app può usare un servizio sul server durante il prerendering e un servizio diverso sul client.

Ad esempio, il codice seguente ottiene l'ambiente dell'app, indipendentemente dal fatto che il codice sia in esecuzione nel server o nel client inserendo IHostEnvironment dal Microsoft.Extensions.Hosting.Abstractions pacchetto NuGet:

private string? environmentName;

public Home(IHostEnvironment? serverEnvironment = null, 
    IWebAssemblyHostEnvironment? wasmEnvironment = null)
{
    environmentName = serverEnvironment?.EnvironmentName;
    environmentName ??= wasmEnvironment?.Environment;
}

Tuttavia, questo approccio aggiunge una dipendenza aggiuntiva al progetto client che non è necessario.

Rendere il servizio facoltativo

Rendere facoltativo il servizio se non è richiesto durante il prerendering usando uno degli approcci seguenti.

L'esempio seguente utilizza l'iniezione del costruttore di IWebAssemblyHostEnvironment:

private string? environmentName;

public Home(IWebAssemblyHostEnvironment? env = null)
{
    environmentName = env?.Environment;
}

In alternativa, inserire IServiceProvider per ottenere facoltativamente il servizio, se disponibile:

@page "/"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IServiceProvider Services

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    <b>Environment:</b> @environmentName
</p>

@code {
    private string? environmentName;

    protected override void OnInitialized()
    {
        if (Services.GetService<IWebAssemblyHostEnvironment>() is { } env)
        {
            environmentName = env.Environment;
        }
    }
}

Creare un'astrazione del servizio

Se è necessaria un'implementazione del servizio diversa nel server, creare un'astrazione del servizio e creare implementazioni per il servizio nei progetti server e client. Registrare i servizi in ogni progetto. Inserire l'astrazione del servizio personalizzata nei componenti, se necessario. Il componente dipende quindi esclusivamente dall'astrazione del servizio personalizzato.

Nel caso di IWebAssemblyHostEnvironment, è possibile riutilizzare l'interfaccia esistente anziché crearne una nuova:

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

Nel file del progetto server Program registrare il servizio:

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

A questo punto, il IWebAssemblyHostEnvironment servizio può essere inserito in un webAssembly interattivo o in un componente automatico prerenderato anche dal server.

Disabilitare la prerenderizzazione per il componente

Disabilitare il pre-rendering per il componente o per l'intera app. Per altre informazioni, vedere la sezione Disabilita prerendering.