Sdílet prostřednictvím

režimy vykreslování ASP.NET Core Blazor

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Tento článek vysvětluje řízení Razor vykreslování součástí v Blazor Web Apps, a to buď v době kompilace, nebo za běhu.

Tyto pokyny se nevztahují na samostatné Blazor WebAssembly aplikace. Blazor WebAssembly aplikace se vykreslují pouze na klientovi prostřednictvím modulu runtime založeného na webAssembly na straně klienta a nemají žádný koncept režimu vykreslování. Pokud je režim vykreslení použit pro komponentu Blazor WebAssembly v aplikaci, označení režimu vykreslení nemá žádný vliv na vykreslení komponenty.

Režimy vykreslování

Každá komponenta v rámci Blazor Web App přechodu na režim vykreslení určuje model hostování, který používá, kde se vykresluje a jestli je interaktivní.

Následující tabulka uvádí dostupné režimy vykreslování pro vykreslovací Razor součásti v nástroji Blazor Web App. Chcete-li použít režim vykreslování na komponentu @rendermode , použijte direktivu na instanci komponenty nebo v definici komponenty. Dále v tomto článku jsou uvedeny příklady pro každý scénář režimu vykreslování.

Název Popis Umístění vykreslení Interaktivní
Statický server Statické vykreslování na straně serveru (statické SSR) Server
Interaktivní server Interaktivní vykreslování na straně serveru (interaktivní SSR) pomocí Blazor Server. Server
Interactive WebAssembly Vykreslování na straně klienta (CSR) pomocí Blazor WebAssembly† Klient
Interaktivní automatické Interaktivní SSR s využitím Blazor Server počátečního a následného převzetí služeb při následné návštěvě po Blazor stažení sady. Server, pak klient

† Vykreslování na straně klienta (CSR) se předpokládá jako interaktivní. "Interaktivní vykreslování na straně klienta" a "interaktivní CSR" se nepoužívají v oboru ani v Blazor dokumentaci.

U interaktivních komponent je ve výchozím nastavení povolené předkreslování. Pokyny k řízení předrenderingu najdete dále v tomto článku. Obecné oborové terminologie týkající se konceptů vykreslování klientů a serverů najdete v tématu ASP.NET Základy jádraBlazor.

Následující příklady ukazují nastavení režimu vykreslování komponenty s několika základními Razor funkcemi komponent.

Pokud chcete chování režimu vykreslování otestovat místně, můžete do aplikace vytvořené ze Blazor Web App šablony projektu umístit následující komponenty. Při vytváření aplikace vyberte možnosti z rozevíracích nabídek (Visual Studio) nebo použijte možnosti rozhraní příkazového řádku (.NET CLI) a povolte interaktivitu na straně serveru i na straně klienta. Pokyny k vytvoření Blazor Web Appnajdete v tématu Nástroje pro ASP.NET Core Blazor.

Povolení podpory interaktivních režimů vykreslování

Musí Blazor Web App být nakonfigurována tak, aby podporovala režimy interaktivního vykreslování. Následující rozšíření se automaticky použijí pro aplikace vytvořené ze Blazor Web App šablony projektu během vytváření aplikace. Jednotlivé komponenty jsou stále nutné k deklarování jejich režimu vykreslování podle části Režimy vykreslování po konfiguraci služeb komponent a koncových bodů v souboru aplikace Program .

Služby pro Razor komponenty se přidávají voláním AddRazorComponents.

Rozšíření tvůrce komponent:

MapRazorComponents zjistí dostupné komponenty a určuje kořenovou komponentu aplikace (první načtenou komponentu App ), která je ve výchozím nastavení součástí (App.razor).

Rozšíření tvůrce konvencí koncových bodů:

Poznámka:

Orientaci na umístění rozhraní API v následujících příkladech najdete Program v souboru aplikace vygenerované ze Blazor Web App šablony projektu. Pokyny k vytvoření Blazor Web Appnajdete v tématu Nástroje pro ASP.NET Core Blazor.

Příklad 1: Následující Program souborové rozhraní API přidává služby a konfiguraci pro povolení interaktivního SSR:

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

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

Příklad 2: Následující Program souborové rozhraní API přidá služby a konfiguraci pro povolení režimu interaktivního vykreslování WebAssembly:

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

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

Příklad 3: Následující souborové Program rozhraní API přidává služby a konfiguraci pro povolení režimu interaktivního serveru, interaktivního webassembly a interaktivního automatického vykreslování:

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

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

BlazorBlazor WebAssembly používá model hostování ke stažení a spouštění komponent, které používají režim vykreslování Interactive WebAssembly. K nastavení Blazor WebAssembly hostování pro tyto komponenty se vyžaduje samostatný klientský projekt. Klientský projekt obsahuje spouštěcí kód hostitele Blazor WebAssembly a nastaví modul runtime .NET pro spuštění v prohlížeči. Šablona Blazor Web App přidá tento klientský projekt za vás, když vyberete možnost pro povolení interaktivity WebAssembly. Všechny komponenty využívající režim vykreslování Interactive WebAssembly by měly být sestaveny z klientského projektu, takže se zahrnou do stažené sady aplikací.

Použití režimu vykreslování na instanci komponenty

Pokud chcete použít režim vykreslování na instanci komponenty, použijte atribut direktivyRazor@rendermode, ve kterém se komponenta používá.

