modalità di rendering ASP.NET Core Blazor

Questo articolo illustra il controllo del rendering dei Razor componenti in Blazor Web Apps, in fase di compilazione o in fase di esecuzione.

Queste indicazioni non si applicano alle app autonome Blazor WebAssembly . Blazor WebAssembly le app eseguono il rendering solo sul client tramite un runtime basato su WebAssembly sul lato client e non hanno alcun concetto di modalità di rendering. Se una modalità di rendering viene applicata a un componente in un'app Blazor WebAssembly , la designazione della modalità di rendering non influisce sul rendering del componente.

Modalità di rendering

Ogni componente di un Blazor Web App oggetto adotta una modalità di rendering per determinare il modello di hosting usato, dove viene eseguito il rendering e se è interattivo o meno.

La tabella seguente illustra le modalità di rendering disponibili per i componenti di rendering Razor in un oggetto Blazor Web App. Per applicare una modalità di rendering a un componente, usare la direttiva nell'istanza @rendermode del componente o nella definizione del componente. Più avanti in questo articolo vengono illustrati esempi per ogni scenario in modalità di rendering.

Nome	Descrizione	Posizione di rendering	Interattivo
Server statico	Rendering statico lato server (SSR statico)	Server	❌No
Server interattivo	Rendering lato server interattivo (SSR interattivo) tramite Blazor Server.	Server	✔️Sì
WebAssembly interattivo	Rendering lato client (CSR) con Blazor WebAssembly†.	Client	✔️Sì
Auto interattivo	SSR interattivo che usa Blazor Server inizialmente e quindi csr nelle visite successive dopo il download del Blazor bundle.	Server, quindi client	✔️Sì

si presuppone che il rendering lato client (CSR) † sia interattivo. "Rendering lato client interattivo " e "CSR interattivo " non vengono usati dal settore o nella Blazor documentazione.

Il prerendering è abilitato per impostazione predefinita per i componenti interattivi. Le indicazioni sul controllo della prerendering sono disponibili più avanti in questo articolo. Per la terminologia generale del settore sui concetti relativi al rendering client e server, vedere ASP.NET Nozioni fondamentali di baseBlazor.

Gli esempi seguenti illustrano l'impostazione della modalità di rendering del componente con alcune funzionalità di base Razor del componente.

Per testare i comportamenti della modalità di rendering in locale, è possibile inserire i componenti seguenti in un'app creata dal modello di Blazor Web App progetto. Quando si crea l'app, selezionare le opzioni dai menu a discesa (Visual Studio) o applicare le opzioni dell'interfaccia della riga di comando (interfaccia della riga di comando .NET) per abilitare sia l'interattività lato server che quella lato client. Per indicazioni su come creare un Blazor Web Appoggetto , vedere Strumenti per ASP.NET Core Blazor.

Abilitare il supporto per le modalità di rendering interattive

Un Blazor Web App oggetto deve essere configurato per supportare le modalità di rendering interattive. Le estensioni seguenti vengono applicate automaticamente alle app create dal modello di progetto durante la Blazor Web App creazione dell'app. I singoli componenti sono comunque necessari per dichiarare la modalità di rendering in base alla sezione Modalità di rendering dopo che i servizi e gli endpoint dei componenti sono configurati nel file dell'app Program .

I servizi per Razor i componenti vengono aggiunti chiamando AddRazorComponents.

Estensioni del generatore di componenti:

• AddInteractiveServerComponents aggiunge servizi per supportare il rendering dei componenti Interactive Server.
• AddInteractiveWebAssemblyComponents aggiunge servizi per supportare il rendering dei componenti Interactive WebAssembly.

MapRazorComponents individua i componenti disponibili e specifica il componente radice per l'app (il primo componente caricato), che per impostazione predefinita è il App componente (App.razor).

Estensioni del generatore di convenzioni degli endpoint:

• AddInteractiveServerRenderMode configura il rendering interattivo lato server (SSR interattivo) per l'app.
• AddInteractiveWebAssemblyRenderMode configura la modalità di rendering Interactive WebAssembly per l'app.

Nota

Per l'orientamento sulla posizione dell'API negli esempi seguenti, esaminare il Program file di un'app generata dal Blazor Web App modello di progetto. Per indicazioni su come creare un Blazor Web Appoggetto , vedere Strumenti per ASP.NET Core Blazor.

Esempio 1: l'API file seguente Program aggiunge servizi e configurazione per l'abilitazione di SSR interattivo:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

