ASP.NET Core Blazor renderingsmodi

In dit artikel wordt het beheer van het weergeven van Razor-onderdelen in Blazor Web App's uitgelegd, hetzij tijdens de compilatie of bij uitvoeringstijd.

Deze richtlijnen zijn niet van toepassing op zelfstandige Blazor WebAssembly apps. Blazor WebAssembly apps worden alleen op de client weergegeven via een client-side WebAssembly-runtime en hebben geen concept van een weergavemodus. Als een rendermodus wordt toegepast op een onderdeel in een Blazor WebAssembly-app, heeft de weergavemodus geen invloed op het weergeven van het onderdeel.

Rendermodi

Elk onderdeel in een Blazor Web App neemt een -rendermodus aan om het hostingmodel te bepalen dat wordt gebruikt, waar het wordt weergegeven en of het interactief is. Interactiviteit maakt het voor gebruikers mogelijk om te communiceren met gerenderde onderdelen. Dit omvat app-reacties op DOM-gebeurtenissen (Document Object Model) en gebeurtenissen en statuswijzigingen die via de gebeurtenis-handlers en binding van Blazoraan C#-leden zijn gekoppeld.

In de volgende tabel ziet u de beschikbare rendermodi voor het weergeven van Razor onderdelen in een Blazor Web App. Als u een rendermodus wilt toepassen op een onderdeel, gebruikt u de @rendermode-instructie op het onderdeelexemplaar of de definitie van het onderdeel. Verderop in dit artikel worden voorbeelden weergegeven voor elk scenario van de rendermodus.

Naam	Beschrijving	Locatie weergeven	Interactief
Statische server	Statische rendering aan serverzijde (statische SSR)	Bedieningscomputer	❌ Geen
Interactieve server	Interactieve server-side rendering (interactieve SSR) met behulp van Blazor Server.	Bedieningscomputer	✔️ Ja
Interactieve WebAssembly	CSR (Client Side Rendering) met behulp van Blazor WebAssembly†.	Klant	✔️ Ja
Interactieve Auto	Interactieve SSR met Blazor Server in eerste instantie en vervolgens CSR bij volgende bezoeken nadat de Blazor bundel is gedownload.	Server en vervolgens client	✔️ Ja

†Client-side rendering (CSR) wordt verondersteld interactief te zijn. "Interactive client-side rendering" en "interactive CSR" worden niet gebruikt door de industrie of in de Blazor documentatie.

Prerendering is standaard ingeschakeld voor interactieve onderdelen. Verderop in dit artikel vindt u richtlijnen voor het beheren van prerendering. Zie ASP.NET Core Blazor fundamentalsvoor algemene brancheterminologie over client- en serverweergaveconcepten.

In de volgende voorbeelden ziet u hoe u de weergavemodus van het onderdeel instelt met enkele eenvoudige Razor onderdeelfuncties.

Als u het gedrag van de rendermodus lokaal wilt testen, kunt u de volgende onderdelen in een app plaatsen die is gemaakt op basis van de Blazor Web App-projectsjabloon. Wanneer u de app maakt, selecteert u opties in vervolgkeuzelijsten (Visual Studio) of past u de CLI-opties (.NET CLI) toe om interactiviteit aan de serverzijde en aan de clientzijde in te schakelen. Voor richtlijnen voor het maken van een Blazor Web App, zie Tooling voor ASP.NET Core Blazor.

Ondersteuning inschakelen voor interactieve rendermodi

Er moet een Blazor Web App worden geconfigureerd ter ondersteuning van interactieve rendermodi. De volgende extensies worden automatisch toegepast op apps die zijn gemaakt op basis van de Blazor Web App projectsjabloon tijdens het maken van de app. Afzonderlijke onderdelen zijn nog steeds vereist om de weergavemodus te declareren volgens de Render-modi sectie nadat de onderdeelservices en eindpunten zijn geconfigureerd in het Program-bestand van de app.

Services voor Razor onderdelen worden toegevoegd door aanroep van AddRazorComponents.

Extensies voor de componentbouwer

• AddInteractiveServerComponents voegt services toe ter ondersteuning van het weergeven van interactieve serveronderdelen.
• AddInteractiveWebAssemblyComponents voegt services toe ter ondersteuning van rendering van interactieve WebAssembly-componenten.

MapRazorComponents beschikbare onderdelen detecteert en het hoofdonderdeel voor de app aangeeft (het eerste geladen onderdeel), dat standaard het App onderdeel (App.razor) is.

Extensies voor eindpuntconventiebouwer.

• AddInteractiveServerRenderMode configureert interactieve server-side rendering (interactieve SSR) voor de app.
• AddInteractiveWebAssemblyRenderMode configureert de weergavemodus Interactive WebAssembly voor de app.

Notitie

Voor oriëntatie op de plaatsing van de API in de volgende voorbeelden controleert u het Program bestand van een app die is gegenereerd op basis van de Blazor Web App projectsjabloon. Voor richtlijnen voor het maken van een Blazor Web App, zie Tooling voor ASP.NET Core Blazor.

