ASP.NET Core Blazor återgivningslägen

Den här artikel beskriver kontrollen över Razor-komponentrendering i Blazor Web App-enheter, antingen vid kompileringstid eller körningstid.

Den här vägledningen gäller inte för fristående Blazor WebAssembly appar. Blazor WebAssembly appar renderas endast på klienten via en WebAssembly-baserad runtime på klientsidan och saknar koncept för ett renderingsläge. Om ett återgivningsläge tillämpas på en komponent i en Blazor WebAssembly app har återgivningslägesbeteckningen ingen inverkan på återgivningen av komponenten.

Återgivningslägen

Varje komponent i en Blazor Web App använder ett återgivningsläge för att fastställa vilken värdmodell den använder, var den återges och om den är interaktiv eller inte.

I följande tabell visas de tillgängliga återgivningslägena för att återge Razor-komponenter i en Blazor Web App. Om du vill tillämpa ett återgivningsläge på en komponent använder du @rendermode-direktivet för komponentinstansen eller komponentdefinitionen. Senare i den här artikeln visas exempel för varje scenario för återgivningsläge.

Namn	Beskrivning	Plats för rendering	Interaktiv
Statisk server	Statisk återgivning på serversidan (statisk SSR)	Server	❌ Ingen
Interaktiv server	Interaktiv återgivning på serversidan (interaktiv SSR) med Blazor Server.	Server	✔️ Ja
Interaktiv WebAssembly	Återgivning på klientsidan (CSR) med hjälp av Blazor WebAssembly†.	Klient	✔️ Ja
Interaktiv auto	Interaktiv SSR med Blazor Server först och CSR vid senare besök, efter att Blazor-paketet laddats ned.	Server, sedan klient	✔️ Ja

†Client-side rendering (CSR) antas vara interaktiv. "Interaktiv klientsidesrendering" och "interaktiv CSR" används inte av branschen eller i Blazor dokumentationen."

Prerendering är aktiverat som standard för interaktiva komponenter. Vägledning om hur du kontrollerar prerendering ges senare i den här artikeln. Allmän branschterminologi om klient- och serverrenderingskoncept finns i grunderna för ASP.NET Core Blazor.

I följande exempel visas hur du ställer in komponentens återgivningsläge med några grundläggande Razor komponentfunktioner.

Om du vill testa beteendet för återgivningsläge lokalt kan du placera följande komponenter i en app som skapats från Blazor Web App-projektmallen. När du skapar appen väljer du alternativ från listmenyer (Visual Studio) eller använder CLI-alternativen (.NET CLI) för att aktivera interaktivitet på både serversidan och klientsidan. Information om hur du skapar en Blazor Web Appfinns i Tooling for ASP.NET Core Blazor.

Aktivera stöd för interaktiva återgivningslägen

En Blazor Web App måste konfigureras för att stödja interaktiva återgivningslägen. Följande tillägg tillämpas automatiskt på appar som skapats från Blazor Web App-projektmallen när appen skapas. Enskilda komponenter måste fortfarande deklarera sitt återgivningsläge enligt avsnittet Renderingslägen efter att komponenttjänsterna och slutpunkterna har konfigurerats i appens Program-fil.

Tjänster för Razor komponenter läggs till genom att anropa AddRazorComponents.

Tillägg för komponentbyggare:

• AddInteractiveServerComponents lägger till tjänster som stöd för rendering av interaktiva serverkomponenter.
• AddInteractiveWebAssemblyComponents lägger till tjänster som stöd för rendering av interaktiva WebAssembly-komponenter.

MapRazorComponents identifierar tillgängliga komponenter och anger rotkomponenten för appen (den första komponenten lästes in), vilket som standard är den App komponenten (App.razor).

Endpoint Convention Builder-tillägg:

• AddInteractiveServerRenderMode konfigurerar interaktiv återgivning på serversidan (interaktiv SSR) för appen.
• AddInteractiveWebAssemblyRenderMode konfigurerar interaktiv webassembly-återgivningsläge för appen.

Obs

Om du vill ha orientering om placeringen av API:et i följande exempel kontrollerar du Program filen för en app som genererats från Blazor Web App-projektmallen. Information om hur du skapar en Blazor Web Appfinns i Tooling for ASP.NET Core Blazor.