Esempio 2: l'API file seguente Program aggiunge servizi e configurazione per abilitare la modalità di rendering Interactive WebAssembly:

builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode();

Esempio 3: l'API file seguente Program aggiunge servizi e configurazione per abilitare le modalità di rendering interattivo Server, Interactive WebAssembly e Interactive Auto:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode();

Blazor usa il Blazor WebAssembly modello di hosting per scaricare ed eseguire componenti che usano la modalità di rendering Interactive WebAssembly. Per configurare Blazor WebAssembly l'hosting per questi componenti, è necessario un progetto client separato. Il progetto client contiene il codice di avvio per l'host e configura il runtime .NET per l'esecuzione Blazor WebAssembly in un browser. Il Blazor Web App modello aggiunge automaticamente questo progetto client quando si seleziona l'opzione per abilitare l'interattività WebAssembly. Tutti i componenti che usano la modalità di rendering Interactive WebAssembly devono essere compilati dal progetto client, in modo che vengano inclusi nel bundle dell'app scaricato.

Applicare una modalità di rendering a un'istanza del componente

Per applicare una modalità di rendering a un'istanza del componente, usare l'attributo @rendermodeRazor di direttiva in cui viene usato il componente.

Nell'esempio seguente il rendering interattivo lato server (SSR interattivo) viene applicato all'istanza del Dialog componente:

<Dialog @rendermode="InteractiveServer" />

Nota

Blazor I modelli includono una direttiva statica using per RenderMode nel file dell'app _Imports (Components/_Imports.razor) per una sintassi più @rendermode breve:

@using static Microsoft.AspNetCore.Components.Web.RenderMode

Senza la direttiva precedente, i componenti devono specificare la classe statica RenderMode nella @rendermode sintassi:

<Dialog @rendermode="RenderMode.InteractiveServer" />

È anche possibile fare riferimento a istanze personalizzate della modalità di rendering create direttamente con la configurazione personalizzata. Per altre informazioni, vedere la sezione Modalità di rendering abbreviate personalizzate più avanti in questo articolo.

Applicare una modalità di rendering a una definizione di componente

Per specificare la modalità di rendering per un componente come parte della relativa definizione, usare la @rendermodeRazor direttiva e l'attributo della modalità di rendering corrispondente.

@page "..."
@rendermode InteractiveServer

L'applicazione di una modalità di rendering a una definizione di componente viene comunemente usata quando si applica una modalità di rendering a una pagina specifica. Le pagine instradabili usano la stessa modalità di rendering del Router componente che ha eseguito il rendering della pagina.

Tecnicamente, @rendermode è sia unaRazor direttiva che un attributo di Razordirettiva. La semantica è simile, ma esistono differenze. La @rendermode direttiva si trova nella definizione del componente, pertanto l'istanza della modalità di rendering a cui si fa riferimento deve essere statica. L'attributo @rendermode direttiva può accettare qualsiasi istanza della modalità di rendering.

Nota

Gli autori di componenti devono evitare di accoppiare l'implementazione di un componente a una modalità di rendering specifica. Gli autori di componenti devono in genere progettare componenti per supportare qualsiasi modalità di rendering o modello di hosting. L'implementazione di un componente deve evitare presupposti sulla posizione in cui è in esecuzione (server o client) e deve degradarsi normalmente durante il rendering statico. Specificare la modalità di rendering nella definizione del componente può essere necessaria se il componente non viene creata direttamente un'istanza (ad esempio con un componente pagina instradabile) o per specificare una modalità di rendering per tutte le istanze del componente.

Applicare una modalità di rendering all'intera app

Per impostare la modalità di rendering 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.

Nota

Rendere interattivo un componente radice, ad esempio il App componente, non è supportato. Pertanto, la modalità di rendering per l'intera app non può essere impostata direttamente dal App componente.

Per le app basate sul modello di Blazor Web App progetto, viene in genere specificata una modalità di rendering assegnata all'intera app in cui il Routes componente viene usato nel App componente (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Il Router componente propaga la modalità di rendering alle pagine in cui viene instradato.

In genere è anche necessario impostare la stessa modalità di rendering interattiva nel HeadOutlet componente, disponibile anche nel App componente di un Blazor Web App generato dal modello di progetto:

<HeadOutlet @rendermode="InteractiveServer" />

Per le app che adottano una modalità di rendering lato client interattiva (WebAssembly o Auto) e abilitare la modalità di rendering per l'intera app tramite il Routes componente:

• Posizionare o spostare il layout e i file di spostamento della cartella dell'app Components/Layout server nella .Client cartella del Layout progetto. Creare una Layout cartella nel .Client progetto, se non esiste.
• Posizionare o spostare i componenti della cartella dell'app Components/Pages server nella .Client cartella del Pages progetto. Creare una Pages cartella nel .Client progetto, se non esiste.
• Posizionare o spostare il Routes componente della cartella dell'app Components server nella .Client cartella radice del progetto.

Per abilitare l'interattività globale durante la creazione di un oggetto Blazor Web App:

• Visual Studio: impostare l'elenco a discesa Percorso interattività su Globale.
• Interfaccia della riga di comando di .NET: usare l'opzione -ai|--all-interactive .

Per altre informazioni, vedere Strumenti per ASP.NET Core Blazor.

Applicare una modalità di rendering a livello di codice

Le proprietà e i campi possono assegnare una modalità di rendering.

Il secondo approccio descritto in questa sezione, impostando la modalità di rendering per istanza del componente, è particolarmente utile quando la specifica dell'app chiama uno o più componenti per adottare ssr statici in un'app interattiva a livello globale. Questo scenario è illustrato nelle pagine SSR statiche in un'app interattiva a livello globale più avanti in questo articolo.

Impostare la modalità di rendering per definizione del componente

Una definizione di componente può definire una modalità di rendering tramite un campo privato:

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

Impostare la modalità di rendering in base all'istanza del componente

Nell'esempio seguente viene applicato il rendering lato server interattivo (SSR interattivo) a qualsiasi richiesta.

<Routes @rendermode="PageRenderMode" />

...

@code {
    private IComponentRenderMode? PageRenderMode => InteractiveServer;
}

Altre informazioni sulla propagazione della modalità di rendering sono disponibili nella sezione Propagazione della modalità di rendering più avanti in questo articolo. La sezione Pagine SSR statiche in un'app interattiva a livello globale illustra come usare l'approccio precedente per adottare SSR statico in un'app interattiva a livello globale.

Rilevare la posizione di rendering, l'interattività e la modalità di rendering assegnata in fase di esecuzione

Le ComponentBase.RendererInfo proprietà e ComponentBase.AssignedRenderMode consentono all'app di rilevare i dettagli relativi alla posizione, all'interattività e alla modalità di rendering assegnata di un componente:

• RendererInfo.Name restituisce il percorso in cui è in esecuzione il componente:
  • Static: nel server (SSR) e incapace di interattività.
  • Server: nel server (SSR) e in grado di interattività dopo il prerendering.
  • WebAssembly: nel client (CSR) e in grado di interattività dopo il prerendering.
  • WebView: nel dispositivo nativo e in grado di interattività dopo il prerendering.
• RendererInfo.IsInteractive indica se il componente supporta l'interattività al momento del rendering. Il valore è true quando si esegue il rendering in modo interattivo o false quando si esegue la pre-esecuzione o per SSR statico (RendererInfo.Name di Static).
• ComponentBase.AssignedRenderMode espone la modalità di rendering assegnata dal componente:
  • InteractiveServer per Interactive Server.
  • InteractiveAuto per Interactive Auto.
  • InteractiveWebAssembly per Interactive WebAssembly.

I componenti usano queste proprietà per eseguire il rendering del contenuto a seconda della posizione o dello stato di interattività. Gli esempi seguenti illustrano casi d'uso tipici.

Visualizzare il contenuto finché un componente non è interattivo:

@if (!RendererInfo.IsInteractive)
{
    <p>Connecting to the assistant...</p>
}
else
{
    ...
}

Disabilitare un pulsante finché un componente non è interattivo:

<button @onclick="Send" disabled="@(!RendererInfo.IsInteractive)">
    Send
</button>

Disabilitare un modulo durante la prerendering e abilitare il modulo quando il componente è interattivo:

<EditForm Model="Movie" ...>
    <fieldset disabled="@disabled">

        ...

        <button type="submit" >Save</button>
    </fieldset>
</EditForm>

@code {
    private bool disabled = true;

    [SupplyParameterFromForm]
    private Movie? Movie { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Movie ??= await ...;

        if (RendererInfo.IsInteractive)
        {
            disabled = false;
        }
    }
}

Eseguire il rendering del markup per supportare l'esecuzione di un'azione HTML regolare se viene eseguito il rendering statico del componente:

@if (AssignedRenderMode is null)
{
    // The render mode is Static Server
    <form action="/movies">
        <input type="text" name="titleFilter" />
        <input type="submit" value="Search" />
    </form>
}
else
{
    // The render mode is Interactive Server, WebAssembly, or Auto
    <input @bind="titleFilter" />
    <button @onclick="FilterMovies">Search</button>
}