Voorbeeld 1: Met de volgende Program bestands-API worden services en configuratie toegevoegd voor het inschakelen van interactieve SSR:

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

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

Voorbeeld 2: Met de volgende Program bestands-API worden services en configuratie toegevoegd voor het inschakelen van de interactieve webassembly-rendermodus:

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

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

Voorbeeld 3: Met de volgende Program bestands-API worden services en configuratie toegevoegd voor het inschakelen van de modi Interactive Server, Interactive WebAssembly en Interactive Auto Render:

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

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

Blazor gebruikt het Blazor WebAssembly hostingmodel om onderdelen te downloaden en uit te voeren die gebruikmaken van de interactieve webassembly-rendermodus. Er is een afzonderlijk clientproject vereist voor het instellen van Blazor WebAssembly hosting voor deze onderdelen. Het clientproject bevat de opstartcode voor de Blazor WebAssembly host en stelt de .NET-runtime in voor uitvoering in een browser. Met de Blazor Web App-sjabloon wordt dit clientproject voor u toegevoegd wanneer u de optie selecteert om WebAssembly-interactiviteit in te schakelen. Alle onderdelen die de rendermodus Interactive WebAssembly gebruiken, moeten worden gebouwd vanuit het clientproject, zodat ze worden opgenomen in de gedownloade app-bundel.

Rendermodus toepassen op een onderdeelexemplaar

Als u een rendermodus wilt toepassen op een onderdeelexemplaar, gebruikt u het kenmerk @rendermodeRazor directive op de plaats waar het onderdeel wordt gebruikt.

In het volgende voorbeeld wordt interactieve server-side rendering (interactieve SSR) toegepast op de Dialog componentinstantie.

<Dialog @rendermode="InteractiveServer" />

Notitie

Blazor sjablonen bevatten een statische using-instructie voor RenderMode in het _Imports-bestand van de app (Components/_Imports.razor) voor kortere @rendermode syntaxis:

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

Zonder de voorgaande instructie moeten onderdelen de statische RenderMode klasse opgeven in @rendermode syntaxis:

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

U kunt ook verwijzen naar exemplaren van de aangepaste rendermodus die rechtstreeks met een aangepaste configuratie zijn geïnstantieerd. Zie de sectie Aangepaste verkorte weergavemodi verderop in dit artikel voor meer informatie.

Een weergavemodus toepassen op een onderdeeldefinitie

Als u de weergavemodus voor een onderdeel wilt opgeven als onderdeel van de definitie, gebruikt u de @rendermodeRazor instructie en het bijbehorende kenmerk voor de weergavemodus.

@page "..."
@rendermode InteractiveServer

Het toepassen van een weergavemodus op een onderdeeldefinitie wordt vaak gebruikt bij het toepassen van een rendermodus op een specifieke pagina. Routeerbare pagina's gebruiken dezelfde weergavemodus als het Router onderdeel dat de pagina heeft weergegeven.

Technisch gezien is @rendermode zowel een Razorrichtlijn als een Razorrichtlijnkenmerk. De semantiek is vergelijkbaar, maar er zijn verschillen. De @rendermode-instructie bevindt zich in de onderdeeldefinitie, dus het exemplaar van de weergavemodus waarnaar wordt verwezen, moet statisch zijn. Het @rendermode directive-kenmerk kan elke instantie van een render-modus aannemen.

Notitie

Auteurs van onderdelen moeten voorkomen dat de implementatie van een onderdeel wordt gekoppeld aan een specifieke rendermodus. In plaats daarvan moeten auteurs van onderdelen doorgaans onderdelen ontwerpen ter ondersteuning van een rendermodus of hostingmodel. De implementatie van een onderdeel moet veronderstellingen over waar het wordt uitgevoerd (op server of client) vermijden en moet geleidelijk en zonder problemen verminderen wanneer het statisch wordt weergegeven. Het opgeven van de weergavemodus in de onderdeeldefinitie kan nodig zijn als het onderdeel niet rechtstreeks wordt geïnstantieerd (bijvoorbeeld met een routeerbaar paginaonderdeel) of als u een weergavemodus voor alle onderdeelexemplaren wilt opgeven.

Een rendermodus toepassen op de hele app

Als u de weergavemodus voor de hele app wilt instellen, geeft u de weergavemodus op het hoogste niveau aan in de componenthiërarchie van de app die geen hoofdonderdeel is.

Notitie

Het interactief maken van een hoofdonderdeel, zoals het App-onderdeel, wordt niet ondersteund. Daarom kan de weergavemodus voor de hele app niet rechtstreeks worden ingesteld door het App-onderdeel.