V následujícím příkladu se u Dialog instance komponenty použije interaktivní vykreslování na straně serveru (interaktivní SSR):

<Dialog @rendermode="InteractiveServer" />

Poznámka:

Blazor šablony obsahují statickou using direktivu pro RenderMode soubor aplikace _Imports (Components/_Imports.razor) pro kratší @rendermode syntaxi:

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

Bez předchozí direktivy musí komponenty specifikovat statickou RenderMode třídu v @rendermode syntaxi:

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

Instance režimu vlastního vykreslování můžete také odkazovat přímo s vlastní konfigurací. Další informace najdete v části Vlastní režimy vykreslování zkrácených rukou dále v tomto článku.

Použití režimu vykreslování u definice komponenty

Chcete-li určit režim vykreslování pro komponentu jako součást jeho definice, použijte @rendermodeRazor direktivu a odpovídající atribut režimu vykreslování.

@page "..."
@rendermode InteractiveServer

Použití režimu vykreslení na definici komponenty se běžně používá při použití režimu vykreslování na konkrétní stránku. Směrovatelné stránky používají stejný režim vykreslování jako komponenta Router , která stránku vykreslovala.

Technicky vzato @rendermode je direktiva RazorRazori atribut direktivy. Sémantika je podobná, ale existují rozdíly. Direktiva @rendermode je v definici komponenty, takže odkazovaná instance režimu vykreslování musí být statická. Atribut @rendermode direktivy může převzít libovolnou instanci režimu vykreslování.

Poznámka:

Autoři komponent by se měli vyhnout párování implementace komponenty s konkrétním režimem vykreslování. Autoři komponent by měli obvykle navrhovat komponenty tak, aby podporovaly jakýkoli režim vykreslování nebo model hostování. Implementace komponenty by se měla vyhnout předpokladům na tom, kde běží (server nebo klient) a při statickém vykreslení by měla být degradovaná. Určení režimu vykreslování v definici komponenty může být potřeba, pokud se komponenta nes instancí přímo (například u směrovatelné součásti stránky) nebo pro všechny instance komponent určí režim vykreslování.

Použití režimu vykreslování pro celou aplikaci

Pokud chcete nastavit režim vykreslování pro celou aplikaci, nastavte režim vykreslení v interaktivní komponentě nejvyšší úrovně v hierarchii komponent aplikace, která není kořenovou komponentou.

Poznámka:

Interaktivní vytvoření kořenové komponenty, například App komponenty, není podporováno. Režim vykreslování pro celou aplikaci proto nelze nastavit přímo komponentou App .