Nell'esempio precedente:

• Quando il valore di AssignedRenderMode è null, il componente adotta ssr statico. Blazor la gestione degli eventi non è funzionale in un browser con SSR statico, quindi il componente invia un modulo (richiesta GET) con una titleFilter stringa di query impostata sul valore dell'utente <input> . Il Movie componente (/movie) può leggere la stringa di query ed elaborare il valore di titleFilter per eseguire il rendering del componente con i risultati filtrati.
• In caso contrario, la modalità di rendering è qualsiasi di InteractiveServer, InteractiveWebAssemblyo InteractiveAuto. Il componente è in grado di usare un delegato del gestore eventi (FilterMovies) e il valore associato all'elemento <input> (titleFilter) per filtrare i film in modo interattivo sulla connessione in background SignalR .

Blazor esempi di documentazione per Blazor Web Apps

Quando si usa un Blazor Web App, la maggior parte dei componenti di esempio della Blazor documentazione richiede interattività per funzionare e dimostrare i concetti trattati negli articoli. Quando si testa un componente di esempio fornito da un articolo, assicurarsi che l'app adotta interattività globale o che il componente adotta una modalità di rendering interattiva.

Prerendering

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.

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

Lo spostamento interno per il routing interattivo non comporta la richiesta di nuovo contenuto della pagina dal server. Di conseguenza, il prerendering non si verifica per le richieste di pagina interne, incluso per la navigazione avanzata. Per altre informazioni, vedere Routing statico e interattivo, routing interattivo e prerendering e gestione avanzata dei moduli e navigazione.

La disabilitazione della prerendering con le tecniche seguenti ha effetto solo per le modalità di rendering di primo livello. Se un componente padre specifica una modalità di rendering, le impostazioni di pre-esecuzione dei relativi elementi figlio vengono ignorate. Questo comportamento è in fase di analisi per le possibili modifiche apportate al rilascio di .NET 10 a novembre 2025.

Per disabilitare la prerendering per un'istanza del componente, passare il prerender flag 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 componente nel App componente:

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

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

Rendering statico lato server (SSR statico)

I componenti usano il rendering statico lato server (SSR statico). Il rendering del componente nel flusso di risposta e nell'interattività non è abilitato.

Nell'esempio seguente non esiste alcuna designazione per la modalità di rendering del componente, quindi il componente eredita la modalità di rendering dal relativo elemento padre. Poiché nessun componente predecessore specifica una modalità di rendering, il rendering del componente seguente viene eseguito in modo statico nel server. Il pulsante non è interattivo e non chiama il UpdateMessage metodo quando selezionato. Il valore di message non cambia e il componente non viene rivalutato in risposta agli eventi dell'interfaccia utente.

RenderMode1.razor:

@page "/render-mode-1"

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Se si usa il componente precedente in locale in un Blazor Web Appoggetto , posizionare il componente nella cartella del progetto server Components/Pages . Il progetto server è il progetto della soluzione con un nome che non termina in .Client. Quando l'app è in esecuzione, passare a /render-mode-1 nella barra degli indirizzi del browser.

Durante il ssr statico, Razor le richieste di pagina dei componenti vengono elaborate dal lato server ASP.NET l'elaborazione delle richieste della pipeline middleware core per il routing e l'autorizzazione. Le funzionalità dedicate Blazor per il routing e l'autorizzazione non sono operative perché Razor il rendering dei componenti non viene eseguito durante l'elaborazione delle richieste sul lato server. Blazor le funzionalità del router nel Routes componente che non sono disponibili durante la visualizzazione statica di SSR includono la visualizzazione:

• Contenuto non autorizzato (<NotAuthorized>...</NotAuthorized>):NotAuthorizedBlazor Web App in genere elabora le richieste non autorizzate nel server personalizzando il comportamento del middleware di autorizzazione.