Voor apps op basis van de Blazor Web App projectsjabloon wordt doorgaans een weergavemodus opgegeven die is toegewezen aan de hele app, waarbij het Routes onderdeel wordt gebruikt in het App-onderdeel (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Het Router-onderdeel geeft de weergavemodus door aan de pagina's die het doorstuurt.

Doorgaans moet u ook dezelfde interactieve weergavemodus instellen op het HeadOutlet onderdeel, dat ook wordt gevonden in het App onderdeel van een Blazor Web App gegenereerd op basis van de projectsjabloon:

<HeadOutlet @rendermode="InteractiveServer" />

Voor apps die een interactieve weergavemodus (WebAssembly of Auto) gebruiken en de weergavemodus voor de hele app inschakelen via het Routes onderdeel:

• Plaats of verplaats de indelings- en navigatiebestanden van de Components/Layout map van de server-app naar de .Client map van het Layout project. Maak een Layout map in het .Client project als deze nog niet bestaat.
• Plaats of verplaats de onderdelen van de Components/Pages map van de server-app naar de .Client map van het Pages project. Maak een Pages map in het .Client project als deze nog niet bestaat.
• Plaats of verplaats het Routes onderdeel van de Components map van de server-app naar de hoofdmap van het .Client project.

Globale interactiviteit inschakelen bij het maken van een Blazor Web App:

• Visual Studio: stel de interactiviteitslocatie vervolgkeuzelijst in op globaal.
• .NET CLI: gebruik de optie -ai|--all-interactive.

Zie Hulpprogramma's voor ASP.NET Core Blazorvoor meer informatie.

Een rendermodus programmatisch toepassen

Eigenschappen en velden kunnen een rendermodus toewijzen.

De tweede benadering die in deze sectie wordt beschreven, waarbij de rendermodus per onderdeelexemplaren wordt ingesteld, is vooral handig wanneer uw app-specificatie aanroept dat een of meer onderdelen statische SSR in een andere interactieve app gebruiken. Dit scenario wordt behandeld in de Statische SSR-pagina's in een interactieve app sectie verderop in dit artikel.

De weergavemodus instellen op onderdeeldefinitie

Een onderdeeldefinitie kan een rendermodus definiëren via een privéveld:

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

De weergavemodus instellen per componentinstantie

In het volgende voorbeeld wordt interactieve server-side rendering (interactieve SSR) toegepast op elke aanvraag.

<Routes @rendermode="PageRenderMode" />

...

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

Meer informatie over de propagatie van de weergavemodus vindt u verderop in dit artikel in het weergavemodus propagatie gedeelte. De statische SSR-pagina's in de sectie van een interactieve app laten zien hoe u de voorgaande benadering gebruikt om statische SSR in een anders interactieve app toe te passen.

Blazor documentatie voorbeelden voor Blazor Web Apps

Wanneer u een Blazor Web App gebruikt, moeten de meeste documentatievoorbeeldonderdelen van Blazor interactiviteit hebben om te functioneren en om de concepten te laten zien zoals behandeld in de artikelen. Wanneer u een voorbeeldonderdeel test dat wordt geleverd door een artikel, moet u ervoor zorgen dat de app gebruikmaakt van wereldwijde interactiviteit of dat het onderdeel een interactieve rendermodus gebruikt.

Voorrendering

Prerendering is het proces van het aanvankelijk weergeven van paginainhoud op de server zonder gebeurtenishandlers in te schakelen voor gerenderde besturingselementen. De server voert de HTML-gebruikersinterface van de pagina zo snel mogelijk uit als reactie op de eerste aanvraag, waardoor de app sneller reageert op gebruikers. Prerendering kan ook SEO- (Search Engine Optimization) verbeteren door inhoud weer te geven voor het eerste HTTP-antwoord dat zoekmachines gebruiken om de paginarang te berekenen.

Prerendering is standaard ingeschakeld voor interactieve onderdelen.

Interne navigatie voor interactieve routering houdt niet in dat nieuwe pagina-inhoud van de server wordt aangevraagd. Daarom vindt prerendering niet plaats voor interne paginaaanvragen, waaronder voor verbeterde navigatie. Zie voor meer informatie Statische versus interactieve routering, Interactieve routering en prerendering, en verbeterde navigatie- en formulierafhandeling.

Het uitschakelen van prerendering met behulp van de volgende technieken wordt alleen van kracht voor rendermodi op het hoogste niveau. Als een oudercomponent een weergavemodus opgeeft, worden de prerenderingsinstellingen van de kindcomponenten genegeerd. Dit gedrag wordt onderzocht op mogelijke wijzigingen met de release van .NET 10 in november 2025.

Wilt u de prerendering uitschakelen voor een componentinstantie, geef dan de vlag prerender met een waarde van false door aan de weergavemodus:

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

Prerendering uitschakelen in een componentdefinitie:

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

Als u het prerendering voor de hele app wilt uitschakelen, geeft u de rendermodus op het hoogste niveau aan in de componenthiërarchie van de app die geen hoofdonderdeel is.

Voor apps op basis van de Blazor Web App projectsjabloon wordt een weergavemodus opgegeven die is toegewezen aan de hele app, waarbij het Routes onderdeel wordt gebruikt in het App onderdeel (Components/App.razor). In het volgende voorbeeld wordt de rendermodus van de app ingesteld op Interactive Server, waarbij de prerendering is uitgeschakeld:

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

Schakel ook het prerendering uit voor het HeadOutlet-onderdeel in het App-onderdeel:

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

Het maken van een hoofdonderdeel, zoals het App-onderdeel, interactief met de @rendermode instructie boven aan het definitiebestand van het hoofdonderdeel (.razor) wordt niet ondersteund. Daarom kan prerendering niet rechtstreeks worden uitgeschakeld door het App onderdeel.

Renderinglocatie, interactiviteit en toegewezen rendermodus detecteren tijdens runtime

Met de eigenschappen ComponentBase.RendererInfo en ComponentBase.AssignedRenderMode kan de app details detecteren over de locatie, interactiviteit en toegewezen rendermodus van een onderdeel:

• RendererInfo.Name retourneert de locatie waar het onderdeel wordt uitgevoerd:
  • Static: Op de server (SSR) en niet in staat tot interactiviteit.
  • Server: Op de server (SSR) en in staat tot interactiviteit na het prerenderen.
  • WebAssembly: Op de client (CSR) en in staat tot interactiviteit na het prerenderen.
  • WebView: op het systeemeigen apparaat en geschikt voor interactiviteit na het prerendering.
• RendererInfo.IsInteractive geeft aan of het onderdeel interactiviteit op het moment van rendering ondersteunt. De waarde is true bij interactief weergeven of false bij prerenderen of voor statische SSR (RendererInfo.Name van Static).
• AssignedRenderMode de toegewezen rendermodus van het onderdeel beschikbaar maakt:
  • InteractiveServerRenderMode voor interactieve server.
  • InteractiveAutoRenderMode voor Interactieve Automaat.
  • InteractiveWebAssemblyRenderMode voor Interactive WebAssembly.
  • null als er geen weergavemodus is toegewezen.

Onderdelen gebruiken deze eigenschappen om inhoud weer te geven, afhankelijk van hun locatie of interactiviteitsstatus. In de volgende voorbeelden ziet u typische gebruiksvoorbeelden.

Inhoud weergeven totdat een onderdeel interactief is:

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

Schakel een knop uit totdat een onderdeel interactief is:

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

Schakel een formulier uit tijdens het voorbereiden en schakel het formulier in wanneer het onderdeel interactief is:

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

Opmaak weergeven ter ondersteuning van het uitvoeren van een normale HTML-actie als het onderdeel statisch wordt weergegeven:

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

In het voorgaande voorbeeld:

• Wanneer de waarde van AssignedRenderModenullis, gebruikt de component statische SSR. Blazor event handling is niet functioneel in een browser met statische SSR, dus verzendt de component een formulier (GET-verzoek) met een titleFilter querystring die is ingesteld op de <input>-waarde van de gebruiker. Het Movie-onderdeel (/movie) kan de querytekenreeks lezen en de waarde van titleFilter verwerken om het onderdeel weer te geven met de gefilterde resultaten.
• Anders is de weergavemodus een van InteractiveServer, InteractiveWebAssemblyof InteractiveAuto. Het onderdeel kan een event handler delegate (FilterMovies) en de waarde die is gebonden aan het <input>-element (titleFilter) gebruiken om films interactief te filteren via de achtergrondverbinding SignalR.

Statische rendering aan serverzijde (statische SSR)

Onderdelen maken gebruik van statische rendering aan serverzijde (statische SSR). Het onderdeel wordt weergegeven in de antwoordstroom en interactiviteit is niet ingeschakeld.

In het volgende voorbeeld is er geen aanduiding voor de rendermodus van het onderdeel, dus neemt het onderdeel de weergavemodus over van het bovenliggende element. Omdat geen voorouderonderdeel een rendermodus aangeeft, wordt het volgende onderdeel statisch gerenderd op de server. De knop is niet interactief en roept de UpdateMessage methode niet aan wanneer deze is geselecteerd. De waarde van message verandert niet en het onderdeel wordt niet gewijzigd als reactie op ui-gebeurtenissen.

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!";
    }
}