U aplikací založených na Blazor Web App šabloně projektu se obvykle určuje režim vykreslování přiřazený k celé aplikaci, kde Routes se komponenta používá v App dané komponentě (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Komponenta Router rozšíří svůj režim vykreslování na stránky, které směruje.

Obvykle také musíte nastavit stejný interaktivní režim vykreslování na komponentěHeadOutlet, která se nachází také v App komponentě Blazor Web App vygenerované ze šablony projektu:

<HeadOutlet @rendermode="InteractiveServer" />

U aplikací, které přecházejí na interaktivní režim vykreslování na straně klienta (WebAssembly nebo Auto) a umožňují režim vykreslování pro celou aplikaci prostřednictvím Routes komponenty:

  • Umístěte nebo přesuňte rozložení a navigační soubory složky serverové aplikace Components/Layout do .Client složky projektu Layout . Pokud složka v .Client projektu neexistuje, vytvořte Layout ji.
  • Umístěte nebo přesuňte komponenty složky serverové aplikace Components/Pages do .Client složky projektu Pages . Pokud složka v .Client projektu neexistuje, vytvořte Pages ji.
  • Umístěte nebo přesuňte Routes komponentu složky serverové aplikace Components do .Client kořenové složky projektu.

Povolení globální interaktivity při vytváření Blazor Web App:

  • Visual Studio: Nastavte rozevírací seznam umístění interaktivity na Globální.
  • .NET CLI: Použijte možnost -ai|--all-interactive .

Další informace naleznete v tématu Nástroje pro ASP.NET Core Blazor.

Programové použití režimu vykreslování

Vlastnosti a pole mohou přiřadit režim vykreslování.

Druhý přístup popsaný v této části, nastavení režimu vykreslování podle instance komponenty, je zvlášť užitečné, když specifikace aplikace volá jednu nebo více komponent k přijetí statického SSR v globálně interaktivní aplikaci. Tento scénář je popsaný na stránkách Statického serveru SSR v globálně interaktivní části aplikace dále v tomto článku.

Nastavení režimu vykreslování podle definice komponenty

Definice komponenty může definovat režim vykreslování prostřednictvím soukromého pole:

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

Nastavení režimu vykreslování podle instance komponenty

Následující příklad použije interaktivní vykreslování na straně serveru (interaktivní SSR) na libovolný požadavek.

<Routes @rendermode="PageRenderMode" />

...

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

Další informace o šíření režimu vykreslování najdete v části Šíření režimu vykreslování dále v tomto článku. Stránky Statického serveru SSR v globálně interaktivní části aplikace ukazují, jak použít předchozí přístup k přijetí statického SSR v globálně interaktivní aplikaci.

Zjišťování umístění vykreslování, interaktivity a přiřazeného režimu vykreslování za běhu

Aplikace ComponentBase.RendererInfo a ComponentBase.AssignedRenderMode vlastnosti umožňují zjistit podrobnosti o umístění, interaktivitě a přiřazené režimu vykreslování komponenty:

  • RendererInfo.Name vrátí umístění, kde komponenta provádí:
    • Static: Na serveru (SSR) a nemožnost interaktivity.
    • Server: Na serveru (SSR) a schopný interaktivitu po předběžném provedení.
    • WebAssembly: Klient (CSR) a schopný interaktivitu po předběžném provedení.
    • WebView: Na nativním zařízení a schopný interaktivitu po předběžném provedení.
  • RendererInfo.IsInteractive označuje, zda komponenta podporuje interaktivitu v době vykreslování. Hodnota je true při interaktivním vykreslování nebo false při předkreslování nebo pro statické SSR (RendererInfo.Name of Static).
  • ComponentBase.AssignedRenderMode zveřejňuje režim vykreslení přiřazeného komponentou:
    • InteractiveServer pro Interactive Server.
    • InteractiveAuto pro interaktivní automatické.
    • InteractiveWebAssembly pro Interactive WebAssembly.

Komponenty tyto vlastnosti používají k vykreslení obsahu v závislosti na jejich umístění nebo stavu interaktivity. Následující příklady ukazují typické případy použití.

Umožňuje zobrazit obsah, dokud nebude komponenta interaktivní:

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

Zakažte tlačítko, dokud nebude komponenta interaktivní:

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

Zakažte formulář během předkreslování a povolte ho, když je komponenta interaktivní:

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

Vykreslení revizí pro podporu provádění běžné akce HTML, pokud je komponenta staticky vykreslena:

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

V předchozím příkladu:

  • Pokud je nullhodnota AssignedRenderMode , komponenta přijímá statické SSR. Blazor Zpracování událostí není v prohlížeči funkční se statickým SSR, takže komponenta odešle formulář (požadavek GET) s řetězcem titleFilter dotazu nastaveným na hodnotu uživatele <input> . Komponenta Movie (/movie) může přečíst řetězec dotazu a zpracovat hodnotu titleFilter vykreslení komponenty s filtrovanými výsledky.
  • V opačném případě je režim vykreslení libovolný z InteractiveServer, InteractiveWebAssemblynebo InteractiveAuto. Komponenta je schopná použít delegát obslužné rutiny události (FilterMovies) a hodnotu vázanou na <input> prvek (titleFilter) k interaktivnímu filtrování filmů přes připojení na pozadí SignalR .

Blazor příklady dokumentace pro Blazor Web Apps

Při použití Blazor Web App, většina ukázkových Blazor komponent dokumentace vyžaduje interaktivitu k fungování a předvedení konceptů popsaných v článcích. Při testování ukázkové komponenty poskytované článkem se ujistěte, že aplikace přijme globální interaktivitu nebo komponenta přijme interaktivní režim vykreslování.

Předkreslování

Předběžné vykreslování je proces počátečního vykreslování obsahu stránky na serveru bez povolení obslužných rutin událostí pro vykreslované ovládací prvky. Server vypíše uživatelské rozhraní HTML stránky co nejdříve v reakci na počáteční požadavek, což aplikaci umožní reagovat na uživatele. Prerendering může také zlepšit optimalizaci vyhledávače (SEO) vykreslením obsahu pro počáteční odpověď HTTP, kterou vyhledávací weby používají k výpočtu pořadí stránek.

U interaktivních komponent je ve výchozím nastavení povolené předkreslování.

Interní navigace pro interaktivní směrování nezahrnuje vyžádání nového obsahu stránky ze serveru. Proto u interních požadavků na stránky, včetně rozšířené navigace, nedojde k předrenderování. Další informace najdete v tématu Statické versus interaktivní směrování, interaktivní směrování a předsměrování a rozšířené navigace a zpracování formulářů.

Zakázání předběžného vykreslování pomocí následujících technik se projeví pouze pro režimy vykreslování nejvyšší úrovně. Pokud nadřazená komponenta určuje režim vykreslení, nastavení předběžného vykreslování podřízených položek se ignoruje. Toto chování se zkoumá, pokud jde o možné změny ve verzi .NET 10 v listopadu 2025.

Pokud chcete zakázat prerendering pro instanci komponenty, předejte prerender příznak s hodnotou false do režimu vykreslování:

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

Zakázání předkreslování v definici komponenty:

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

Pokud chcete zakázat prerendering pro celou aplikaci, označte režim vykreslování na nejvyšší úrovni interaktivní komponenty v hierarchii komponent aplikace, která není kořenovou komponentou.

U aplikací založených na Blazor Web App šabloně projektu se určuje režim vykreslování přiřazený k celé aplikaci, kde se komponenta Routes používá v dané komponentě App (Components/App.razor). Následující příklad nastaví režim vykreslení aplikace na Interactive Server se zakázaným předrenderováním:

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

Zakažte také předkreslování komponenty HeadOutlet v této komponentě:App

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

Vytvoření kořenové komponenty, například App komponenty, interaktivní se @rendermode direktivou v horní části definičního souboru kořenové komponenty (.razor) není podporováno. Proto není možné předřazování přímo zakázat komponentou App .

Statické vykreslování na straně serveru (statické SSR)

Komponenty používají statické vykreslování na straně serveru (statické SSR). Komponenta se vykreslí do streamu odpovědí a interaktivita není povolená.

V následujícím příkladu neexistuje žádné označení pro režim vykreslení komponenty, takže komponenta dědí svůj režim vykreslování z nadřazeného objektu. Vzhledem k tomu, že žádná nadřazená komponenta neurčí režim vykreslování, je na serveru staticky vykreslena následující komponenta. Tlačítko není interaktivní a nevyvolá metodu UpdateMessage při výběru. Hodnota message se nezmění a komponenta není reenderována v reakci na události uživatelského rozhraní.

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

Pokud používáte předchozí komponentu místně ve složce Blazor Web Appprojektu serveru, umístěte ji do složky projektu Components/Pages serveru. Serverový projekt je projekt řešení s názvem, který nekončí .Client. Když je aplikace spuštěná, přejděte do /render-mode-1 adresního řádku prohlížeče.

Během statického systému SSR Razor se požadavky na stránky součástí zpracovávají na straně serveru ASP.NET zpracování požadavků na kanál middlewaru Core pro směrování a autorizaci. Vyhrazené Blazor funkce pro směrování a autorizaci nejsou funkční, protože Razor komponenty se nevykreslují během zpracování požadavků na straně serveru. Blazor Funkce směrovače v komponentě Routes , které nejsou dostupné během statického SSR, zahrnují zobrazení:

Pokud aplikace vykazuje interaktivitu na kořenové úrovni, zpracování požadavků na straně serveru ASP.NET Core se nezabíná po počáteční statickém SSR, což znamená, že předchozí Blazor funkce fungují podle očekávání.

Vylepšená navigace se statickým SSR vyžaduje zvláštní pozornost při načítání JavaScriptu. Další informace najdete v tématu ASP.NET Core Blazor JavaScript se statickým vykreslováním na straně serveru (statické SSR).

Interaktivní vykreslování na straně serveru (interaktivní SSR)

Interaktivní vykreslování na straně serveru (interaktivní SSR) vykreslí komponentu interaktivně ze serveru pomocí Blazor Server. Interakce uživatelů se zpracovávají přes připojení v reálném čase k prohlížeči. Připojení okruhu se naváže při vykreslení součásti serveru.

V následujícím příkladu je režim vykreslení nastaven interaktivní SSR přidáním @rendermode InteractiveServer do definice komponenty. Tlačítko volá metodu UpdateMessage při výběru. Hodnota message změn a komponenta se znovu zobrazí, aby se zpráva aktualizovala v uživatelském rozhraní.

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

Pokud používáte předchozí komponentu ve složce Blazor Web Appprojektu serveru, umístěte ji do složky projektu Components/Pages serveru. Serverový projekt je projekt řešení s názvem, který nekončí .Client. Když je aplikace spuštěná, přejděte do /render-mode-2 adresního řádku prohlížeče.

Vykreslování na straně klienta (CSR)

Vykreslování na straně klienta (CSR) vykreslí komponentu interaktivně na klientovi pomocí Blazor WebAssembly. Modul runtime .NET a sada aplikací se stáhnou a ukládají do mezipaměti při počátečním vykreslení komponenty WebAssembly. Komponenty využívající CSR musí být sestaveny z samostatného klientského projektu, který nastaví Blazor WebAssembly hostitele.

V následujícím příkladu je režim vykreslování nastaven na CSR s @rendermode InteractiveWebAssembly. Tlačítko volá metodu UpdateMessage při výběru. Hodnota message změn a komponenta se znovu zobrazí, aby se zpráva aktualizovala v uživatelském rozhraní.

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

Pokud používáte předchozí komponentu Blazor Web Appmístně do složky projektu klienta, umístěte ji do složky projektu klienta Pages . Projekt klienta je projekt řešení s názvem, který končí ..Client Když je aplikace spuštěná, přejděte do /render-mode-3 adresního řádku prohlížeče.

Automatické (automatické) vykreslování

Automatické vykreslování určuje, jak vykreslit komponentu za běhu. Komponenta se zpočátku vykreslí pomocí interaktivního Blazor Server vykreslování na straně serveru (interaktivní SSR) pomocí modelu hostování. Modul runtime .NET a sada aplikací se stáhnou do klienta na pozadí a uloží se do mezipaměti, aby je bylo možné použít při budoucích návštěvách.

Režim automatického vykreslování nikdy dynamicky nemění režim vykreslování komponenty, která už je na stránce. Režim automatického vykreslení provede počáteční rozhodnutí o tom, jaký typ interaktivity se má pro komponentu použít, a pak tato komponenta zachová tento typ interaktivity tak dlouho, dokud je na stránce. Jedním z faktorů v tomto počátečním rozhodnutí je zvážení, zda již komponenty na stránce s interaktivitou WebAssembly/Server. Automatický režim dává přednost výběru režimu vykreslování, který odpovídá režimu vykreslování stávajících interaktivních komponent. Důvodem, proč automatický režim dává přednost použití existujícího režimu interaktivity, je vyhnout se zavedení nového interaktivního modulu runtime, který nesdílí stav s existujícím modulem runtime.

Komponenty používající režim automatického vykreslování musí být sestaveny z samostatného klientského projektu, který nastaví Blazor WebAssembly hostitele.

V následujícím příkladu je komponenta v průběhu procesu interaktivní. Tlačítko volá metodu UpdateMessage při výběru. Hodnota message změn a komponenta se znovu zobrazí, aby se zpráva aktualizovala v uživatelském rozhraní. Zpočátku se komponenta vykreslí interaktivně ze serveru, ale při následných návštěvách se vykreslí z klienta po stažení a uložení sady aplikací do mezipaměti.

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

Pokud používáte předchozí komponentu Blazor Web Appmístně do složky projektu klienta, umístěte ji do složky projektu klienta Pages . Projekt klienta je projekt řešení s názvem, který končí ..Client Když je aplikace spuštěná, přejděte do /render-mode-4 adresního řádku prohlížeče.

Šíření režimu vykreslování

Režimy vykreslování se šíří v hierarchii komponent.

Pravidla pro použití režimů vykreslování:

  • Výchozí režim vykreslování je Statický.
  • Režimy vykreslování Interactive Server (InteractiveServer), Interactive WebAssembly (InteractiveWebAssembly) a Interactive Auto (InteractiveAuto) lze použít z komponenty, včetně použití různých režimů vykreslování pro součásti na stejné straně.
  • V podřízené komponentě nemůžete přepnout do jiného interaktivního režimu vykreslování. Komponenta serveru nemůže být například podřízenou součástí WebAssembly.
  • Parametry předané interaktivní podřízené komponentě ze statického nadřazeného objektu musí být serializovatelné ve formátu JSON. To znamená, že do interaktivní podřízené komponenty nemůžete předat fragmenty vykreslování ani podřízený obsah ze statické nadřazené komponenty.

Následující příklady používají nesměrovatelnou komponentu, která není stránkovaná SharedMessage . Nezávislá komponenta režimu SharedMessage vykreslování nepoužívá režim vykreslování s direktivou@attribute. Pokud tyto scénáře testujete pomocí Blazor Web Appsložky aplikace, umístěte do složky aplikace následující komponentu 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!";
    }
}

