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

  • Článek

Tento článek vysvětluje řízení Razor vykreslování komponent ve Blazor službě Web Apps 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 Blazor ve webové aplikaci přijímá režim vykreslování, který určuje model hostování, který používá, kde se vykresluje a jestli je interaktivní.

Následující tabulka ukazuje dostupné režimy vykreslování pro vykreslovací Razor komponenty ve Blazor webové aplikaci. 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 šablony projektu webové aplikace 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 webové aplikace najdete v tématu Nástroje pro ASP.NET Core Blazor.

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

Blazor Webová aplikace musí být nakonfigurovaná tak, aby podporovala režimy interaktivního vykreslování. Následující rozšíření se automaticky použijí pro aplikace vytvořené ze Blazor šablony projektu Webové aplikace 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 šablony projektu webové aplikace. Pokyny k vytvoření Blazor webové aplikace najdete 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 webové aplikace 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 ve výchozím nastavení 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 šabloně projektu webové aplikace se obvykle specifikuje 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 webové aplikace 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 webové aplikace:

  • 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á některý z následujících scénářů:

  • Máte oblast (složku) aplikace s komponentami, které musí přijmout statické vykreslování na straně serveru (statické SSR) a spouštět pouze na serveru. 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.
  • K aplikaci máte komponenty v různých umístěních (ne v jedné složce), které musí přijímat statické služby SSR a spouštět jenom na serveru. 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 ion se v komponentě App používá k nastavení režimu vykreslení komponentyRoutes.

V oboupřípadechch

Předchozí dva scénáře jsou popsány příklady v části Jemné řízení režimů vykreslování dále v tomto článku. Následující dvě dílčí části se zaměřují na základní přístupy k nastavení režimu vykreslování.

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

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

@rendermode renderModeForPage

...

@code {
    private static IComponentRenderMode renderModeForPage = 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="RenderModeForPage" />

...

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

Další informace o šíření režimu vykreslování najdete v části Šíření režimu vykreslování dále v tomto článku. Část Detailní řízení režimů vykreslování ukazuje, jak použít předchozí přístup k přijetí statického SSR v konkrétních oblastech aplikace (složek) nebo pro konkrétní komponenty rozložené kolem aplikace s přiřazením režimu vykreslování jednotlivých součástí.

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

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 šabloně projektu webové aplikace se určuje režim vykreslení přiřazený celé aplikaci, kde Routes se komponenta App používá v dané komponentě (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)

Ve výchozím nastavení používají komponenty 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 Blazor místně ve webové aplikaci, 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 Blazor místně ve webové aplikaci, 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 místně ve webové aplikaci, umístěte ji do složky klientského Pages projektu. 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 místně ve webové aplikaci, umístěte ji do složky klientského Pages projektu. 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é součásti ze statického nadřazeného objektu musí být JSserializovatelné. 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 webové 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 (ve výchozím nastavení) 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 vytvoření 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, který se používá v Blazor šabloně projektu webové aplikace 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.

Jemné řízení režimů vykreslování

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 zbytek aplikace používá interaktivní režim vykreslování.

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 ion se v komponentě App používá k nastavení režimu vykreslení komponentyRoutes.

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 nullHttpContext , ž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 tomto dílčím oddílu Blazor používá šablona projektu webové aplikace 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 šablony projektu webové aplikace 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 využívá HttpContext k určení, jestli se komponenta vykresluje na serveru. Identity komponenty musí být vykresleny na serveru se statickým SSR, protože jsou nastaveny Identitycookie. 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 NavigationManager

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

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

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

Poznámka:

Blazor V šabloně projektu Webové aplikace 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 má zbytek aplikace přijmout globální InteractiveServer, InteractiveWebAssemblynebo InteractiveAuto vykreslování.

Součásti, které musí přijmout statické SSR ve Account složce, nejsou nutné k nastavení rozložení, protože se používá prostřednictvím _Imports.razor souboru, a komponenty nenastavují režim vykreslování, protože by se měly vykreslit se statickým 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 využívá HttpContext k určení, jestli se komponenta vykresluje na serveru. 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 NavigationManager

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

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

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            NavigationManager.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 statické 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í komponentu .Client v projektu ve Blazor webové aplikaci s globální interaktivní webassembly nebo interaktivním automatickým vykreslováním.Home 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 typuBlazor Sample.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 platí jenom pro Blazor Web Apps.

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