ASP.NET Core-klassbibliotek Razor (RCL) med statisk återgivning på serversidan (statisk SSR)

Anmärkning

Det här är inte den senaste versionen av den här artikeln. Den aktuella versionen finns i .NET 10-versionen av den här artikeln.

Den här artikeln innehåller vägledning för komponentbiblioteksförfattare som överväger stöd för statisk återgivning på serversidan (statisk SSR).

BlazorParlamentet uppmuntrar utvecklingen av ett ekosystem med bibliotek med öppen källkod och kommersiella komponenter, formellt kallade Razor klassbibliotek (RCL). Utvecklare kan också skapa återanvändbara komponenter för att dela komponenter privat mellan appar i sina egna företag. Helst utvecklas komponenter för kompatibilitet med så många värdmodeller och återgivningslägen som möjligt. Statisk SSR introducerar ytterligare begränsningar som kan vara mer utmanande att stödja än interaktiva återgivningslägen.

Förstå funktionerna och begränsningarna för statisk SSR

Statisk SSR är ett läge där komponenter körs när servern hanterar en inkommande HTTP-begäran. Blazor renderar komponenten som HTML, som ingår i svaret. När svaret har skickats ignoreras komponenten och återgivningstillståndet på serversidan, så allt som återstår är HTML i webbläsaren.

Fördelen med det här läget är billigare, mer skalbar hosting eftersom inga serverresurser krävs för att behålla komponenternas tillstånd, ingen kontinuerlig anslutning behöver upprätthållas mellan webbläsare och server och ingen WebAssembly-nyttolast krävs i webbläsaren.

Alla befintliga komponenter kan fortfarande användas med statisk SSR. Kostnaden för det här läget är dock att händelsehanterare, till exempel @onclick†, inte kan köras av följande skäl:

• Det finns ingen .NET-kod i webbläsaren för att köra dem.
• Servern har omedelbart tagit bort alla komponent- och återgivningstillstånd som skulle behövas för att köra händelsehanterare eller för att återskapa samma komponentinstanser.

†Det här är ett särskilt undantag för @onsubmit händelsehanteraren för formulär, som alltid fungerar, oavsett återgivningsläge.

Detta motsvarar hur komponenter beter sig under förrendering, innan Blazor-kretsen eller .NET WebAssembly-körmiljön startas SignalR.

För komponenter vars enda roll är att producera skrivskyddat DOM-innehåll är dessa beteenden för statisk SSR helt tillräckliga. Biblioteksförfattare måste dock överväga vilken metod som ska användas när de inkluderar interaktiva komponenter i sina bibliotek.

Alternativ för komponentförfattare

Det finns tre huvudsakliga metoder:

• Använd inte interaktiva beteenden (Basic)

  För komponenter vars enda roll är att skapa skrivskyddat DOM-innehåll behöver utvecklaren inte vidta några särskilda åtgärder. Dessa komponenter fungerar naturligt med alla återgivningslägen.

  Examples:

  • En "användarkortskomponent" som läser in data som motsvarar en person och renderar dem i ett stiliserat användargränssnitt med ett foto, en jobbtitel och annan information.
  • En "video"-komponent som fungerar som omslutning runt HTML-elementet <video> , vilket gör det enklare att använda i en Razor komponent.

• Kräv interaktiv återgivning (Basic)

  Du kan välja att kräva att komponenten endast används med interaktiv återgivning. Detta begränsar tillämpligheten för din komponent, men innebär att du fritt kan förlita dig på godtyckliga händelsehanterare. Även då bör du ändå undvika att deklarera en specifik @rendermode och tillåta appförfattaren som använder biblioteket att välja en.

  Examples:

  • En videoredigeringskomponent där användare kan skarva och ordna om segment av video. Även om det fanns ett sätt att representera dessa redigeringsåtgärder med vanliga HTML-knappar och formulärposter skulle användarupplevelsen vara oacceptabel utan verklig interaktivitet.
  • En samarbetsdokumentredigerare som måste visa andra användares aktiviteter i realtid.

• Använd interaktiva beteenden, men design för statisk SSR och progressiv förbättring (Avancerat )

  Många interaktiva beteenden kan implementeras med endast HTML-funktioner. Med god förståelse för HTML och CSS kan du ofta skapa en användbar baslinje för funktioner som fungerar med statisk SSR. Du kan fortfarande deklarera händelsehanterare som implementerar mer avancerade, valfria beteenden, som bara fungerar i interaktiva återgivningslägen.

  Examples:

  • En rutnätskomponent. Under statisk SSR kan komponenten endast ha stöd för att visa data och navigera mellan sidor (implementeras med <a> länkar). När komponenten används med interaktiv återgivning kan den lägga till livesortering och filtrering.
  • En flikuppsättningskomponent. Så länge navigering mellan flikar uppnås med hjälp av <a> länkar och tillstånd endast lagras i URL-frågeparametrar kan komponenten fungera utan @onclick.
  • En avancerad filuppladdningskomponent. Under statisk SSR kan komponenten fungera som en intern <input type=file>. När komponenten används med interaktiv återgivning kan den också visa uppladdningsstatus.
  • En aktieticker. Under statisk SSR kan komponenten visa aktieofferten när HTML-koden renderades. När komponenten används med interaktiv rendering kan den uppdatera aktiekursen i realtid.