Als u het voorgaande onderdeel lokaal in een Blazor Web Appgebruikt, plaatst u het onderdeel in de Components/Pages map van het serverproject. Het serverproject is het project van de oplossing met een naam die niet eindigt op .Client. Wanneer de app wordt uitgevoerd, gaat u naar /render-mode-1 in de adresbalk van de browser.

Tijdens statische SSR worden Razor componentpagina-aanvragen verwerkt door de server-side ASP.NET Core middleware-pijplijn voor route- en autorisatieaanvraagverwerking. Toegewezen Blazor functies voor routering en autorisatie zijn niet operationeel omdat Razor onderdelen niet worden weergegeven tijdens de verwerking van aanvragen aan de serverzijde. Blazor routerfuncties in de Routes-component die niet beschikbaar zijn tijdens statische SSR, omvatten onder andere het weergeven van:

• Niet-geautoriseerde inhoud (<NotAuthorized>...</NotAuthorized>) (NotAuthorized): Blazor Web Appverwerken doorgaans niet-geautoriseerde aanvragen op de server door het gedrag van autorisatie-middlewareaan te passen.

• Geen gevonden inhoud (<NotFound>...</NotFound>) (NotFound): Blazor Web Appverwerken meestal ongeldige URL-aanvragen op de server door de ingebouwde 404-gebruikersinterface van de browser weer te geven of een aangepaste 404-pagina (of een ander antwoord) te retourneren via ASP.NET Core-middleware (bijvoorbeeld UseStatusCodePagesWithRedirects / API-documentatie). Voor meer informatie, zie voor een eenvoudigere manier om de Niet Gevonden 404-UI weer te geven met Blazor (dotnet/aspnetcore #45654).

Als de app interactiviteit op hoofdniveau vertoont, is ASP.NET Core-aanvraagverwerking aan de serverzijde niet betrokken na de eerste statische SSR, wat betekent dat de voorgaande Blazor-functies werken zoals verwacht.

Verbeterde navigatie met statische SSR vereist speciale aandacht bij het laden van JavaScript. Voor meer informatie, zie ASP.NET Core Blazor JavaScript met statische server-side rendering (statische SSR).

Interactieve server-side rendering (interactieve SSR)

Interactieve server-side rendering (interactieve SSR) rendert het onderdeel interactief vanaf de server met behulp van Blazor Server. Gebruikersinteracties worden verwerkt via een realtime-verbinding met de browser. De circuitverbinding wordt tot stand gebracht wanneer het serveronderdeel wordt weergegeven.

In het volgende voorbeeld wordt de weergavemodus ingesteld op interactieve SSR door @rendermode InteractiveServer toe te voegen aan de onderdeeldefinitie. De knop roept de UpdateMessage methode aan wanneer deze is geselecteerd. De waarde van message wijzigt en de component wordt opnieuw gerenderd om het bericht in de gebruikersinterface bij te werken.

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!";
    }
}

