ASP.NET Core-klassebibliotheken Razor (RCL's) met statische rendering aan serverzijde (statische SSR)

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 10-versie van dit artikel voor de huidige release.

Dit artikel bevat richtlijnen voor auteurs van onderdeelbibliotheken die ondersteuning overwegen voor statische server-side rendering (statische SSR).

Blazormoedigt de ontwikkeling aan van een ecosysteem van opensource- en commerciële onderdeelbibliotheken, formeel klassebibliotheken (RCL's) genoemdRazor. Ontwikkelaars kunnen ook herbruikbare onderdelen maken voor het privé delen van onderdelen in apps binnen hun eigen bedrijven. In het ideale instantie worden onderdelen ontwikkeld voor compatibiliteit met zoveel mogelijk hostingmodellen en renderingmodi. Statische SSR introduceert extra beperkingen die lastiger zijn te ondersteunen dan interactieve weergavemodi.

Inzicht in de mogelijkheden en beperkingen van statische SSR

Statische SSR is een modus waarin onderdelen worden uitgevoerd wanneer de server een binnenkomende HTTP-aanvraag verwerkt. Blazor geeft het onderdeel weer als HTML, dat is opgenomen in het antwoord. Zodra het antwoord is verzonden, wordt het onderdeel aan de serverzijde en de status van de renderer verwijderd, zodat alles wat overblijft HTML in de browser is.

Het voordeel van deze modus is goedkopere, schalende hosting, omdat er geen doorlopende serverresources nodig zijn om de componentstatus vast te houden, er geen doorlopende verbinding tussen browser en server hoeft te worden gehandhaafd en er geen WebAssembly-payload in de browser vereist is.

Alle bestaande onderdelen kunnen nog steeds worden gebruikt met statische SSR. De kosten van deze modus zijn echter dat gebeurtenis-handlers, zoals @onclick†, niet kunnen worden uitgevoerd om de volgende redenen:

• Er is geen .NET-code in de browser om ze uit te voeren.
• De server heeft onmiddellijk alle componenten en rendererstatus verwijderd die nodig zouden zijn om gebeurtenisafhandelaars uit te voeren of om dezelfde componentinstanties opnieuw te renderen.

†Er is een speciale uitzondering voor de @onsubmit gebeurtenishandler voor formulieren, die altijd functioneel is, ongeacht de weergavemodus.

Dit is equivalent aan hoe componenten zich gedragen tijdens prerendering, voorafgaand aan de opstart van Blazor het SignalR circuit of de .NET WebAssembly-runtime.

Voor componenten waarvan de enige rol is om read-only DOM-inhoud te produceren, zijn deze gedragingen voor statische SSR volledig voldoende. Bibliotheekauteurs moeten echter rekening houden met de manier waarop interactieve onderdelen in hun bibliotheken moeten worden opgenomen.

Opties voor auteurs van onderdelen

Er zijn drie hoofdmethoden:

• Gebruik geen interactief gedrag (Basic)

  Voor onderdelen waarvan de enige rol is om alleen-lezen DOM-inhoud te produceren, hoeft de ontwikkelaar geen speciale actie te ondernemen. Deze onderdelen werken natuurlijk met elke rendermodus.

  Examples:

  • Een gebruikerskaartonderdeel dat gegevens laadt die overeenkomen met een persoon en deze weergeeft in een gestileerde gebruikersinterface met een foto, functie en andere details.
  • Een videoonderdeel dat fungeert als een wrapper rond het HTML-element <video> , waardoor het handiger is om in een Razor onderdeel te gebruiken.

• Interactieve rendering vereisen (Basic)

  U kunt ervoor kiezen om te vereisen dat uw onderdeel alleen wordt gebruikt met interactieve rendering. Dit beperkt de toepasselijkheid van uw onderdeel, maar betekent dat u vrijelijk kunt vertrouwen op willekeurige gebeurtenis-handlers. Zelfs dan moet u nog steeds voorkomen dat u een specifieke @rendermode declaratie uitvoert en de auteur van de app die uw bibliotheek verbruikt, toestemming geven om er een te selecteren.

  Examples:

  • Een videobewerkingsonderdeel waarin gebruikers segmenten van video's kunnen koppelen en opnieuw kunnen rangschikken. Zelfs als er een manier was om deze bewerkingen weer te geven met gewone HTML-knoppen en formulierposts, zou de gebruikerservaring onacceptabel zijn zonder echte interactiviteit.
  • Een gezamenlijke documenteditor die de activiteiten van andere gebruikers in realtime moet weergeven.

• Interactief gedrag gebruiken, maar ontwerpen voor statische SSR en progressieve uitbreiding (Geavanceerd)

  Veel interactieve gedragingen kunnen worden geïmplementeerd met behulp van alleen HTML-mogelijkheden. Met een goed begrip van HTML en CSS kunt u vaak een nuttige basislijn voor functionaliteit produceren die werkt met statische SSR. U kunt nog steeds gebeurtenis-handlers declareren die geavanceerdere, optionele gedragingen implementeren, die alleen in interactieve rendermodi werken.

  Examples:

  • Een rasteronderdeel. Onder statische SSR kan het onderdeel alleen ondersteuning bieden voor het weergeven van gegevens en het navigeren tussen pagina's (geïmplementeerd met <a> koppelingen). Bij gebruik met interactieve rendering kan het onderdeel live sorteren en filteren toevoegen.
  • Een tabset-component. Zolang navigatie tussen tabbladen wordt bereikt met behulp van <a> koppelingen en de status alleen in URL-queryparameters wordt gehouden, kan het onderdeel zonder @onclick werken.
  • Een geavanceerd onderdeel voor het uploaden van bestanden. Onder statische SSR kan het onderdeel zich gedragen als een systeemeigen <input type=file>. Wanneer het onderdeel wordt gebruikt met interactieve rendering, kan de voortgang van de upload ook worden weergegeven.
  • Een aandelen ticker. Onder statische SSR kan het onderdeel de aandelenkoers weergeven op het moment dat de HTML werd weergegeven. Wanneer het onderdeel wordt gebruikt met interactieve rendering, kan de aandelenkoers vervolgens in realtime worden bijgewerkt.

Voor een van deze strategieën is er ook de mogelijkheid om interactieve functies te implementeren met JavaScript.

Als u een van deze benaderingen wilt kiezen, moeten auteurs van herbruikbare Razor onderdelen een afweging maken tussen kosten/baten. Uw onderdeel is nuttiger en heeft een breder potentieel gebruikersbestand als het ondersteuning biedt voor alle rendermodi, waaronder statische SSR. Het kost echter meer werk om een onderdeel te ontwerpen en te implementeren dat ondersteuning biedt voor en het beste gebruik maakt van elke rendermodus.

Wanneer moet de @rendermode richtlijn worden gebruikt

In de meeste gevallen mogen auteurs van herbruikbare onderdelen geen rendermodus opgeven, zelfs niet wanneer interactiviteit is vereist. Dit komt doordat de auteur van het onderdeel niet weet of de app ondersteuning biedt voor InteractiveServer, InteractiveWebAssembly, of beide met InteractiveAuto. Door geen @rendermode op te geven, laat de componentauteur de keuze aan de app-ontwikkelaar over.

Zelfs als de auteur van het onderdeel denkt dat interactiviteit vereist is, kunnen er nog steeds gevallen zijn waarin een app-auteur het voldoende acht om alleen statische SSR te gebruiken. Een kaartonderdeel met interactiviteit voor slepen en in- en uitzoomen kan bijvoorbeeld interactiviteit vereisen. In sommige scenario's kan het nodig zijn om alleen een statische kaartafbeelding te tonen en slepen- en zoomfuncties te vermijden.

De enige reden waarom een auteur van een herbruikbaar onderdeel de @rendermode instructie voor het onderdeel moet gebruiken, is als de implementatie fundamenteel is gekoppeld aan één specifieke rendermodus en zeker een fout veroorzaakt als deze in een andere modus wordt gebruikt. Overweeg een onderdeel met een kerndoel om rechtstreeks met het hostbesturingssysteem te communiceren met behulp van Windows- of Linux-specifieke API's. Het kan onmogelijk zijn om een dergelijk onderdeel op WebAssembly te gebruiken. Zo ja, dan is het redelijk om voor het onderdeel te declareren @rendermode InteractiveServer .

Streaming-rendering

Herbruikbare Razor componenten kunnen @attribute [StreamRendering] declareren voor streaming rendering ([StreamRendering] attribuut-API). Dit resulteert in incrementele UI-updates tijdens statische SSR. Aangezien dezelfde patronen voor het laden van gegevens incrementele UI-updates produceren tijdens interactieve rendering, ongeacht de aanwezigheid van het [StreamRendering] kenmerk, kan het onderdeel zich in alle gevallen correct gedragen. Zelfs in gevallen waarin het streamen van statische SSR op de server wordt onderdrukt, geeft de component nog steeds de juiste eindstatus weer.

Koppelingen in rendermodi gebruiken

Herbruikbare Razor onderdelen kunnen koppelingen en verbeterde navigatie gebruiken. HTML-tags <a> moeten gelijkwaardig gedrag opleveren, met of zonder een interactief Router onderdeel en of het nu verbeterde navigatie op voorouderlijk niveau in de DOM is ingeschakeld of uitgeschakeld.

Formulieren gebruiken in verschillende rendermodi

Herbruikbare Razor onderdelen kunnen formulieren (of <form><EditForm>) bevatten, omdat deze kunnen worden geïmplementeerd om gelijkwaardig te werken in zowel statische als interactieve rendermodi.

Bekijk het volgende voorbeeld:

<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()
    {
        ...
    }
}

De Enhance, FormNameen SupplyParameterFromFormAttribute API's worden alleen gebruikt tijdens statische SSR en worden genegeerd tijdens interactieve rendering. Het formulier werkt correct tijdens zowel interactieve als statische SSR.

Vermijd API's die specifiek zijn voor statische SSR

HttpContext is alleen beschikbaar tijdens statische SSR, dus verlaat je niet op HttpContext bij het maken van componenten die in verschillende rendermodi werken. De HttpContext API is ook niet zinvol om te gebruiken tijdens interactieve rendering, omdat er op die momenten geen actieve HTTP-aanvraag is. Het is betekenisloos om na te denken over het instellen van een HTTP-statuscode of het schrijven naar het HTTP-antwoord.

Herbruikbare componenten kunnen, indien beschikbaar, als volgt een HttpContext ontvangen:

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

De waarde is null tijdens interactieve rendering en wordt alleen ingesteld tijdens statische SSR.

In veel gevallen zijn er betere alternatieven dan het gebruik van HttpContext. Als u de huidige URL moet kennen of een omleiding wilt uitvoeren, werken NavigationManager met alle API's in alle rendermodi. Als u de verificatiestatus van de gebruiker wilt weten, gebruikt u de Blazor-service (AuthenticationStateProvider) in plaats van AuthenticationStateProvider.