Exempel 1: Följande Program-fil-API lägger till tjänster och konfiguration för aktivering av interaktiv SSR:

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

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

Exempel 2: Följande Program-fil-API lägger till tjänster och konfiguration för aktivering av interaktiv webassembly-återgivningsläge:

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

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

Exempel 3: Följande Program fil-API lägger till tjänster och konfiguration för aktivering av interaktiva server-, interaktiva webassembly- och interaktiva autoåtergivningslägen:

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

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

Blazor använder Blazor WebAssembly värdmodell för att ladda ned och köra komponenter som använder återgivningsläget Interactive WebAssembly. Ett separat klientprojekt krävs för att konfigurera Blazor WebAssembly värd för dessa komponenter. Klientprojektet innehåller startkoden för Blazor WebAssembly-värden och konfigurerar .NET-runtime för körning i en webbläsare. Mallen Blazor Web App lägger till det här klientprojektet åt dig när du väljer alternativet för att aktivera WebAssembly-interaktivitet. Alla komponenter som använder interaktiv WebAssembly-återgivningsläge bör skapas från klientprojektet, så att de tas med i det nedladdade apppaketet.

Tillämpa ett återgivningsläge på en komponentinstans

Om du vill tillämpa ett återgivningsläge på en komponentinstans använder du attributet @rendermodeRazor direktiv där komponenten används.

I följande exempel tillämpas interaktiv återgivning på serversidan (interaktiv SSR) på den Dialog komponentinstansen:

<Dialog @rendermode="InteractiveServer" />

Not

Blazor mallar innehåller ett statiskt using-direktiv för RenderMode i appens _Imports-fil (Components/_Imports.razor) för kortare @rendermode syntax:

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

Utan föregående direktiv måste komponenterna ange klassen static RenderMode i @rendermode syntax:

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

Du kan också referera till instanser i anpassat återgivningsläge som instansieras direkt med anpassad konfiguration. Mer information finns i avsnittet Anpassade korthandsåtergivningslägen senare i den här artikeln.

Tillämpa ett återgivningsläge på en komponentdefinition

Om du vill ange återgivningsläget för en komponent som en del av definitionen använder du @rendermodeRazor-direktivet och motsvarande renderingslägesattribut.

@page "..."
@rendermode InteractiveServer

Att tillämpa ett återgivningsläge på en komponentdefinition används ofta vid tillämpning av ett återgivningsläge på en specifik sida. Routningsbara sidor använder samma återgivningsläge som den Router komponent som renderade sidan.

Tekniskt sett är @rendermode både ett Razor-direktiv och ett Razor-direktivattribut. Semantiken är liknande, men det finns skillnader. Det @rendermode direktivet finns i komponentdefinitionen, så den refererade instansen för återgivningsläge måste vara statisk. Direktivattributet @rendermode kan ta vilken som helst instans av renderingsläge.

Not

Komponentförfattare bör undvika att koppla en komponents implementering till ett specifikt återgivningsläge. I stället bör komponentförfattare vanligtvis utforma komponenter för att stödja alla återgivningslägen eller värdmodeller. En komponents implementering bör undvika antaganden om var den körs (server eller klient) och bör försämras korrekt när den återges statiskt. Det kan behövas att ange återgivningsläget i komponentdefinitionen om komponenten inte instansieras direkt (till exempel med en dirigerbar sidkomponent) eller om du vill ange ett återgivningsläge för alla komponentinstanser.

Tillämpa ett återgivningsläge på hela appen

Om du vill ange återgivningsläget för hela appen anger du återgivningsläget på den interaktiva komponenten på högsta nivå i appens komponenthierarki som inte är en rotkomponent.

Not

Det går inte att göra en rotkomponent interaktiv, till exempel komponenten App. Det innebär att återgivningsläget för hela appen inte kan ställas in direkt av App komponenten.