Als u het voorgaande onderdeel in een Blazor Web Appgebruikt, plaatst u het onderdeel in de Components/Pages map van het serverproject. Het serverproject is het project van de oplossing met een naam die niet eindigt op .Client. Wanneer de app wordt uitgevoerd, gaat u naar /render-mode-2 in de adresbalk van de browser.

Rendering aan clientzijde (CSR)

Csr (Client Side Rendering) geeft het onderdeel interactief weer op de client met behulp van Blazor WebAssembly. De .NET-runtime en app-bundel worden gedownload en in de cache opgeslagen wanneer het WebAssembly-onderdeel in eerste instantie wordt weergegeven. Onderdelen die gebruikmaken van CSR moeten worden gebouwd vanuit een afzonderlijk clientproject waarmee de Blazor WebAssembly host wordt ingesteld.

In het volgende voorbeeld is de rendermodus ingesteld op CSR met @rendermode InteractiveWebAssembly. De knop roept de UpdateMessage methode aan wanneer deze is geselecteerd. De waarde van message wijzigt en de component wordt opnieuw gerenderd om het bericht in de gebruikersinterface bij te werken.

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!";
    }
}

Als u het voorgaande onderdeel lokaal in een Blazor Web Appgebruikt, plaatst u het onderdeel in de Pages map van het clientproject. Het clientproject is het project van de oplossing met een naam die eindigt op .Client. Wanneer de app wordt uitgevoerd, gaat u naar /render-mode-3 in de adresbalk van de browser.

Automatische (Auto) weergave

Automatische rendering bepaalt hoe de component ten tijde van de uitvoering moet worden weergegeven. Het onderdeel wordt in eerste instantie weergegeven met interactieve server-side rendering (interactieve SSR) met behulp van het Blazor Server hostingmodel. De .NET-runtime- en app-bundel worden op de achtergrond gedownload naar de client en in de cache opgeslagen, zodat ze kunnen worden gebruikt tijdens toekomstige bezoeken.

In de modus Voor automatisch renderen wordt de weergavemodus van een onderdeel dat al op de pagina staat nooit dynamisch gewijzigd. De modus Auto renderen maakt een eerste beslissing over welk type interactiviteit voor een component moet worden gebruikt. Vervolgens behoudt het component dat type interactiviteit zolang het op de pagina staat. Een factor in deze eerste beslissing is te overwegen of onderdelen al bestaan op de pagina met interactiviteit van WebAssembly/Server. De automatische modus geeft de voorkeur aan het selecteren van een rendermodus die overeenkomt met de weergavemodus van bestaande interactieve onderdelen. De reden waarom de automodus liever een bestaande interactiviteitsmodus gebruikt, is om te voorkomen dat er een nieuwe interactieve runtime wordt ingevoerd die de status niet deelt met de bestaande runtime.

Onderdelen die de modus Voor automatisch renderen gebruiken, moeten worden gebouwd op basis van een afzonderlijk clientproject waarmee de Blazor WebAssembly host wordt ingesteld.