Dědičnost režimu vykreslování

Pokud je komponenta SharedMessage umístěná do staticky vykreslené nadřazené komponenty, SharedMessage komponenta se také vykreslí staticky a není interaktivní. Tlačítko nezavolá UpdateMessagea zpráva se neaktualizuje.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

Pokud je komponenta SharedMessage umístěna v komponentě, která definuje režim vykreslení, dědí použitý režim vykreslování.

V následujícím příkladu je komponenta SharedMessage interaktivní přes SignalR připojení k klientovi. Tlačítko volá UpdateMessagea zpráva se aktualizuje.

RenderMode6.razor:

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

<SharedMessage />

Podřízené komponenty s různými režimy vykreslování

V následujícím příkladu jsou obě SharedMessage komponenty předem vysunuty a zobrazí se, když se stránka zobrazí v prohlížeči.

  • První SharedMessage komponenta s interaktivním vykreslováním na straně serveru (interaktivní SSR) je interaktivní po Blazornavázání okruhu SignalR .
  • Druhá SharedMessage komponenta s vykreslováním na straně klienta (CSR) je interaktivní po Blazor stažení sady aplikací a modul runtime .NET je v klientovi aktivní.

RenderMode7.razor:

@page "/render-mode-7"

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

Podřízená komponenta s serializovatelným parametrem

