Sdílet prostřednictvím

Razor ASP.NET knihovny základních tříd (RCLS) se statickým vykreslováním na straně serveru (statické SSR)

  • Č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 obsahuje pokyny pro autory knihoven komponent, kteří zvažují podporu vykreslování na straně statického serveru (static SSR).

Blazorpodporuje vývoj ekosystému opensourcových a komerčních knihoven komponent, formálně označovaných jako Razor knihovny tříd (RCLS). Vývojáři můžou také vytvářet opakovaně použitelné komponenty pro soukromé sdílení komponent mezi aplikacemi ve svých vlastních společnostech. V ideálním případě jsou komponenty vyvíjeny z důvodu zajištění kompatibility s co nejvíce hostitelskými modely a režimy vykreslování. Statické SSR zavádí další omezení, která můžou být náročnější na podporu než režimy interaktivního vykreslování.

Vysvětlení možností a omezení statického serveru SSR

Statická služba SSR je režim, ve kterém se komponenty spouští, když server zpracovává příchozí požadavek HTTP. Blazor vykresluje komponentu jako HTML, která je součástí odpovědi. Po odeslání odpovědi se komponenta na straně serveru a stav rendereru zahodí, takže vše, co zůstává v prohlížeči, je html.

Výhoda tohoto režimu je levnější, škálovatelnější hostování, protože k uchování stavu součástí nejsou potřeba žádné průběžné prostředky serveru, mezi prohlížečem a serverem se nesmí udržovat žádné průběžné připojení a v prohlížeči se nevyžaduje žádná datová část WebAssembly.

Všechny existující komponenty lze stále používat se statickým SSR. Náklady na tento režim jsou ale v tom, že obslužné rutiny událostí, jako @onclickje například †, nejde spustit z následujících důvodů:

  • V prohlížeči neexistuje žádný kód .NET, který by je dal spustit.
  • Server okamžitě zahodil všechny komponenty a stav rendereru, které by bylo potřeba ke spouštění obslužných rutin událostí nebo k opětovnému vyřazování stejných instancí komponent.

†Pokud je zvláštní výjimka obslužné @onsubmit rutiny události pro formuláře, která je vždy funkční bez ohledu na režim vykreslování.

To je ekvivalentem chování komponent během předrenderingu před BlazorSignalR spuštěním okruhu nebo modulu runtime .NET WebAssembly.

U komponent, jejichž jedinou rolí je vytvoření obsahu modelu DOM jen pro čtení, jsou tato chování pro statické SSR zcela dostačující. Autoři knihoven ale musí zvážit, jaký přístup se má při zahrnutí interaktivních komponent do knihoven provést.

Možnosti pro autory komponent

Existují tři hlavní přístupy:

  • Nepoužívejte interaktivní chování (Základní)

    U komponent, jejichž jedinou rolí je vytvoření obsahu modelu DOM jen pro čtení, nemusí vývojář provádět žádné zvláštní akce. Tyto komponenty přirozeně pracují s jakýmkoli režimem vykreslování.

    Příklady:

    • Komponenta "uživatelská karta", která načte data odpovídající osobě a vykreslí je ve stylizovaném uživatelském rozhraní s fotkou, funkcí a dalšími podrobnostmi.
    • Komponenta "video", která funguje jako obálka kolem elementu HTML <video> , což usnadňuje použití v komponentě Razor .

  • Vyžadování interaktivního vykreslování (Basic)

    Můžete se rozhodnout, že se komponenta bude používat jenom s interaktivním vykreslováním. To omezuje použitelnost komponenty, ale znamená to, že se můžete volně spolehnout na libovolné obslužné rutiny událostí. I potom byste se měli vyhnout deklarování konkrétního @rendermode uživatele a povolit autorovi aplikace, který vaši knihovnu využívá, vybrat ji.

    Příklady:

    • Komponenta pro úpravy videa, ve které můžou uživatelé splice a přeuspořádat segmenty videa. I kdyby existoval způsob, jak tyto operace úprav znázornit pomocí tlačítek html a formulářů, uživatelské prostředí by bylo nepřijatelné bez skutečné interaktivity.
    • Editor dokumentů pro spolupráci, který musí zobrazovat aktivity ostatních uživatelů v reálném čase.

  • Používejte interaktivní chování, ale návrh statického SSR a progresivního vylepšení (Advanced)

    Mnoho interaktivních chování je možné implementovat pouze pomocí funkcí HTML. S dobrým pochopením html a css můžete často vytvořit užitečný směrný plán funkčnosti, který funguje se statickým SSR. Stále můžete deklarovat obslužné rutiny událostí, které implementují pokročilejší volitelné chování, které fungují pouze v interaktivních režimech vykreslování.

    Příklady:

    • Komponenta mřížky. V rámci statického SSR může komponenta podporovat pouze zobrazení dat a navigaci mezi stránkami (implementovanými s <a> odkazy). Při použití s interaktivním vykreslováním může komponenta přidat dynamické řazení a filtrování.
    • Komponenta tabset. Pokud se navigace mezi kartami dosahuje pomocí <a> odkazů a stavu, je uložena pouze v parametrech dotazu adresy URL, může komponenta fungovat bez @onclick.
    • Rozšířená komponenta pro nahrávání souborů. V rámci statického SSR se komponenta může chovat jako nativní <input type=file>. Při použití s interaktivním vykreslováním může komponenta také zobrazit průběh nahrávání.
    • Punčocháče. V případě statického SSR může komponenta zobrazit cenovou nabídku akcií v okamžiku vykreslení HTML. Při použití s interaktivním vykreslováním může komponenta aktualizovat cenu akcií v reálném čase.

