modalità di rendering di ASP.NET Core Blazor

Questo articolo spiega come controllare il rendering dei componenti Razor nei Blazor Web App, sia in fase di compilazione che 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. L'interattività consente agli utenti di interagire con i componenti sottoposti a rendering. Le risposte dell'applicazione agli eventi del modello a oggetti del documento (DOM) e le modifiche di stato associate ai membri di C# tramite i gestori di eventi e il binding di Blazorsono incluse.

La tabella seguente illustra le modalità di rendering disponibili per i componenti Razor in un 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 dal lato server (SSR statico)	Servidor	❌ No
Server interattivo	Rendering interattivo lato server (SSR interattivo) tramite Blazor Server.	Servidor	✔️Sì
WebAssembly interattivo	Rendering lato client (CSR) utilizzando Blazor WebAssembly†.	Cliente	✔️Sì
Auto interattivo	SSR interattivo che utilizza Blazor Server inizialmente e poi CSR nelle visite successive dopo il download del pacchetto Blazor.	Server, quindi client	✔️Sì

Si presume che il rendering lato client (CSR) sia interattivo. "Rendering client-side interattivo" e "CSR interattivo" non sono usati dall'industria o nella documentazione Blazor."

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

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 istruzioni su come creare un Blazor Web App, 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 devono ancora dichiarare la modalità di rendering come indicato nella sezione Modalità di rendering dopo che i servizi e gli endpoint dei componenti sono stati configurati nel file dell'app Program.

I servizi dei componenti Razor 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 istruzioni su come creare un Blazor Web App, vedere Strumenti per ASP.NET Core Blazor.

Esempio 1: il seguente file API aggiunge servizi e configurazione per abilitare l'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 di file seguente Program aggiunge servizi e configurazioni per abilitare le modalità di rendering Interattivo Server, Interattivo WebAssembly e Interattivo Automatico:

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 componente Dialog.

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

È inoltre possibile fare riferimento a istanze di modalità di rendering personalizzate, create direttamente con configurazione personalizzata. Per ulteriori informazioni, consultare 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 componente Router che ha eseguito il rendering della pagina.