Následující příklad ukazuje interaktivní podřízenou komponentu, která přebírá parametr. Parametry musí být serializovatelné.

RenderMode8.razor:

@page "/render-mode-8"

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

Parametry komponent, které nelze serializovat, jako je podřízený obsah nebo fragment vykreslení, nejsou podporovány. V následujícím příkladu má předání podřízeného obsahu komponentě SharedMessage za následek chybu za běhu.

RenderMode9.razor:

@page "/render-mode-9"

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

Chyba:

System.InvalidOperationException: Parametr ChildContent nelze předat komponentě SharedMessage s rendermode InteractiveServerRenderMode. Důvodem je, že parametr je typu delegáta Microsoft.AspNetCore.Components.RenderFragment, což je libovolný kód a nelze ho serializovat.

Pokud chcete obejít předchozí omezení, zabalte podřízenou komponentu do jiné komponenty, která parametr nemá. Jedná se o přístup přijatý v Blazor Web App šabloně projektu s komponentou Routes (Components/Routes.razor) k zabalení Router komponenty.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

V předchozím příkladu:

  • Podřízený obsah se předává komponentě SharedMessage bez generování chyby za běhu.
  • Komponenta SharedMessage se na serveru vykreslí interaktivně.

Podřízená komponenta s jiným režimem vykreslení než nadřazená komponenta

Nepokoušejte se použít jiný interaktivní režim vykreslování pro podřízenou komponentu, než je režim vykreslování nadřazeného objektu.

Následující komponenta při vykreslení komponenty způsobí chybu za běhu:

RenderMode11.razor:

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

<SharedMessage @rendermode="InteractiveWebAssembly" />

Chyba:

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.

Statické stránky SSR v globálně interaktivní aplikaci

Existují případy, kdy specifikace aplikace volá komponenty k přijetí statického vykreslování na straně serveru (statické SSR) a běží pouze na serveru, zatímco rest aplikace používá interaktivní režim vykreslování.