• Contenuto non trovato () (<NotFound>...</NotFound>NotFound): Blazor Web App in genere elabora richieste URL non valide nel server visualizzando l'interfaccia utente predefinita del browser 404 o restituendo una pagina 404 personalizzata (o un'altra risposta) tramite ASP.NET middleware core (ad esempio,UseStatusCodePagesWithRedirects / documentazione dell'API).

Se l'app presenta interattività a livello radice, l'elaborazione delle richieste core ASP.NET sul lato server non è coinvolta dopo il SSR statico iniziale, il che significa che le funzionalità precedenti Blazor funzionano come previsto.

La navigazione avanzata con SSR statico richiede particolare attenzione durante il caricamento di JavaScript. Per altre informazioni, vedere ASP.NET Core Blazor JavaScript con rendering statico lato server (SSR statico).

Rendering lato server interattivo (SSR interattivo)

Il rendering lato server interattivo (SSR interattivo) esegue il rendering interattivo del componente dal server usando Blazor Server. Le interazioni utente vengono gestite tramite una connessione in tempo reale con il browser. La connessione al circuito viene stabilita quando viene eseguito il rendering del componente server.

Nell'esempio seguente la modalità di rendering viene impostata su SSR interattivo aggiungendo @rendermode InteractiveServer alla definizione del componente. Il pulsante chiama il UpdateMessage metodo quando selezionato. Il valore delle message modifiche e il componente viene riabilita per aggiornare il messaggio nell'interfaccia utente.

RenderMode2.razor:

@page "/render-mode-2"
@rendermode InteractiveServer

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Se si usa il componente precedente in un Blazor Web App, posizionare il componente nella cartella del progetto server Components/Pages . Il progetto server è il progetto della soluzione con un nome che non termina in .Client. Quando l'app è in esecuzione, passare a /render-mode-2 nella barra degli indirizzi del browser.

Rendering lato client

Il rendering lato client esegue il rendering interattivo del componente nel client usando Blazor WebAssembly. Il runtime .NET e il bundle dell'app vengono scaricati e memorizzati nella cache quando viene inizialmente eseguito il rendering del componente WebAssembly. I componenti che usano CSR devono essere compilati da un progetto client separato che configura l'host Blazor WebAssembly .

Nell'esempio seguente la modalità di rendering è impostata su CSR con @rendermode InteractiveWebAssembly. Il pulsante chiama il UpdateMessage metodo quando selezionato. Il valore delle message modifiche e il componente viene riabilita per aggiornare il messaggio nell'interfaccia utente.

RenderMode3.razor:

@page "/render-mode-3"
@rendermode InteractiveWebAssembly

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Se si usa il componente precedente in locale in un Blazor Web App, posizionare il componente nella cartella del Pages progetto client. Il progetto client è il progetto della soluzione con un nome che termina con .Client. Quando l'app è in esecuzione, passare a /render-mode-3 nella barra degli indirizzi del browser.

Rendering automatico (automatico)

Il rendering automatico (automatico) determina come eseguire il rendering del componente in fase di esecuzione. Il rendering del componente viene inizialmente eseguito con il rendering interattivo lato server (SSR interattivo) usando il Blazor Server modello di hosting. Il runtime .NET e il bundle dell'app vengono scaricati nel client in background e memorizzati nella cache in modo che possano essere usati nelle visite future.

La modalità di rendering automatico non modifica mai dinamicamente la modalità di rendering di un componente già presente nella pagina. La modalità di rendering automatico prende una decisione iniziale sul tipo di interattività da usare per un componente, quindi il componente mantiene tale tipo di interattività purché si tratti della pagina. Un fattore di questa decisione iniziale consiste nel valutare se i componenti esistono già nella pagina con interattività WebAssembly/Server. La modalità automatica preferisce selezionare una modalità di rendering corrispondente alla modalità di rendering dei componenti interattivi esistenti. Il motivo per cui la modalità Automatica preferisce usare una modalità di interattività esistente consiste nell'evitare di introdurre un nuovo runtime interattivo che non condivide lo stato con il runtime esistente.

I componenti che usano la modalità di rendering automatico devono essere compilati da un progetto client separato che configura l'host Blazor WebAssembly .

Nell'esempio seguente il componente è interattivo in tutto il processo. Il pulsante chiama il UpdateMessage metodo quando selezionato. Il valore delle message modifiche e il componente viene riabilita per aggiornare il messaggio nell'interfaccia utente. Inizialmente, il rendering del componente viene eseguito in modo interattivo dal server, ma nelle visite successive viene eseguito il rendering dal client dopo che il runtime .NET e il bundle dell'app vengono scaricati e memorizzati nella cache.

RenderMode4.razor:

@page "/render-mode-4"
@rendermode InteractiveAuto

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Se si usa il componente precedente in locale in un Blazor Web App, posizionare il componente nella cartella del Pages progetto client. Il progetto client è il progetto della soluzione con un nome che termina con .Client. Quando l'app è in esecuzione, passare a /render-mode-4 nella barra degli indirizzi del browser.

Propagazione della modalità di rendering

Le modalità di rendering si propagano verso il basso nella gerarchia dei componenti.

Regole per l'applicazione delle modalità di rendering:

• La modalità di rendering predefinita è Statica.
• Le modalità di rendering Interactive Server (InteractiveServer), Interactive WebAssembly (InteractiveWebAssembly) e Interactive Auto (InteractiveAuto) possono essere usate da un componente, inclusa l'uso di modalità di rendering diverse per i componenti di pari livello.
• Non è possibile passare a una modalità di rendering interattiva diversa in un componente figlio. Ad esempio, un componente server non può essere figlio di un componente WebAssembly.
• I parametri passati a un componente figlio interattivo da un elemento padre statico devono essere serializzabili IN FORMATO JSON. Ciò significa che non è possibile passare frammenti di rendering o contenuto figlio da un componente padre statico a un componente figlio interattivo.

Gli esempi seguenti usano un componente non instradabile e non di pagina SharedMessage . Il componente indipendente dalla modalità SharedMessage di rendering non applica una modalità di rendering con una @attribute direttiva . Se si testano questi scenari con un Blazor Web App, inserire il componente seguente nella cartella dell'app Components .

SharedMessage.razor:

<p>@Greeting</p>

<button @onclick="UpdateMessage">Click me</button> @message

<p>@ChildContent</p>

@code {
    private string message = "Not updated yet.";

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    [Parameter]
    public string Greeting { get; set; } = "Hello!";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Ereditarietà della modalità di rendering

Se il SharedMessage componente viene inserito in un componente padre sottoposto a rendering statico, viene eseguito anche il rendering statico del SharedMessage componente e non è interattivo. Il pulsante non chiama UpdateMessagee il messaggio non viene aggiornato.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

Se il SharedMessage componente viene inserito in un componente che definisce la modalità di rendering, eredita la modalità di rendering applicata.

Nell'esempio seguente il SharedMessage componente è interattivo tramite una SignalR connessione al client. Il pulsante chiama UpdateMessagee il messaggio viene aggiornato.

RenderMode6.razor:

@page "/render-mode-6"
@rendermode InteractiveServer

<SharedMessage />

Componenti figlio con diverse modalità di rendering

Nell'esempio seguente entrambi i SharedMessage componenti vengono prerenderati e visualizzati quando la pagina viene visualizzata nel browser.

• Il primo SharedMessage componente con rendering interattivo lato server (SSR interattivo) è interattivo dopo la creazione del SignalR circuito.
• Il secondo SharedMessage componente con rendering lato client (CSR) è interattivo dopo il download del Blazor bundle dell'app e il runtime .NET è attivo nel client.

RenderMode7.razor:

@page "/render-mode-7"

<SharedMessage @rendermode="InteractiveServer" />
<SharedMessage @rendermode="InteractiveWebAssembly" />

Componente figlio con un parametro serializzabile

Nell'esempio seguente viene illustrato un componente figlio interattivo che accetta un parametro . I parametri devono essere serializzabili.

RenderMode8.razor:

@page "/render-mode-8"

<SharedMessage @rendermode="InteractiveServer" Greeting="Welcome!" />

I parametri del componente non serializzabili, ad esempio il contenuto figlio o un frammento di rendering, non sono supportati. Nell'esempio seguente, il passaggio del contenuto figlio al SharedMessage componente genera un errore di runtime.

RenderMode9.razor:

@page "/render-mode-9"

<SharedMessage @rendermode="InteractiveServer">
    Child content
</SharedMessage>

❌Errore:

System.InvalidOperationException: impossibile passare il parametro 'ChildContent' al componente 'SharedMessage' con renderingmode 'InteractiveServerRenderMode'. Questo perché il parametro è del tipo delegato 'Microsoft.AspNetCore.Components.RenderFragment', che è codice arbitrario e non può essere serializzato.

Per aggirare la limitazione precedente, eseguire il wrapping del componente figlio in un altro componente che non ha il parametro . Questo è l'approccio adottato nel modello di Blazor Web App progetto con il componente (Components/Routes.razor) per eseguire il Routes wrapping del Router componente.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

Nell'esempio precedente:

• Il contenuto figlio viene passato al SharedMessage componente senza generare un errore di runtime.
• Il SharedMessage componente esegue il rendering interattivo nel server.

Componente figlio con una modalità di rendering diversa da quella padre

Non provare ad applicare una modalità di rendering interattiva diversa a un componente figlio rispetto alla modalità di rendering del padre.

Il componente seguente genera un errore di runtime quando viene eseguito il rendering del componente:

RenderMode11.razor:

@page "/render-mode-11"
@rendermode InteractiveServer

<SharedMessage @rendermode="InteractiveWebAssembly" />

❌Errore:

Cannot create a component of type 'BlazorSample.Components.SharedMessage' because its render mode 'Microsoft.AspNetCore.Components.Web.InteractiveWebAssemblyRenderMode' is not supported by Interactive Server rendering.

Pagine SSR statiche in un'app interattiva a livello globale

Esistono casi in cui la specifica dell'app richiede ai componenti di adottare il rendering statico lato server (SSR statico) e viene eseguito solo nel server, mentre l'oggetto rest dell'app usa una modalità di rendering interattiva.

Questo approccio è utile solo quando l'app ha pagine specifiche che non possono funzionare con il rendering interattivo server o WebAssembly. Ad esempio, adottare questo approccio per le pagine che dipendono dalla lettura/scrittura di cookie HTTP e possono funzionare solo in un ciclo di richiesta/risposta invece del rendering interattivo. Per le pagine che funzionano con il rendering interattivo, non è consigliabile forzarle a usare il rendering statico di SSR, perché è meno efficiente e meno reattivo per l'utente finale.

Contrassegnare qualsiasi Razor pagina del componente con l'attributo [ExcludeFromInteractiveRouting] assegnato con la @attributeRazor direttiva :

@attribute [ExcludeFromInteractiveRouting]

L'applicazione dell'attributo fa sì che la navigazione alla pagina esesce dal routing interattivo. Lo spostamento in ingresso è costretto a eseguire un ricaricamento a pagina intera, risolvendo invece la pagina tramite routing interattivo. Il ricaricamento a pagina intera forza il componente radice di primo livello, in genere il App componente (App.razor), a eseguire il rerender dal server, consentendo all'app di passare a una diversa modalità di rendering di primo livello.

Il RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting metodo di estensione consente al componente di rilevare se l'attributo [ExcludeFromInteractiveRouting] viene applicato alla pagina corrente.

App Nel componente usare il modello nell'esempio seguente:

• Le pagine che non sono annotate con l'attributo predefinito per la InteractiveServer [ExcludeFromInteractiveRouting] modalità di rendering con interattività globale. È possibile sostituire InteractiveServer con InteractiveWebAssembly o InteractiveAuto per specificare una modalità di rendering globale predefinita diversa.
• Le pagine annotate con l'attributo [ExcludeFromInteractiveRouting] adopt static SSR (PageRenderMode è assegnato null).

<!DOCTYPE html>
<html>
<head>
    ...
    <HeadOutlet @rendermode="@PageRenderMode" />
</head>
<body>
    <Routes @rendermode="@PageRenderMode" />
    ...
</body>
</html>

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? PageRenderMode
        => HttpContext.AcceptsInteractiveRouting() ? InteractiveServer : null;
}

Un'alternativa all'uso del metodo di estensione consiste nel RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting leggere manualmente i metadati dell'endpoint usando HttpContext.GetEndpoint()?.Metadata.

I servizi sul lato client non riescono a risolvere durante il pre-riavvio

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 Blazor client registrati, non è possibile inserire questi servizi in un componente senza ricevere un errore che indica che non è possibile trovare il servizio durante la pre-gestione.

Si consideri ad esempio il componente seguente Home nel .Client progetto in un Blazor Web App oggetto con rendering Interattivo WebAssembly globale o Interattivo automatico. 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.

Se l'app non richiede il valore durante la prerendering, questo problema può essere risolto inserendo IServiceProvider per ottenere il servizio anziché il tipo di servizio stesso:

@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;
        }
    }
}