In het volgende voorbeeld is het onderdeel interactief gedurende het hele proces. De knop roept de UpdateMessage methode aan wanneer deze is geselecteerd. De waarde van message wijzigt en de component wordt opnieuw gerenderd om het bericht in de gebruikersinterface bij te werken. In eerste instantie wordt het onderdeel interactief van de server weergegeven, maar bij volgende bezoeken wordt het vanaf de client weergegeven nadat de .NET-runtime en app-bundel zijn gedownload en in de cache opgeslagen.

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!";
    }
}

Als u het voorgaande onderdeel lokaal in een Blazor Web Appgebruikt, plaatst u het onderdeel in de Pages map van het clientproject. Het clientproject is het project van de oplossing met een naam die eindigt op .Client. Wanneer de app wordt uitgevoerd, gaat u naar /render-mode-4 in de adresbalk van de browser.

Verspreiding van weergavemodus

Rendermodi verspreiden zich door de componentenhiërarchie.

Regels voor het toepassen van rendermodi:

• De standaardweergavemodus is statisch.
• De interactieve server (InteractiveServer), Interactive WebAssembly (InteractiveWebAssembly) en de weergavemodi Interactive Auto (InteractiveAuto) kunnen worden gebruikt vanuit een onderdeel, waaronder het gebruik van verschillende rendermodi voor onderdelen van hetzelfde niveau.
• U kunt niet overschakelen naar een andere interactieve weergavemodus in een onderliggend onderdeel. Een serveronderdeel kan bijvoorbeeld geen onderliggend onderdeel van een WebAssembly-onderdeel zijn.
• Parameters die worden doorgegeven aan een interactief onderdeel van een kindcomponent van een statische ouder, moeten JSON-serieel zijn. Dit betekent dat u geen weergavefragmenten of onderliggende inhoud van een statische bovenliggende component kunt doorgeven aan een interactieve onderliggende component.

In de volgende voorbeelden wordt een niet-routeerbaar, niet-pagina-SharedMessage onderdeel gebruikt. Het render-modus agnostische onderdeel SharedMessage past geen rendermodus toe met een @attribute instructie. Als u deze scenario's test met een Blazor Web App, plaatst u het volgende onderdeel in de Components map van de app.

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!";
    }
}

Overerven van rendermodus

Als de SharedMessage-component in een statisch gerenderde bovenliggende component wordt geplaatst, wordt de SharedMessage-component ook statisch gerenderd en is deze niet interactief. De knop roept UpdateMessageniet aan en het bericht wordt niet bijgewerkt.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

Als het SharedMessage onderdeel wordt geplaatst in een onderdeel dat de weergavemodus definieert, neemt het de toegepaste rendermodus over.

In het volgende voorbeeld is het SharedMessage-onderdeel interactief via een SignalR verbinding met de client. De knop roept UpdateMessageaan en het bericht wordt bijgewerkt.

RenderMode6.razor:

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

<SharedMessage />

Kindercomponenten met verschillende renderingsmodi

In het volgende voorbeeld worden beide SharedMessage componenten vooraf gerenderd en verschijnen ze wanneer de pagina in de browser wordt weergegeven.

• Het eerste SharedMessage-onderdeel met interactieve server-side rendering (interactieve SSR) wordt interactief nadat het circuit van BlazorSignalR tot stand is gebracht.
• Het tweede SharedMessage-onderdeel met client-side rendering (CSR) is interactief nadat de Blazor app-bundel is gedownload en de .NET-runtime actief is op de client.

RenderMode7.razor:

@page "/render-mode-7"

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

Kindcomponent met een serialiseerbare parameter

In het volgende voorbeeld wordt een interactief kindcomponent getoond dat een parameter gebruikt. Parameters moeten serialiseerbaar zijn.

RenderMode8.razor:

@page "/render-mode-8"

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

Niet-serialiseerbare onderdeelparameters, zoals inhoud van kindelementen of een renderfragment, worden niet ondersteund. In het volgende voorbeeld resulteert het doorgeven van child-inhoud aan de SharedMessage-component in een runtime-fout.

RenderMode9.razor:

@page "/render-mode-9"

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

❌ Fout:

System.InvalidOperationException: kan de parameter ChildContent niet doorgeven aan onderdeel SharedMessage met rendermode InteractiveServerRenderMode. Dit komt doordat de parameter van het gemachtigde type 'Microsoft.AspNetCore.Components.RenderFragment' is, wat willekeurige code is en niet kan worden geserialiseerd.

Hetzelfde gebeurt als u interactieve rendering probeert toe te passen in een indeling die overneemt van LayoutComponentBase, zoals de MainLayout-component van de app, in een app die rendering per pagina of component toepast. Zie ASP.NET Core Blazor indelingenvoor meer informatie.

Om de voorgaande beperking te omzeilen, wikkel je het kindcomponent in een ander component dat de parameter niet heeft. Dit is de benadering die wordt gebruikt in de Blazor Web App projectsjabloon met het Routes onderdeel (Components/Routes.razor) om het Router onderdeel te verpakken.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