U některé z těchto strategií je také možnost implementovat interaktivní funkce pomocí JavaScriptu.

Aby si mohli vybrat z těchto přístupů, musí autoři opakovaně použitelných Razor komponent využít kompromis mezi náklady a výhodami. Vaše komponenta je užitečnější a má širší uživatelskou základnu, pokud podporuje všechny režimy vykreslování, včetně statického SSR. Návrh a implementace komponenty, která podporuje a využívá nejlepší výhodu každého režimu vykreslování, ale trvá více práce.

Kdy použít direktivu @rendermode

Ve většině případů by autoři opakovaně použitelných komponent neměli zadávat režim vykreslování ani v případě, že je vyžadována interaktivita. Je to proto, že autor komponenty neví, jestli aplikace umožňuje podporu pro InteractiveServer, InteractiveWebAssemblynebo obojí s InteractiveAuto. Tím, že nezadáte @rendermode, autor komponenty ponechá volbu vývojáři aplikace.

I když si autor komponenty myslí, že je vyžadována interaktivita, můžou existovat případy, kdy autor aplikace považuje za dostačující použití statického SSSR. Může se například zdát, že komponenta mapy s interaktivitou přetažení a přiblížení může vyžadovat interaktivitu. Některé scénáře ale můžou volat pouze vykreslení statického obrázku mapy a vyhnout se přetahováním nebo přiblížením funkcí.

Jediným důvodem, proč by autor opakovaně použitelné komponenty měl použít @rendermode direktivu na jeho komponentě, je, pokud je implementace zásadně svázána s jedním konkrétním režimem vykreslování a určitě by způsobila chybu, pokud by byla použita v jiném režimu. Zvažte komponentu se základním účelem přímé interakce s hostitelským operačním systémem pomocí rozhraní API specifických pro Windows nebo Linux. Takovou komponentu ve službě WebAssembly nelze použít. Pokud ano, je vhodné pro komponentu deklarovat @rendermode InteractiveServer .

Vykreslování streamování

Opakovaně použitelné Razor komponenty jsou zdarma deklarovány @attribute [StreamRendering] pro vykreslování streamování ([StreamRendering] rozhraní API atributů). Výsledkem jsou přírůstkové aktualizace uživatelského rozhraní během statického SSR. Vzhledem k tomu, že stejné vzory načítání dat vytvářejí přírůstkové aktualizace uživatelského rozhraní během interaktivního [StreamRendering] vykreslování, bez ohledu na přítomnost atributu se komponenta může ve všech případech chovat správně. I v případech, kdy je na serveru potlačeno streamování statického SSR, komponenta stále vykresluje svůj správný konečný stav.

Opakovaně použitelné Razor komponenty mohou používat odkazy a vylepšenou navigaci. Značky HTML <a> by měly generovat ekvivalentní chování s interaktivní Router komponentou nebo bez této komponenty a zda je povolena nebo zakázána rozšířená navigace na nadřazené úrovni v systému DOM.

Použití formulářů napříč režimy vykreslování

Opakovaně použitelné Razor komponenty mohou obsahovat formuláře (nebo <form> <EditForm>), protože je možné je implementovat tak, aby fungovaly stejně ve statických i interaktivních režimech vykreslování.

Představte si následující příklad:

<EditForm Enhance FormName="NewProduct" Model="Model" OnValidSubmit="SaveProduct">
    <DataAnnotationsValidator />
    <ValidationSummary />

    <p><label>Name: <InputText @bind-Value="Item.Name" /></label></p>

    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Product? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private async Task Save()
    {
        ...
    }
}

Rozhraní EnhanceAPI a SupplyParameterFromFormAttribute rozhraní FormNameAPI se používají pouze během statického SSR a při interaktivním vykreslování se ignorují. Formulář funguje správně během interaktivního i statického SSR.

Vyhněte se rozhraním API, která jsou specifická pro statické rozhraní SSR

HttpContext je k dispozici pouze během statického SSR, takže se nespoléhejte na HttpContext vytváření komponent, které fungují v různých režimech vykreslování. Rozhraní HttpContext API nemá smysl používat během interaktivního vykreslování, protože v těchto časech neexistuje žádný aktivní požadavek HTTP. Je zbytečné přemýšlet o nastavení stavového kódu HTTP nebo zápisu do odpovědi HTTP.

Opakovaně použitelné komponenty jsou zdarma k dispozici HttpContext , pokud jsou k dispozici:

[CascadingParameter]
public HttpContext? Context { get; set; }

Hodnota je null během interaktivního vykreslování a je nastavená pouze během statického SSR.

V mnoha případech existují lepší alternativy než použití HttpContext. Pokud potřebujete znát aktuální adresu URL nebo provést přesměrování, rozhraní API pro NavigationManager práci se všemi režimy vykreslování. Pokud potřebujete znát stav ověřování uživatele, použijte Blazorslužbu (AuthenticationStateProviderdokumentaci) k použití HttpContext.User.AuthenticationStateProvider