Tuttavia, l'approccio precedente non è utile se la logica richiede un valore durante la prerendering.

È anche possibile evitare il problema se si disabilita il prerendering per il componente, ma si tratta di una misura estrema da adottare in molti casi che potrebbero non soddisfare le specifiche del componente.

Esistono tre approcci che è possibile adottare per risolvere questo scenario. Di seguito sono elencate le opzioni consigliate per la maggior parte consigliate:

• Consigliato per i servizi framework condivisi: per i servizi framework condivisi che semplicemente non sono registrati sul lato server nel progetto principale, registrare i servizi nel progetto principale, rendendoli disponibili durante la pre-gestione. Per un esempio di questo scenario, vedere le linee guida per HttpClient i servizi in Chiamare un'API Web da un'app ASP.NET CoreBlazor.

• Consigliato per i servizi all'esterno del framework condiviso: creare un'implementazione del servizio personalizzata per il servizio nel server. Usare il servizio normalmente nei componenti interattivi del .Client progetto. Per una dimostrazione di questo approccio, vedere ASP.NET Ambienti CoreBlazor.

• Creare un'astrazione del servizio e creare implementazioni per il servizio nei .Client progetti server e . Registrare i servizi in ogni progetto. Inserire il servizio personalizzato nel componente.

• Potrebbe essere possibile aggiungere un .Client riferimento al pacchetto di progetto a un pacchetto sul lato server ed eseguire il fallback all'uso dell'API lato server durante la pre-esecuzione del rendering nel server.