In het voorgaande voorbeeld:

• De inhoud van het kind wordt doorgegeven aan het SharedMessage-component zonder een runtimefout te genereren.
• Het SharedMessage-onderdeel wordt interactief weergegeven op de server.

Onderliggend component met een andere weergavemodus dan zijn oudercomponent

Probeer geen andere interactieve weergavemodus toe te passen op een onderliggend onderdeel dan de rendermodus van het bovenliggende onderdeel.

Het volgende onderdeel resulteert in een runtime-fout wanneer het onderdeel wordt weergegeven:

RenderMode11.razor:

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

<SharedMessage @rendermode="InteractiveWebAssembly" />

❌ Fout:

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.

Statische SSR-pagina's in een interactieve app

Er zijn gevallen waarin de specificatie van de app vereist dat onderdelen statische rendering aan de serverzijde (statische SSR) gebruiken en alleen worden uitgevoerd op de server, terwijl de rest van de app gebruikmaakt van een interactieve rendermodus.

Deze aanpak is alleen handig wanneer de app specifieke pagina's heeft die niet kunnen werken met interactieve Server of WebAssembly-rendering. Gebruik deze benadering bijvoorbeeld voor pagina's die afhankelijk zijn van het lezen/schrijven van HTTP-cookies en die alleen kunnen werken in een aanvraag-/antwoordcyclus in plaats van interactieve rendering. Voor pagina's die werken met interactieve rendering, moet u ze niet dwingen om statische SSR te gebruiken, omdat deze minder efficiënt en minder responsief is voor de eindgebruiker.

Markeer elke Razor onderdeelpagina met het attribuut [ExcludeFromInteractiveRouting], toegewezen met de @attributeRazor-richtlijn:

@attribute [ExcludeFromInteractiveRouting]

Wanneer u het kenmerk toepast, zal de navigatie naar de pagina de interactieve routering verlaten. Inkomende navigatie wordt gedwongen een volledige pagina opnieuw te laden in plaats van de pagina via interactieve routering op te lossen. Het opnieuw laden van de volledige pagina dwingt het hoofdonderdeel op het hoogste niveau af, meestal het App onderdeel (App.razor), om opnieuw te laden vanaf de server, zodat de app kan overschakelen naar een andere rendermodus op het hoogste niveau.

Met de RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting extensiemethode kan het onderdeel detecteren of het [ExcludeFromInteractiveRouting] kenmerk wordt toegepast op de huidige pagina.

Gebruik in het App onderdeel het patroon in het volgende voorbeeld:

• Pagina's die niet zijn geannoteerd met het kenmerk [ExcludeFromInteractiveRouting], wisselen standaard naar de InteractiveServer weergavemodus met globale interactiviteit. U kunt InteractiveServer vervangen door InteractiveWebAssembly of InteractiveAuto om een andere standaardmodus voor globale weergave op te geven.
• Pagina's met het kenmerk [ExcludeFromInteractiveRouting] krijgen statische SSR toegewezen (PageRenderMode is toegewezen aan 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;
}

Een alternatief voor het gebruik van de RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting-extensiemethode is het handmatig lezen van metagegevens van eindpunten met behulp van HttpContext.GetEndpoint()?.Metadata.

Klantsideservices falen om te worden opgelost tijdens prerenderen

Ervan uitgaande dat prerendering niet is uitgeschakeld voor een component of voor de app, wordt een component in het .Client-project op de server gerenderd. Omdat de server geen toegang heeft tot client-side geregistreerde Blazor services, is het niet mogelijk om deze services in een onderdeel te injecteren zonder een foutmelding te krijgen dat de service niet kan worden gevonden tijdens het prerenderen.

Denk bijvoorbeeld aan het volgende Home onderdeel in het .Client project in een Blazor Web App met globale interactieve WebAssembly of interactieve automatische weergave. Het onderdeel probeert IWebAssemblyHostEnvironment te injecteren om de naam van de omgeving te verkrijgen.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

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

Er treedt geen compileertijdfout op, maar er treedt een runtimefout op tijdens het prerendering:

Kan geen waarde opgeven voor eigenschap 'Environment' voor het type BlazorSample.Client.Pages.Home'. Er is geen geregistreerde service van het type Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment.

Deze fout treedt op omdat het onderdeel tijdens het prerenderen op de server moet compileren en uitvoeren, maar IWebAssemblyHostEnvironment geen geregistreerde service op de server is.

Als de app de waarde niet nodig heeft tijdens het prerenderen, kan dit probleem worden opgelost door IServiceProvider in te voeren om de service te verkrijgen in plaats van het servicetype zelf:

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

De voorgaande benadering is echter niet nuttig als uw logica een waarde vereist tijdens het prerendering.

U kunt het probleem ook voorkomen als u het prerenderings- voor het onderdeel uitschakelt, maar dat is een extreme maatregel die in veel gevallen moet worden genomen die mogelijk niet voldoet aan de specificaties van uw onderdeel.