Tento přístup je užitečný jenom v případě, že aplikace obsahuje konkrétní stránky, které nemůžou pracovat s interaktivním vykreslováním serveru nebo webAssembly. Použijte například tento přístup pro stránky, které jsou závislé na čtení a zápisu souborů cookie HTTP a můžou pracovat pouze v cyklu požadavků a odpovědí místo interaktivního vykreslování. U stránek, které pracují s interaktivním vykreslováním, byste je neměli vynutit, aby používaly statické vykreslování SSR, protože je pro koncového uživatele méně efektivní a méně responzivní.

Označte libovolnou Razor stránku komponenty s atributem [ExcludeFromInteractiveRouting] přiřazeným direktivou:@attributeRazor

@attribute [ExcludeFromInteractiveRouting]

Použití atributu způsobí, že navigace na stránce se ukončí z interaktivního směrování. Příchozí navigace je nucena provést opětovné načtení celé stránky místo toho, aby se stránka přeložila prostřednictvím interaktivního směrování. Opětovné načtení celé stránky vynutí opětovné načtení kořenovou komponentu nejvyšší úrovně, obvykle komponentu (App.razorkomponentuApp), aby se znovu vyrovnala ze serveru, což aplikaci umožňuje přepnout do jiného režimu vykreslování nejvyšší úrovně.

Metoda RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting rozšíření umožňuje komponentě zjistit, zda [ExcludeFromInteractiveRouting] je atribut použit na aktuální stránce.

V komponentě App použijte vzor v následujícím příkladu:

  • Stránky, které nejsou opatřeny poznámkami s atributem [ExcludeFromInteractiveRouting] ve výchozím nastavení do InteractiveServer režimu vykreslení s globální interaktivitou. Můžete nahradit InteractiveServer InteractiveWebAssembly nebo InteractiveAuto zadat jiný výchozí globální režim vykreslování.
  • Stránky anotované atributem [ExcludeFromInteractiveRouting] přijímají statické SSR (PageRenderModeje přiřazenonull).
<!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;
}

Alternativou k použití RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting metody rozšíření je ruční čtení metadat koncového bodu pomocí HttpContext.GetEndpoint()?.Metadata.

Existují dva přístupy, které lze použít k jemnému řízení režimů vykreslování, z nichž každý je popsán v následujících pododdílech:

  • Oblast (složka) statických komponent SSR: Máte oblast (složku) aplikace s komponentami, které musí přijmout statické SSR a sdílet stejnou předponu cesty trasy. Aplikace řídí režim vykreslování globálně nastavením režimu vykreslování na Routes komponentě App v komponentě na základě cesty ke složce.

  • Statické komponenty SSR rozložené do aplikace: Máte komponenty rozložené kolem aplikace v různých umístěních, které musí přijmout statické SSR a spouštět pouze na serveru. Statické komponenty jen pro SSR nejsou v jedné složce a nesdílejí společnou předponu cesty směrování. Aplikace řídí režim vykreslování na základě jednotlivých komponent nastavením režimu vykreslování s direktivou @rendermode v instancích komponent. Reflexe se v komponentě App používá k nastavení režimu vykreslování na komponentě Routes .

V oboupřípadechch

Následující příklady používají HttpContext kaskádový parametr k určení, zda je stránka staticky vykreslena. Označuje null HttpContext , že komponenta se vykresluje interaktivně, což je užitečné jako signál v kódu aplikace k aktivaci opětovného načtení celé stránky.

Oblast (složka) statických komponent SSR

Přístup popsaný v této pododdíle používá Blazor Web App šablona projektu s individuálním ověřováním a globální interaktivitou.

Oblast (složka) aplikace obsahuje komponenty, které musí přijmout statické SSR a spouštět pouze na serveru. Komponenty ve složce sdílejí stejnou předponu cesty trasy. Například IdentityRazor komponenty Blazor Web App šablony projektu jsou ve Components/Account/Pages složce a sdílejí předponu /Accountkořenové cesty .

Složka obsahuje _Imports.razor také soubor, který aplikuje vlastní rozložení účtu na součásti ve složce:

@using BlazorSample.Components.Account.Shared
@layout AccountLayout

Složka Shared udržuje komponentu AccountLayout rozložení. Komponenta používá HttpContext k určení, zda komponenta přijala statické SSR. Identity součásti musí být vykresleny na serveru se statickým SSR, protože nastavují Identity soubory cookie. Pokud je nullhodnota HttpContext , komponenta se vykresluje interaktivně a opětovné načtení celé stránky se provádí voláním NavigationManager.Refresh nastavenou forceLoad na truehodnotu . Tím se vynutí úplný rerender stránky pomocí statického SSR.

Components/Account/Shared/AccountLayout.razor:

@inherits LayoutComponentBase
@layout BlazorSample.Components.Layout.MainLayout
@inject NavigationManager Navigation

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            Navigation.Refresh(forceReload: true);
        }
    }
}

Poznámka:

Blazor Web App V šabloně projektu je druhý soubor rozložení (ManageLayout.razorve Components/Account/Shared složce) pro Identity komponenty ve Components/Account/Pages/Manage složce. Složka Manage má vlastní _Imports.razor soubor, který se má použít u ManageLayout komponent ve složce. Použití vnořených _Imports.razor souborů ve vlastních aplikacích je užitečným přístupem k použití vlastních rozložení na skupiny stránek.

V této komponentě App všechny požadavky na komponentu Account ve složce použijí null režim vykreslování, který vynucuje statické SSR. Požadavky jiných komponent přijímají globální aplikaci interaktivního režimu vykreslování SSR (InteractiveServer).