För någon av dessa strategier finns det också möjlighet att implementera interaktiva funktioner med JavaScript.

Om du vill välja bland dessa metoder måste återanvändbara Razor komponentförfattare göra en kostnads-/förmånsavvägning. Komponenten är mer användbar och har en bredare potentiell användarbas om den stöder alla återgivningslägen, inklusive statisk SSR. Det krävs dock mer arbete för att utforma och implementera en komponent som stöder och utnyttjar varje återgivningsläge på bästa sätt.

När direktivet @rendermode ska användas

I de flesta fall bör återanvändbara komponentförfattare inte ange ett återgivningsläge, inte ens när interaktivitet krävs. Det beror på att komponentförfattaren inte vet om appen aktiverar stöd för InteractiveServer, InteractiveWebAssemblyeller båda med InteractiveAuto. Genom att inte ange en @rendermodelämnar komponentförfattaren valet till apputvecklaren.

Även om komponentförfattaren anser att interaktivitet krävs kan det fortfarande finnas fall där en appförfattare anser att det räcker att använda statisk SSR ensamt. Till exempel kan en kartkomponent med dra och zooma interaktivitet verka kräva interaktivitet. Vissa scenarier kanske dock bara kräver att återge en statisk kartbild och undvika funktioner för dragning/zoomning.

Den enda anledningen till att en återanvändbar komponentförfattare bör använda @rendermode direktivet om sin komponent är om implementeringen i grunden är kopplad till ett specifikt återgivningsläge och säkert skulle orsaka ett fel om det används i ett annat läge. Överväg en komponent med huvudsyftet att interagera direkt med värdoperativsystemet med hjälp av Windows- eller Linux-specifika API:er. Det kan vara omöjligt att använda en sådan komponent på WebAssembly. I så fall är det rimligt att deklarera @rendermode InteractiveServer för komponenten.

Streaming-återgivning

Återanvändbara Razor komponenter är fria att deklarera @attribute [StreamRendering] för strömningsrendering ([StreamRendering] attribut-API). Detta resulterar i inkrementella användargränssnittsuppdateringar under statisk SSR. Eftersom samma datainläsningsmönster ger inkrementella användargränssnittsuppdateringar under interaktiv återgivning, oavsett förekomsten av [StreamRendering] attributet, kan komponenten fungera korrekt i alla fall. Även i fall där strömmar av statisk SSR undertrycks på servern, återger komponenten fortfarande sitt korrekta slutliga tillstånd.

Använda länkar mellan återgivningslägen

Återanvändbara Razor komponenter kan använda länkar och förbättrad navigering. HTML-taggar <a> bör ge motsvarande beteenden med eller utan en interaktiv Router komponent och huruvida förbättrad navigering är aktiverad/inaktiverad på överordnad nivå i DOM.

Använda formulär mellan återgivningslägen

Återanvändbara Razor komponenter kan innehålla formulär (antingen <form> eller <EditForm>), eftersom dessa kan implementeras för att fungera på samma sätt i både statiska och interaktiva återgivningslägen.

Tänk på följande exempel:

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

    <p><label>Name: <InputText @bind-Value="Model!.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()
    {
        ...
    }
}

EnhanceAPI:erna , FormNameoch SupplyParameterFromFormAttribute används endast under statisk SSR och ignoreras under interaktiv återgivning. Formuläret fungerar korrekt under både interaktiv och statisk SSR.

Undvik API:er som är specifika för statisk SSR

HttpContext är endast tillgängligt under statisk SSR, så förlita dig inte på HttpContext när du skapar komponenter som fungerar mellan återgivningslägen. API:et HttpContext är inte heller meningsfullt att använda under interaktiv återgivning eftersom det inte finns någon aktiv HTTP-begäran under flygning vid dessa tidpunkter. Det är meningslöst att tänka på att ange en HTTP-statuskod eller skriva till HTTP-svaret.

Återanvändbara komponenter kan ta emot en HttpContext när den är tillgänglig enligt följande:

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

Värdet är null under interaktiv återgivning och anges endast under statisk SSR.

I många fall finns det bättre alternativ än att använda HttpContext. Om du behöver känna till den aktuella URL:en eller utföra en omdirigering fungerar API:erna NavigationManager i alla återgivningslägen. Om du behöver känna till användarens autentiseringstillstånd använder du Blazortjänsten AuthenticationStateProvider (AuthenticationStateProvider dokumentationen) över med hjälp av HttpContext.User.