Er zijn drie benaderingen die u kunt gebruiken om dit scenario aan te pakken. De volgende zijn van meest aanbevolen tot minst aanbevolen:

• Aanbevolen voor gedeelde frameworkservices: Voor gedeelde frameworkservices die nog niet aan de serverkant geregistreerd zijn in het hoofdproject, registreert u de services in het hoofdproject, waardoor ze beschikbaar zijn tijdens het prerendering. Zie de richtlijnen voor HttpClient services in Een web-API aanroepen vanuit een ASP.NET Core Blazor-appvoor een voorbeeld van dit scenario.

• Aanbevolen voor services buiten het gedeelde framework: Maak een aangepaste service-implementatie voor de service op de server. Gebruik de service normaal gesproken in interactieve onderdelen van het .Client-project. Zie ASP.NET Core Blazor-omgevingenvoor een demonstratie van deze aanpak.

• Maak een serviceabstractie en maak implementaties voor de service in de .Client- en serverprojecten. Registreer de diensten in ieder project. Injecteer de aangepaste service in de component.

• U kunt wellicht een .Client projectpakketverwijzing toevoegen aan een pakket aan de serverzijde en terugvallen op het gebruik van de serverside API bij prerendering op de server.

Ontdekken van componenten uit extra assemblies

Aanvullende assemblies moeten aan het Blazor framework worden bekendgemaakt om routeerbare Razor onderdelen in verwante projecten te detecteren. Zie ASP.NET Core Blazor routering en navigatievoor meer informatie.

Sluiting van circuits wanneer er geen resterende interactieve serveronderdelen zijn

Interactieve Server-onderdelen verwerken webgebruikersinterfacegebeurtenissen met behulp van een realtime-verbinding met de browser die een circuit wordt genoemd. Een circuit en de bijbehorende status worden gemaakt wanneer een interactive server-hoofdonderdeel wordt weergegeven. Het circuit wordt gesloten wanneer er geen resterende interactieve serveronderdelen op de pagina zijn, waardoor serverbronnen worden vrijgemaakt.

Aangepaste korte-handweergavemodi

De @rendermode-instructie gebruikt één parameter die een statisch exemplaar van het type IComponentRenderModeis. Het @rendermode directiekenmerk kan elke instantie van de rendermodus gebruiken, statisch of niet. Het Blazor framework biedt de RenderMode statische klasse met een aantal vooraf gedefinieerde rendermodi voor het gemak, maar u kunt uw eigen klasse maken.

Normaal gesproken gebruikt een onderdeel de volgende @rendermode instructie om prerendering uit te schakelen:

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

Bekijk echter het volgende voorbeeld dat een verkorte interactieve server-side rendermodus creëert zonder prerendering via het _Imports-bestand van de app (Components/_Imports.razor):

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

Gebruik de verkorte weergavemodus in onderdelen in de Components map:

@rendermode InteractiveServerWithoutPrerendering

Een exemplaar van één onderdeel kan ook een aangepaste rendermodus definiëren via een privéveld:

@rendermode interactiveServerWithoutPrerendering

...

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

Op dit moment is de verkorte weergavemodusbenadering waarschijnlijk alleen nuttig om de uitgebreide specificatie van de prerender vlag te verminderen. De verkorte benadering kan in de toekomst nuttiger zijn als er extra vlaggen beschikbaar komen voor interactieve rendering en u korthandig rendermodi wilt maken met verschillende combinaties van vlaggen.

Service-injectie via een importbestand op het hoogste niveau (_Imports.razor)

Deze sectie is alleen van toepassing op Blazor Web Apps.

Een importbestand op het hoogste niveau in de map Components (Components/_Imports.razor) injecteert de verwijzingen naar alle onderdelen in de maphiërarchie, die het App onderdeel (App.razor) bevat. Het App-onderdeel wordt altijd statisch weergegeven, zelfs als prerendering van een paginaonderdeel is uitgeschakeld. Daarom leidt het injecteren van services via het importbestand op het hoogste niveau tot het creëren van twee exemplaren van de service in paginaonderdelen.

Als u dit scenario wilt oplossen, injecteert u de service in een nieuw importbestand dat zich bevindt in de map Pages (Components/Pages/_Imports.razor). Vanaf die locatie wordt de service slechts eenmaal gebruikt in pagina-onderdelen.

Aanvullende informatiebronnen

• WebSocket-compressie
  • richtlijnen voor ASP.NET Core BlazorSignalR
  • Richtlijnen voor bedreigingsbeperking voor ASP.NET Core Blazor interactieve rendering aan de serverzijde
• ASP.NET Core Blazor JavaScript met statische server-side rendering (SSR)
• Trapsgewijze waarden/parameters en weergavemodusgrenzen: zie ook de trapsgewijze waarden op hoofdniveau en trapsgewijze waarden op hoofdniveau met meldingensecties eerder in het artikel.
• ASP.NET Core Razor klassenbibliotheken (RCLs) met statische server-side rendering (statisch SSR)
• Gegevens in Blazor Web Appbeveiligen met interactieve autorendering