Individuare i componenti da assembly aggiuntivi

Per individuare i componenti instradabili Razor nei progetti a cui si fa riferimento, è necessario divulgare assembly aggiuntivi al Blazor framework. Per altre informazioni, vedere ASP.NET routing e navigazione coreBlazor.

Chiusura di circuiti quando non sono presenti componenti Interactive Server rimanenti

I componenti di Interactive Server gestiscono gli eventi dell'interfaccia utente Web usando una connessione in tempo reale con il browser denominato circuito. Un circuito e lo stato associato vengono creati quando viene eseguito il rendering di un componente Interactive Server radice. Il circuito viene chiuso quando nella pagina non sono presenti componenti Interactive Server rimanenti, che liberano risorse server.

Modalità di rendering abbreviate personalizzate

La @rendermode direttiva accetta un singolo parametro che è un'istanza statica di tipo IComponentRenderMode. L'attributo @rendermode di direttiva può accettare qualsiasi istanza della modalità di rendering, statica o meno. Il Blazor framework fornisce la RenderMode classe statica con alcune modalità di rendering predefinite per praticità, ma è possibile crearne di personalizzate.

In genere, un componente usa la direttiva seguente @rendermode per disabilitare il prerendering:

@rendermode @(new InteractiveServerRenderMode(prerender: false))