Důležité

Použití null režimu vykreslování vždy nevynucuje statické SSR. Jen se to stane, že se chová tímto způsobem pomocí přístupu uvedeného v této části.

null Režim vykreslení je v podstatě stejný jako nezadání režimu vykreslení, což vede k tomu, že komponenta dědí režim vykreslování nadřazeného objektu. V tomto případě se komponenta App vykresluje pomocí statického null SSR, takže režim vykreslování vede k Routes tomu, že komponenta dědí statickou službu SSR ze App komponenty. Pokud je pro podřízenou komponentu, jejíž nadřazená komponenta používá interaktivní režim vykreslování, zadává podřízený režim vykreslování stejný interaktivní režim vykreslování.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

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

    private IComponentRenderMode? RenderModeForPage => 
        HttpContext.Request.Path.StartsWithSegments("/Account")
            ? null
            : {INTERACTIVE RENDER MODE};
}

V předchozím kódu změňte {INTERACTIVE RENDER MODE} zástupný symbol na odpovídající hodnotu v závislosti na tom, jestli rest má aplikace přijmout globální InteractiveServer, InteractiveWebAssemblynebo InteractiveAuto vykreslovat.

Součásti, které musí přijmout statické SSR ve Account složce, nejsou nutné k nastavení rozložení, které se použije prostřednictvím _Imports.razor souboru. Komponenty nenastavují režim vykreslování, protože by se měly vykreslit pomocí statického SSR. Aby bylo možné vynutit statické SSR, není nutné nic dalšího Account udělat pro komponenty ve složce.

Statické komponenty SSR rozložené do aplikace

V předchozím dílčím oddílu řídí aplikace režim vykreslování komponent nastavením režimu vykreslování globálně v komponentě App . Případně může komponenta App také přijmout režimy vykreslení jednotlivých komponent pro nastavení režimu vykreslování, což umožňuje komponentám rozloženým po aplikaci vynutit přijetí statického SSR. Tento pododdíl popisuje přístup.

Aplikace má vlastní rozložení, které se dá použít u komponent kolem aplikace. Sdílená komponenta aplikace se obvykle umístí do Components/Layout složky. Komponenta používá HttpContext k určení, zda komponenta přijala statické SSR. Pokud je nullhodnota HttpContext , komponenta se vykresluje interaktivně a opětovné načtení celé stránky se provádí voláním NavigationManager.Refresh nastavenou forceLoad na truehodnotu . Tím se aktivuje požadavek na server pro komponentu.

Components/Layout/StaticSsrLayout.razor:

@inherits LayoutComponentBase
@layout MainLayout
@inject NavigationManager Navigation

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            Navigation.Refresh(forceReload: true);
        }
    }
}

V komponentě App se reflexe používá k nastavení režimu vykreslování. Pro komponentu se použije Routes jakýkoli režim vykreslení přiřazený k definičnímu souboru jednotlivých komponent.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

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

    private IComponentRenderMode? RenderModeForPage =>
        HttpContext.GetEndpoint()?.Metadata.GetMetadata<RenderModeAttribute>()?
            .Mode;
}

Každá komponenta, která musí přijmout statickou službu SSR, nastaví vlastní rozložení a nezadá režim vykreslování. Nezadání režimu vykreslování vede k null hodnotě RenderModeAttribute.Mode v App komponentě, což vede k Routes tomu, že k instanci komponenty a vynucení statického SSR není přiřazen žádný režim vykreslování.

Důležité

Použití null režimu vykreslování vždy nevynucuje statické SSR. Jen se to stane, že se chová tímto způsobem pomocí přístupu uvedeného v této části.

null Režim vykreslení je v podstatě stejný jako nezadání režimu vykreslení, což vede k tomu, že komponenta dědí režim vykreslování nadřazeného objektu. V tomto případě se komponenta App vykresluje pomocí statického null SSR, takže režim vykreslování vede k Routes tomu, že komponenta dědí statickou službu SSR ze App komponenty. Pokud je pro podřízenou komponentu, jejíž nadřazená komponenta používá interaktivní režim vykreslování, zadává podřízený režim vykreslování stejný interaktivní režim vykreslování.

Aby komponenty vynutily statický SSR, není nutné nic dalšího udělat, než když použijete vlastní rozložení bez nastavení interaktivního režimu vykreslování:

@layout BlazorSample.Components.Layout.StaticSsrLayout

Interaktivní komponenty kolem aplikace se vyhýbají použití vlastního rozložení statického SSR a nastavují pouze odpovídající interaktivní režim vykreslování, který se na komponentu použije při odrazu App v komponentěRoutes:

@rendermode {INTERACTIVE RENDER MODE}

V předchozím kódu změňte {INTERACTIVE RENDER MODE} zástupný symbol na odpovídající hodnotu v závislosti na tom, jestli má komponenta přijmout InteractiveServer, InteractiveWebAssemblynebo InteractiveAuto vykreslovat.

Služby na straně klienta se nepodaří vyřešit během předdefinování.

Za předpokladu, že prerendering není pro komponentu nebo pro aplikaci zakázaný, je komponenta v .Client projektu předem na serveru. Vzhledem k tomu, že server nemá přístup k registrovaným službám na straně Blazor klienta, není možné tyto služby vložit do komponenty, aniž by se zobrazila chyba, že se služba během předběžného běhu nenašla.