Tecnicamente, @rendermode è sia una Razordirettiva che un Razorattributo direttivo. 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 direttiva @rendermode può accettare istanze di qualsiasi 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 necessario se il componente non viene istanziato direttamente (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 i file di layout e di navigazione della cartella del server dell'app Components/Layout nella cartella del progetto .Client. 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 componente Routes della cartella Components dell'app server nella cartella radice del progetto .Client.

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

• Visual Studio: impostare il menu a discesa della posizione dell'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, impostare la modalità di rendering per istanza del componente, è particolarmente utile quando la specifica dell'app richiede che uno o più componenti adottino SSR statico in un'app che altrimenti sarebbe interattiva. Questo scenario è descritto nelle pagine SSR statiche nella sezione di un'app interattiva 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 interattivo lato server (SSR) 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 SSR statica in un'app interattiva illustra come usare l'approccio precedente per adottare SSR statico in un'app altrimenti interattiva.

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.

Pre-rendering

Le modalità di rendering interattive (Interactive Server, Interactive WebAssembly, Interactive Auto) supportano la prerendering per impostazione predefinita, che inizialmente esegue il rendering del contenuto della pagina in modo statico dal server per migliorare l'esperienza di caricamento iniziale. Per altre informazioni, vedere componenti Prerender ASP.NET CoreRazor.

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: sul server (SSR) e incapace di interagire.
  • Server: Sul server (SSR) e in grado di interagire dopo il prerendering.
  • WebAssembly: sul client (CSR) ed è in grado di interagire dopo il prerendering.
  • WebView: Sul dispositivo nativo e capace di interazione 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 il pre-rendering o durante il SSR statico (RendererInfo.Name di Static).
• AssignedRenderMode espone la modalità di rendering assegnata dal componente:
  • InteractiveServerRenderMode per Server Interattivo.
  • InteractiveAutoRenderMode per Interactive Auto.
  • InteractiveWebAssemblyRenderMode per "Interactive WebAssembly".
  • null se non viene assegnata una modalità di rendering.

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 il pre-rendering e abilitare il modulo quando il componente diventa 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 standard quando il componente è reso staticamente.

@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 componente Movie (/movie) può leggere la stringa di query e processare il valore di titleFilter per visualizzare il 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 tramite la connessione in background SignalR.

Rendering statico dal lato server (SSR statico)

I componenti utilizzano il rendering statico lato server (SSR statico). Il componente viene renderizzato nel flusso di risposta e l'interattività non è abilitata.

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 utilizza il componente precedente in locale in un Blazor Web App, posizionare il componente nella cartella del server del progetto 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 l'SSR statico, Razor le richieste di pagina dei componenti vengono elaborate dalla pipeline middleware server-side ASP.NET Core per l'autorizzazione delle richieste. Le funzionalità dedicate Blazor per l'autorizzazione non sono operative perché i componenti Razor non vengono eseguiti durante l'elaborazione delle richieste lato server. Blazorle funzionalità del router nel Routes componente che non sono disponibili durante la ssr statica includono la visualizzazione di contenuto non autorizzato (<NotAuthorized>...</NotAuthorized>).NotAuthorized Blazor Web Appin genere elabora le richieste non autorizzate nel server personalizzando il comportamento del middleware di autorizzazione.

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 ulteriori informazioni, vedere ASP.NET Core Blazor JavaScript con rendering statico lato server (SSR).

Rendering interattivo lato server (SSR interattivo)

Il rendering lato server interattivo (SSR interattivo) esegue interattivamente il rendering 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 di message cambia e il componente viene ri-renderizzato 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.

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 il suo stato associato vengono creati quando viene eseguito il rendering di un componente radice del Server Interattivo. Il circuito viene chiuso quando nella pagina non sono presenti componenti Interactive Server rimanenti, che liberano risorse server.

Rendering sul 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 di message cambia e il componente viene ri-renderizzato 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 utilizza il componente precedentemente localmente in un Blazor Web App, posizionare il componente nella cartella del progetto client Pages. 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 (Auto)

Il rendering automatico determina come eseguire il rendering del componente durante l'esecuzione. Il componente viene inizialmente reso tramite rendering interattivo lato server (SSR interattivo) attraverso il modello di hosting Blazor Server. 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 di message cambia e il componente viene ri-renderizzato 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 utilizza il componente precedentemente localmente in un Blazor Web App, posizionare il componente nella cartella del progetto client Pages. 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 utilizzano un componente SharedMessage non instradabile e non associato a una pagina. Il componente SharedMessage indipendente dalla modalità di rendering non utilizza 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) diventa interattivo dopo che il circuito di BlazorSignalR è stabilito.
• Il secondo SharedMessage componente con rendering lato client (CSR) è interattivo dopo il download del Blazor pacchetto dell'app e il runtime .NET è attivo sul client.

RenderMode7.razor:

@page "/render-mode-7"

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

Componente figlio con un parametro serializzabile

Nell'esempio seguente viene mostrato 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 non serializzabili del componente, come il contenuto figlio o il frammento di render, non sono supportati. Nell'esempio seguente, il passaggio del contenuto figlio al componente SharedMessage 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.

La stessa cosa accade se si tenta di adottare il rendering interattivo in un layout che eredita da LayoutComponentBase, ad esempio il componente dell'app MainLayout , in un'app che adotta il rendering per pagina/componente. Per altre informazioni, vedere layout ASP.NET CoreBlazor.

Per aggirare la limitazione precedente, inserisci il componente figlio in un altro componente che non include il parametro. Questo è l'approccio adottato nel modello di progetto Blazor Web App con il componente Routes per incapsulare il componente Components/Routes.razor.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

Nell'esempio precedente:

• Il contenuto figlio viene passato al componente SharedMessage 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 del genitore

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

In alcuni casi la specifica dell'app richiede ai componenti di adottare il rendering statico lato server (SSR statico) e viene eseguito solo nel server, mentre il resto 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 forzare l'uso di SSR statico, perché è meno efficiente e meno reattivo per l'utente finale.

Contrassegnare qualsiasi pagina del componente con l'attributo assegnato con la direttiva :

@attribute [ExcludeFromInteractiveRouting]

L'applicazione dell'attributo fa sì che la navigazione alla pagina esca dal routing interattivo. La navigazione in entrata è costretta a eseguire un ricaricamento a pagina intera anziché risolvere la pagina tramite routing interattivo. Il ricaricamento a pagina intera forza il componente radice di primo livello, di solito il componente App (App.razor), a effettuare il rendering dal server, consentendo all'app di passare a una diversa modalità di rendering per il livello superiore.

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

Nel componente App, usare il modello nell'esempio seguente.

• Le pagine che non sono annotate con l'attributo[ExcludeFromInteractiveRouting] predefiniscono alla modalità di rendering InteractiveServer 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 adottano SSR statico ( viene assegnato ).

<!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 è leggere manualmente i metadati dell'endpoint usando RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting.

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

Tuttavia, considera il seguente esempio che crea una modalità abbreviata di rendering interattivo lato server senza prerendering 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 contenuti nella cartella Components.

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

Risorse aggiuntive

• Compressione WebSocket
  • Linee guida per ASP.NET Core BlazorSignalR
  • Linee guida per la mitigazione delle minacce per il rendering interattivo lato server di ASP.NET 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 i valori a catena a livello di radice e i valori a catena a livello di radice con le sezioni relative alle notifiche riportate in precedenza nell'articolo.
• Razor
• Protegge i dati in Blazor Web Appcon rendering interattivo automatico