Si consideri tuttavia l'esempio seguente che crea una modalità di rendering lato server interattivo a mano abbreviata senza eseguire la pre-esecuzione tramite il file dell'app _Imports (Components/_Imports.razor):

public static IComponentRenderMode InteractiveServerWithoutPrerendering { get; } = 
    new InteractiveServerRenderMode(prerender: false);

Usare la modalità di rendering abbreviata nei componenti della Components cartella:

@rendermode InteractiveServerWithoutPrerendering

In alternativa, una singola istanza del componente può definire una modalità di rendering personalizzata tramite un campo privato:

@rendermode interactiveServerWithoutPrerendering

...

@code {
    private static IComponentRenderMode interactiveServerWithoutPrerendering = 
        new InteractiveServerRenderMode(prerender: false);
}

Al momento, l'approccio alla modalità di rendering abbreviata è probabilmente utile solo per ridurre il livello di dettaglio dell'impostazione del prerender flag. L'approccio abbreviato potrebbe risultare più utile in futuro se sono disponibili flag aggiuntivi per il rendering interattivo e si vogliono creare modalità di rendering abbreviate con diverse combinazioni di flag.

Inserimento del servizio tramite un file di importazione di primo livello (_Imports.razor)

Questa sezione si applica solo a Blazor Web Apps.

Un file di primo livello importa nella Components cartella (Components/_Imports.razor) inserisce i riferimenti in tutti i componenti nella gerarchia di cartelle, che include il App componente (App.razor). Il rendering del App componente viene sempre eseguito in modo statico anche se la pre-gestione di un componente di pagina è disabilitata. Pertanto, l'inserimento di servizi tramite il file di importazione di primo livello comporta la risoluzione di due istanze del servizio nei componenti della pagina.

Per risolvere questo scenario, inserire il servizio in un nuovo file di importazioni inserito nella Pages cartella (Components/Pages/_Imports.razor). Da tale posizione, il servizio viene risolto una sola volta nei componenti della pagina.

Risorse aggiuntive

• Compressione WebSocket
  • Linee guida per ASP.NET Core BlazorSignalR
  • Linee guida per la mitigazione delle minacce per ASP.NET rendering lato server interattivo Core Blazor
• ASP.NET Core Blazor JavaScript con rendering statico lato server (SSR statico)
• Valori/parametri a catena e limiti della modalità di rendering: vedere anche la sezione Parametri a cascata a livello di radice più indietro nell'articolo.
• ASP.NET librerie di classi core Razor (RCLs) con rendering statico lato server (SSR statico)