Představte si například následující Home komponentu .Client v projektu s Blazor Web App globální interaktivní webassembly nebo interaktivním automatickým vykreslováním. Komponenta se pokusí vložit IWebAssemblyHostEnvironment , aby získala název prostředí.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

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

Během předkreslování nedojde k žádné chybě v době kompilace, ale během předkreslování dojde k chybě za běhu:

Nelze zadat hodnotu vlastnosti Environment v typu BlazorSample.Client.Pages.Home Neexistuje žádná registrovaná služba typu Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment.

K této chybě dochází, protože komponenta se musí zkompilovat a spouštět na serveru během předřazení, ale IWebAssemblyHostEnvironment není registrovanou službou na serveru.

Pokud aplikace nevyžaduje hodnotu během předrenderování, můžete tento problém vyřešit vložením IServiceProvider metody získání služby místo samotného typu služby:

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

Předchozí přístup ale není užitečný, pokud vaše logika vyžaduje hodnotu během předkreslování.

Můžete se také vyhnout problému, pokud zakážete předběžné nastavení pro komponentu, ale to je extrémní opatření, které je třeba vzít v mnoha případech, které nemusí splňovat specifikace komponenty.

Tento scénář můžete vyřešit třemi způsoby. Níže jsou uvedeny od nejpohodnějšího po nejméně doporučenou:

  • Doporučeno pro služby sdíleného rozhraní: U sdílených služeb architektury, které nejsou v hlavním projektu zaregistrované pouze na straně serveru, zaregistrujte služby v hlavním projektu, které je zpřístupní během předběžného běhu. Příklad tohoto scénáře najdete v doprovodných materiálech pro HttpClient služby volání webového rozhraní API z aplikace ASP.NET CoreBlazor.

  • Doporučeno pro služby mimo sdílenou architekturu: Vytvořte vlastní implementaci služby pro službu na serveru. Službu používejte normálně v interaktivních součástech .Client projektu. Ukázku tohoto přístupu najdete v ASP.NET základních Blazor prostředích.

  • Vytvořte abstrakci služby a vytvořte implementace pro službu v projektech a serverových .Client projektech. Zaregistrujte služby v každém projektu. Vložení vlastní služby do komponenty

  • Možná budete moct přidat .Client odkaz na balíček projektu na balíček na straně serveru a vrátit se k použití rozhraní API na straně serveru při předběžném nastavení na serveru.

Zjišťování komponent z dalších sestavení

Aby bylo možné zjistit směrovatelné Razor komponenty v odkazovaných projektech, musí být do rámce zpřístupněna Blazor další sestavení. Další informace najdete v tématu ASP.NET Blazor Základní směrování a navigace.

Uzavření okruhů, pokud neexistují žádné zbývající součásti interaktivního serveru

Komponenty interaktivního serveru zpracovávají události webového uživatelského rozhraní pomocí připojení v reálném čase s prohlížečem označovaným jako okruh. Okruh a jeho přidružený stav se vytvoří, když se vykreslí kořenová součást Interactive Serveru. Okruh se zavře, pokud na stránce nejsou žádné zbývající součásti interaktivního serveru, které uvolní prostředky serveru.

Vlastní režimy vykreslování zkrácené ruky

Direktiva @rendermode přebírá jeden parametr, který je statickou instancí typu IComponentRenderMode. Atribut @rendermode direktivy může převzít jakoukoli instanci režimu vykreslování, statickou nebo ne. Architektura Blazor poskytuje RenderMode statickou třídu s několika předdefinovanými režimy vykreslování pro usnadnění práce, ale můžete si vytvořit vlastní.

Za normálních okolností komponenta používá následující @rendermode direktivu k zákazu předrenderingu:

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

Vezměte však v úvahu následující příklad, který vytvoří režim interaktivního vykreslování na straně serveru bez předběžného vykreslování prostřednictvím souboru aplikace _Imports (Components/_Imports.razor):

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

V komponentách v celé složce použijte režim zkráceného Components vykreslování:

@rendermode InteractiveServerWithoutPrerendering

Alternativně může jedna instance komponenty definovat vlastní režim vykreslování prostřednictvím soukromého pole:

@rendermode interactiveServerWithoutPrerendering

...

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

V současné době je přístup režimu zkráceného vykreslování pravděpodobně užitečný pouze pro snížení podrobností určení příznaku prerender . Pokud budou pro interaktivní vykreslování k dispozici další příznaky a chcete vytvořit režimy vykreslování s krátkým vykreslováním s různými kombinacemi příznaků, může být tento přístup v budoucnu užitečnější.

Injektáž služby prostřednictvím souboru importu nejvyšší úrovně (_Imports.razor)

Tato část se týká Blazor Web Appjenom s.

Soubor importu nejvyšší úrovně ve Components složce (Components/_Imports.razor) vloží jeho odkazy do všech komponent v hierarchii složek, které zahrnují komponentu App (App.razor). Komponenta App se vždy vykreslí staticky i v případě, že je zakázána předkreslování součásti stránky. Proto vložením služeb přes soubor importu nejvyšší úrovně vznikne překlad dvou instancí služby v komponentách stránky.

Pokud chcete tento scénář vyřešit, vložte službu do nového souboru importu umístěného Pages ve složce (Components/Pages/_Imports.razor). Z daného umístění se služba vyřeší pouze jednou v komponentách stránky.

Další materiály