För appar som baseras på Blazor Web App projektmall anges vanligtvis ett återgivningsläge som tilldelats hela appen där den Routes komponenten används i komponenten App (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Komponenten Router sprider återgivningsläget till de sidor som den dirigerar.

Du måste också ange samma interaktiva återgivningsläge på HeadOutlet komponenten, som också finns i App komponenten i en Blazor Web App som genereras från projektmallen:

<HeadOutlet @rendermode="InteractiveServer" />

För appar som använder ett interaktivt återgivningsläge på klientsidan (WebAssembly eller Auto) och aktiverar återgivningsläget för hela appen via komponenten Routes:

• Placera eller flytta layout- och navigeringsfilerna i serverappens Components/Layout mapp till .Client-projektets Layout mapp. Skapa en Layout mapp i .Client-projektet om den inte finns.
• Placera eller flytta komponenterna i serverappens Components/Pages mapp till .Client-projektets Pages mapp. Skapa en Pages mapp i .Client-projektet om den inte finns.
• Placera eller flytta Routes komponenten i serverappens Components mapp till rotmappen för .Client-projektet.

Så här aktiverar du global interaktivitet när du skapar en Blazor Web App:

• Ställ in interaktivitetsplatsens listruta till Globali Visual Studio.
• .NET CLI: Använd alternativet -ai|--all-interactive.

Mer information finns i Tooling for ASP.NET Core Blazor.

Tillämpa ett återgivningsläge programatiskt

Egenskaper och fält kan tilldela ett återgivningsläge.

Den andra metoden som beskrivs i det här avsnittet, som anger återgivningsläget efter komponentinstans, är särskilt användbar när din appspecifikation kräver att en eller flera komponenter använder statisk SSR i en annars interaktiv app. Det här scenariot beskrivs på Static SSR-sidor i sektionen för interaktiv app senare i den här artikeln.

Ange återgivningsläget efter komponentdefinition

En komponentdefinition kan definiera ett återgivningsläge via ett privat fält:

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

Ange återgivningsläget efter komponentinstans

I följande exempel tillämpas interaktiv återgivning på serversidan (interaktiv SSR) på alla begäranden.

<Routes @rendermode="PageRenderMode" />

...

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

Ytterligare information om spridning av återgivningsläge finns i avsnittet Spridning av återgivningsläge senare i den här artikeln. Avsnittet Static SSR i en interaktiv app visar hur du kan använda den tidigare nämnda metoden för att införa statisk SSR i en annars interaktiv app.

Identifiera återgivningsplats, interaktivitet och tilldelat återgivningsläge vid körning

Egenskaperna ComponentBase.RendererInfo och ComponentBase.AssignedRenderMode gör det möjligt för appen att identifiera information om en komponents plats, interaktivitet och tilldelade återgivningsläge:

• RendererInfo.Name returnerar platsen där komponenten körs:
  • Static: På servern (SSR) och oförmögen till interaktivitet.
  • Server: På servern (SSR) och som kan interaktivitet efter prerendering.
  • WebAssembly: På klienten (CSR) och kan interagera efter prerendering.
  • WebView: På den lokala enheten och är kapabel till interaktivitet efter förprerendering.
• RendererInfo.IsInteractive anger om komponenten stöder interaktivitet vid tidpunkten för återgivningen. Värdet är true vid återgivning interaktivt eller false vid förrendering eller för statisk SSR (RendererInfo.Name av Static).
• AssignedRenderMode exponerar komponentens tilldelade återgivningsläge:
  • InteractiveServerRenderMode för interaktiv server.
  • InteractiveAutoRenderMode för interaktiv automatik.
  • InteractiveWebAssemblyRenderMode för Interactive WebAssembly.
  • null om ett återgivningsläge inte har tilldelats.

Komponenter använder dessa egenskaper för att återge innehåll beroende på deras plats eller interaktivitetsstatus. Följande exempel visar typiska användningsfall.

Visa innehåll tills en komponent är interaktiv:

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

Inaktivera en knapp tills en komponent är interaktiv:

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

Inaktivera ett formulär under förinläsningen och aktivera formuläret när komponenten är interaktiv:

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

Rendera markering som stöd för att utföra en vanlig HTML-åtgärd om komponenten återges statiskt:

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

I föregående exempel:

• När värdet för AssignedRenderMode är nullantar komponenten statisk SSR. Blazor händelsehantering fungerar inte i en webbläsare med statisk SSR, så komponenten skickar ett formulär (GET-begäran) med en titleFilter frågesträng inställd på användarens <input> värde. Komponenten Movie (/movie) kan läsa frågesträngen och bearbeta värdet för titleFilter för att återge komponenten med filtrerade resultat.
• Annars är återgivningsläget något av InteractiveServer, InteractiveWebAssemblyeller InteractiveAuto. Komponenten kan använda ett händelsehanterar-delegat (FilterMovies) och värdet som är bundet till <input>-elementet (titleFilter) för att filtrera filmer interaktivt i bakgrundsanslutningen SignalR.

Blazor dokumentationsexempel för Blazor Web Apps

När du använder en Blazor Web Appkräver de flesta Blazor dokumentationsexempelkomponenter interaktivitet för att fungera och demonstrera de begrepp som beskrivs i artiklarna. När du testar en exempelkomponent som tillhandahålls av en artikel kontrollerar du att appen antingen använder global interaktivitet eller att komponenten använder ett interaktivt återgivningsläge.

Förberendring

Prerendering är processen att först återge sidinnehåll på servern utan att aktivera händelsehanterare för renderade kontroller. Servern matar ut HTML-användargränssnittet på sidan så snart som möjligt som svar på den första begäran, vilket gör att appen känns mer dynamisk för användarna. Prerendering kan också förbättra sökmotoroptimering (SEO) genom att återge innehåll för det första HTTP-svaret som sökmotorer använder för att beräkna sidrankning.

Prerendering är aktiverat som standard för interaktiva komponenter.

Intern navigering för interaktiv routning innebär inte att begära nytt sidinnehåll från servern. Därför sker inte prerendering för interna sidbegäranden, inklusive förbättrad navigering . För mer information, se statisk kontra interaktiv routing, interaktiv routing och förberendering, och förbättrad navigation och formulärhantering.

Inaktivering av prerendering med hjälp av följande tekniker börjar bara gälla för återgivningslägen på den översta nivån. Om en överordnad komponent anger ett återgivningsläge ignoreras förinställningarna för dess underordnade komponenter. Det här beteendet är under utredning för eventuella ändringar med lanseringen av .NET 10 i november 2025.

Om du vill inaktivera prerendering för en komponentinstansskickar du flaggan prerender med värdet false till återgivningsläget:

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

För att inaktivera prerendering i en komponentdefinition :

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

Om du vill inaktivera prerendering för hela appen anger du återgivningsläget på den interaktiva komponenten på högsta nivå i appens komponenthierarki som inte är en rotkomponent.

För appar som baseras på Blazor Web App projektmall anges ett återgivningsläge som tilldelats hela appen där komponenten Routes används i komponenten App (Components/App.razor). I följande exempel anges appens återgivningsläge till Interaktiv server med prerendering inaktiverad:

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

Inaktivera även prerendering för HeadOutlet-komponenten i komponenten App:

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

Det går inte att göra en rotkomponent, till exempel den App komponenten, interaktiv med @rendermode-direktivet överst i rotkomponentens definitionsfil (.razor). Därför kan prerendering inte inaktiveras direkt av komponenten App.

Statisk återgivning på serversidan (statisk SSR)

Komponenter använder statisk återgivning på serversidan (statisk SSR). Komponenten renderas till svarsströmmen och interaktivitet är inte aktiverad.

I följande exempel finns det ingen beteckning för komponentens återgivningsläge, så komponenten ärver återgivningsläget från det överordnade objektet. Eftersom ingen överordnad komponent anger ett återgivningsläge återges följande komponent statiskt på servern. Knappen är inte interaktiv och anropar inte metoden UpdateMessage när den väljs. Värdet för message ändras inte och komponenten återskapas inte som svar på användargränssnittshändelser.

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

Om du använder den föregående komponenten lokalt i en Blazor Web Appplacerar du komponenten i serverprojektets Components/Pages mapp. Serverprojektet är lösningens projekt med ett namn som inte slutar med .Client. När appen körs navigerar du till /render-mode-1 i webbläsarens adressfält.

Under statisk SSR bearbetas Razor-komponentsidans begäranden av server-sidans ASP.NET Core mellansystemspipeline för dirigering och auktorisering. Dedikerade Blazor funktioner för routning och auktorisering fungerar inte eftersom Razor komponenter inte återges under bearbetning av begäran på serversidan. Funktioner i Blazor-routern i Routes-komponenten som inte är tillgängliga under statisk SSR inkluderar att visa:

• Inte auktoriserat innehåll (<NotAuthorized>...</NotAuthorized>) (NotAuthorized): Blazor Web Apps behandlar vanligtvis obehöriga begäranden på servern genom att anpassa beteendet för Authorization Middleware.

• Inte hittat innehåll (<NotFound>...</NotFound>) (NotFound): Blazor Web Apps bearbetar vanligtvis felaktiga URL-begäranden på servern genom att antingen visa webbläsarens inbyggda 404-användargränssnitt eller returnera en anpassad 404-sida (eller annat svar) via ASP.NET Core-mellanprogram (till exempel UseStatusCodePagesWithRedirects / API-dokumentation). Mer information finns i Skapa ett enklare sätt att visa användargränssnittet not found 404 med Blazor (dotnet/aspnetcore #45654).

Om appen uppvisar interaktivitet på rotnivå, sker ingen bearbetning av ASP.NET Core-begäranden på serversidan efter den initiala statiska SSR:en, vilket betyder att föregående Blazor-funktioner fungerar som förväntat.

Förbättrad navigering med statisk SSR kräver särskild uppmärksamhet vid inläsning av JavaScript. Mer information finns i ASP.NET Core Blazor JavaScript med statisk återgivning på serversidan (statisk SSR).

Interaktiv återgivning på serversidan (interaktiv SSR)

Interaktiv återgivning på serversidan (interaktiv SSR) återger komponenten interaktivt från servern med hjälp av Blazor Server. Användarinteraktioner hanteras via en realtidsanslutning till webbläsaren. Kretsanslutningen upprättas när serverkomponenten renderas.

I följande exempel ställs återgivningsläget in på interaktiv SSR genom att lägga till @rendermode InteractiveServer i komponentdefinitionen. Knappen anropar metoden UpdateMessage när den väljs. Värdet för message ändras och komponenten återskapas för att uppdatera meddelandet i användargränssnittet.

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

Om du använder den föregående komponenten i en Blazor Web Appplacerar du komponenten i serverprojektets Components/Pages mapp. Serverprojektet är lösningens projekt med ett namn som inte slutar med .Client. När appen körs navigerar du till /render-mode-2 i webbläsarens adressfält.

Återgivning på klientsidan (CSR)

Återgivning på klientsidan (CSR) återger komponenten interaktivt på klienten med hjälp av Blazor WebAssembly. .NET-körnings- och apppaketet laddas ned och cachelagras när WebAssembly-komponenten ursprungligen renderas. Komponenter som använder CSR måste skapas från ett separat klientprojekt som konfigurerar Blazor WebAssembly-värden.

I följande exempel är återgivningsläget inställt på CSR med @rendermode InteractiveWebAssembly. Knappen anropar metoden UpdateMessage när den väljs. Värdet för message ändras och komponenten återskapas för att uppdatera meddelandet i användargränssnittet.

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

Om du använder den föregående komponenten lokalt i en Blazor Web Appplacerar du komponenten i klientprojektets Pages mapp. Klientprojektet är lösningens projekt med ett namn som slutar i .Client. När appen körs navigerar du till /render-mode-3 i webbläsarens adressfält.

Automatisk (Auto) återgivning

Automatisk återgivning bestämmer hur komponenten ska återges vid körtid. Komponenten återges ursprungligen med interaktiv återgivning på serversidan (interaktiv SSR) med hjälp av Blazor Server värdmodell. .NET-runtime- och apppaketet laddas ned till klienten i bakgrunden och cachelagras så att de kan användas vid framtida besök.

Återgivningsläget Auto ändrar aldrig dynamiskt återgivningsläget för en komponent som redan är på sidan. Läget Automatisk återgivning fattar ett första beslut om vilken typ av interaktivitet som ska användas för en komponent. Komponenten behåller sedan den typen av interaktivitet så länge den finns på sidan. En faktor i det här första beslutet är att överväga om komponenter redan finns på sidan med webassembly/serverinteraktivitet. Automatiskt läge föredrar att välja ett återgivningsläge som matchar återgivningsläget för befintliga interaktiva komponenter. Anledningen till att Auto-läget föredrar att använda ett befintligt interaktivitetsläge är att undvika att införa en ny interaktiv miljö som inte delar tillstånd med den befintliga miljön.

Komponenter som använder det automatiska återgivningsläget måste byggas från ett separat klientprojekt som konfigurerar Blazor WebAssembly-värden.

I följande exempel är komponenten interaktiv under hela processen. Knappen anropar metoden UpdateMessage när den väljs. Värdet för message ändras och komponenten återskapas för att uppdatera meddelandet i användargränssnittet. Till en början återges komponenten interaktivt från servern, men vid efterföljande besök återges den från klienten efter att .NET-körningen och apppaketet har laddats ned och cachelagrats.

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

Om du använder den föregående komponenten lokalt i en Blazor Web Appplacerar du komponenten i klientprojektets Pages mapp. Klientprojektet är lösningens projekt med ett namn som slutar i .Client. När appen körs navigerar du till /render-mode-4 i webbläsarens adressfält.

Spridning av återgivningsläge

Återgivningslägen sprids nedåt i komponenthierarkin.

Regler för att tillämpa återgivningslägen:

• Standardåtergivningsläget är Statiskt.
• Återgivningslägena Interactive Server (InteractiveServer), Interactive WebAssembly (InteractiveWebAssembly) och Interactive Auto (InteractiveAuto) kan användas från en komponent, inklusive användning av olika återgivningslägen för syskonkomponenter.
• Du kan inte byta till ett annat interaktivt återgivningsläge i en barnkomponent. En serverkomponent kan till exempel inte vara underordnad en WebAssembly-komponent.
• Parametrar som skickas till en interaktiv underkomponent från en statisk överordnad måste vara JSON-serialiserbara. Det innebär att du inte kan skicka renderingsfragment eller barninnehåll från en statisk föräldrakomponent till en interaktiv barnkomponent.

I följande exempel används en icke-sidbar SharedMessage-komponent. Den komponent som är agnostisk för återgivningsläge, SharedMessage, tillämpar inte ett återgivningsläge med @attribute direktiv. Om du testar dessa scenarier med en Blazor Web Appplacerar du följande komponent i appens Components mapp.

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

Arv av renderingsläge

Om komponenten SharedMessage placeras i en statiskt renderad överordnad komponent återges SharedMessage komponenten också statiskt och är inte interaktiv. Knappen anropar inte UpdateMessageoch meddelandet uppdateras inte.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

Om komponenten SharedMessage placeras i en komponent som definierar återgivningsläget ärver den det tillämpade återgivningsläget.

I följande exempel är komponenten SharedMessage interaktiv över en SignalR anslutning till klienten. Knappen anropar UpdateMessageoch meddelandet uppdateras.

RenderMode6.razor:

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

<SharedMessage />

Barnkomponenter med olika återgivningslägen

I följande exempel är båda SharedMessage komponenter förinstallerade och visas när sidan visas i webbläsaren.

• Den första SharedMessage-komponenten med interaktiv återgivning på serversidan (interaktiv SSR) blir interaktiv efter att Blazor:s SignalR-krets har upprättats.
• Den andra SharedMessage komponenten med återgivning på klientsidan (CSR) är interaktiv efter attBlazor apppaketet har laddats ned och .NET-körningen är aktiv på klienten.

RenderMode7.razor:

@page "/render-mode-7"

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

Underordnad komponent med en serialiserbar parameter

I följande exempel visas en interaktiv barnkomponent som tar en parameter. Parametrarna måste vara serialiserbara.

RenderMode8.razor:

@page "/render-mode-8"

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

Ickeserialiserbara komponentparametrar, till exempel underordnat innehåll eller ett renderingsfragment, stöds inte. I följande exempel resulterar överföring av underordnat innehåll till den SharedMessage komponenten i ett körningsfel.

RenderMode9.razor:

@page "/render-mode-9"

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

❌ Fel:

System.InvalidOperationException: Det går inte att skicka parametern "ChildContent" till komponenten "SharedMessage" med rendermode "InteractiveServerRenderMode". Det beror på att parametern är av delegattypen "Microsoft.AspNetCore.Components.RenderFragment", som är godtycklig kod och inte kan serialiseras.

Om du vill kringgå föregående begränsning omsluter du den underordnade komponenten i en annan komponent som inte har parametern. Det här är den metod som används i Blazor Web App-projektmallen med komponenten Routes (Components/Routes.razor) för att omsluta Router komponenten.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

I föregående exempel:

• Det underordnade innehållet skickas till komponenten SharedMessage utan att orsaka något körningsfel.
• Komponenten SharedMessage återges interaktivt på servern.

Underordnad komponent med ett renderingsläge som skiljer sig från det överordnade

Försök inte tillämpa ett annat interaktivt återgivningsläge på en underordnad komponent än dess överordnade återgivningsläge.

Följande komponent leder till ett körningsfel när komponenten renderas:

RenderMode11.razor:

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

<SharedMessage @rendermode="InteractiveWebAssembly" />

❌ Fel:

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.

Statiska SSR-sidor i en interaktiv app

Det finns fall där appens specifikation kräver att komponenter använder statisk återgivning på serversidan (statisk SSR) och endast körs på servern, medan resten av appen använder ett interaktivt återgivningsläge.

Den här metoden är bara användbar när appen har specifika sidor som inte kan fungera med interaktiv server- eller WebAssembly-återgivning. Anta till exempel den här metoden för sidor som är beroende av att läsa/skriva HTTP-cookies och som bara kan fungera i en begäran/svar-cykel i stället för interaktiv återgivning. För sidor som fungerar med interaktiv rendering bör du inte tvinga dem att använda statisk SSR, eftersom det är mindre effektivt och mindre dynamiskt för slutanvändaren.

Markera alla Razor komponentsidor med attributet [ExcludeFromInteractiveRouting] tilldelat med @attributeRazor-direktivet:

@attribute [ExcludeFromInteractiveRouting]

Om attributet tillämpas avslutas navigeringen på sidan från interaktiv routning. Inkommande navigering är tvungen att genomföra en fullsidesåterladdning i stället för att lösa sidan via interaktiv ruttning. Omstart av hela sidan tvingar den översta rotkomponenten, vanligtvis App-komponenten (App.razor), att laddas om från servern, vilket gör att appen kan växla till ett annat renderingsläge på hög nivå.

Med RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting-tilläggsmetoden kan komponenten identifiera om [ExcludeFromInteractiveRouting]-attributet tillämpas på den aktuella sidan.

I komponenten App använder du mönstret i följande exempel:

• Sidor som inte annoteras med attributet [ExcludeFromInteractiveRouting] har som standardinställning återgivningsläget InteractiveServer med global interaktivitet. Du kan ersätta InteractiveServer med InteractiveWebAssembly eller InteractiveAuto för att ange ett annat globalt standardåtergivningsläge.
• Sidor som har kommenterats med attributet [ExcludeFromInteractiveRouting] antar statisk SSR (PageRenderMode tilldelas 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;
}

Ett alternativ till att använda RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting-tilläggsmetoden är att läsa slutpunktsmetadata manuellt med hjälp av HttpContext.GetEndpoint()?.Metadata.

Tjänster på klientsidan kan inte lösas under förinläsning

Förutsatt att prerendering inte är inaktiverat för en komponent eller för appen, förinstalleras en komponent i .Client-projektet på servern. Eftersom servern inte har åtkomst till registrerade Blazor tjänster på klientsidan går det inte att mata in dessa tjänster i en komponent utan att få ett felmeddelande om att tjänsten inte kan hittas under förinläsningen.

Tänk dig till exempel den följande Home-komponenten i .Client-projektet i en Blazor Web App med global interaktiv WebAssembly eller automatisk interaktiv återgivning. Komponenten försöker mata in IWebAssemblyHostEnvironment för att hämta miljöns namn.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

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

Inget kompileringstidsfel inträffar, men ett körningsfel inträffar under förinläsningen:

Det går inte att ange ett värde för egenskapen "Miljö" på typen "BlazorSample.Client.Pages".Home". Det finns ingen registrerad tjänst av typen "Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment".

Det här felet beror på att komponenten måste kompileras och köras på servern under förinläsningen, men IWebAssemblyHostEnvironment inte är en registrerad tjänst på servern.

Om appen inte kräver värdet under prerendering kan det här problemet lösas genom att mata in IServiceProvider för att hämta tjänsten i stället för själva tjänsttypen:

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

Den föregående metoden är dock inte användbar om logiken kräver ett värde under förinläsningen.

Du kan också undvika problemet om du inaktiverar förhandsrendering för komponenten, men det är en extrem åtgärd att vidta i många fall som inte nödvändigtvis uppfyller komponentens specifikationer.

Det finns tre metoder som du kan använda för att hantera det här scenariot. Följande listas från de mest rekommenderade till minst rekommenderade:

• Rekommenderade för delade ramverkstjänster: För delade ramverkstjänster som bara inte är registrerade på serversidan i huvudprojektet registrerar du tjänsterna i huvudprojektet, vilket gör dem tillgängliga under förinläsningen. Ett exempel på det här scenariot finns i vägledningen för HttpClient tjänster i Anropa ett webb-API från en ASP.NET Core Blazor-app.

• Rekommenderade för tjänster utanför det delade ramverket: Skapa en anpassad tjänstimplementering för tjänsten på servern. Använd tjänsten normalt i interaktiva komponenter i .Client-projektet. En demonstration av den här metoden finns i ASP.NET Core Blazor-miljöer.

• Skapa en tjänstabstraktion och skapa implementeringar för tjänsten i .Client- och serverprojekten. Registrera tjänsterna i varje projekt. Mata in den anpassade tjänsten i komponenten.

• Du kanske kan lägga till en .Client projektpaketreferens till ett paket på serversidan och återgå till att använda API:et på serversidan när du förinstallerar på servern.

Identifiera komponenter från ytterligare sammansättningar

Ytterligare sammansättningar måste lämnas ut till det Blazor ramverket för att identifiera dirigerbara Razor komponenter i refererade projekt. Mer information finns i ASP.NET Core Blazor routning och navigering.

Stängning av kretsar när det inte finns några återstående interaktiva serverkomponenter

Interaktiva serverkomponenter hanterar webbgränssnittshändelser med hjälp av en realtidsanslutning med webbläsaren som kallas en krets. En krets och dess associerade tillstånd skapas när en interaktiv rotserverkomponent återges. Kretsen stängs när det inte finns några återstående interaktiva serverkomponenter på sidan, vilket frigör serverresurser.

Anpassade korthandsåtergivningslägen

@rendermode-direktivet tar en enda parameter som är en statisk instans av typen IComponentRenderMode. Direktivattributet @rendermode kan ta alla instanser av rendermodus, vare sig de är statiska eller inte. Det Blazor ramverket tillhandahåller RenderMode statisk klass med vissa fördefinierade återgivningslägen för enkelhetens skull, men du kan skapa egna.

Normalt använder en komponent följande @rendermode-direktiv för att inaktivera prerendering:

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

Tänk dig dock följande exempel som skapar ett förkortat interaktivt renderingsläge på serversidan utan föråtergivning via appens _Imports-fil (Components/_Imports.razor):

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

Använd korthandsåtergivningsläget i komponenter i mappen Components:

@rendermode InteractiveServerWithoutPrerendering

Alternativt kan en enskild komponentinstans definiera ett anpassat återgivningsläge via ett privat fält:

@rendermode interactiveServerWithoutPrerendering

...

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

För närvarande är metoden för korthandsåtergivningsläge förmodligen bara användbar för att minska utförligheten i att ange flaggan prerender. Den korta metoden kan vara mer användbar i framtiden om ytterligare flaggor blir tillgängliga för interaktiv återgivning och du vill skapa korta återgivningslägen med olika kombinationer av flaggor.

Tjänstinmatning via en importfil på toppnivå (_Imports.razor)

Det här avsnittet gäller endast Blazor Web Apps.

En importfil på den översta nivån i mappen Components (Components/_Imports.razor) matar in sina referenser i alla komponenter i mapphierarkin, som innehåller komponenten App (App.razor). Komponenten App återges alltid statiskt även om för en sidkomponent är inaktiverad. Genom att mata in tjänster via den översta importfilen kan du därför lösa två instanser av tjänsten i sidkomponenter.

Åtgärda det här scenariot genom att mata in tjänsten i en ny importfil som placeras i mappen Pages (Components/Pages/_Imports.razor). Från denna plats löses tjänsten bara en gång för sidkomponenterna.

Ytterligare resurser

• WebSocket-komprimering
  • ASP.NET Core BlazorSignalR vägledning
  • Vägledning för hotreducering för ASP.NET Core Blazor interaktiv återgivning på serversidan
• ASP.NET Core Blazor JavaScript med statisk återgivning på serversidan (statisk SSR)
• Kaskadvärden/parametrar och gränser för återgivningslägen: Se även avsnittet Kaskadparametrar på rotnivå tidigare i artikeln.
• ASP.NET Core Razor-klassbibliotek (RCL) med statisk återgivning på serversidan (statisk SSR)