Biblioteki klas ASP.NET Core Razor (RCLs) ze statycznym renderowaniem po stronie serwera (statycznym SSR)

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu dla platformy .NET 11.

Ten artykuł zawiera wskazówki dla autorów bibliotek składników, którzy rozważają obsługę renderowania statycznego po stronie serwera (static SSR).

Blazorzachęca do rozwoju ekosystemu bibliotek komponentów open source i komercyjnych, formalnie nazywanych Razor bibliotekami klas (RCLs). Deweloperzy mogą również tworzyć komponenty wielokrotnego użytku do prywatnego udostępniania komponentów między aplikacjami we własnych firmach. W idealnym przypadku składniki są opracowywane pod kątem zgodności z jak największą liczbą modeli hostingu i trybów renderowania. Statyczne SSR wprowadza dodatkowe ograniczenia, które mogą być trudniejsze do obsługi niż tryby renderowania interaktywnego.

Poznać możliwości i ograniczenia statycznego SSR

Statyczny SSR to tryb, w którym komponenty są uruchamiane, gdy serwer obsługuje przychodzące żądanie HTTP. Blazor renderuje komponent jako HTML, który jest zawarty w odpowiedzi. Po wysłaniu odpowiedzi składnik po stronie serwera i stan renderowania zostają usunięte, więc w przeglądarce pozostaje tylko kod HTML.

Zaletą tego trybu jest tańszy, bardziej skalowalny hosting, ponieważ do przechowywania stanu składnika nie są wymagane żadne bieżące zasoby serwera, nie trzeba utrzymywać trwającego połączenia między przeglądarką a serwerem, a w przeglądarce nie jest wymagany pakiet WebAssembly.

Wszystkie istniejące składniki mogą być nadal używane ze statyczną usługą SSR. Jednak koszt tego trybu polega na tym, że programy obsługi zdarzeń, takie jak @onclick†, nie mogą być uruchamiane z następujących powodów:

  • Nie ma kodu platformy .NET w przeglądarce, więc nie można ich uruchomić.
  • Serwer natychmiast odrzucił wszystkie komponenty i stan modułu renderowania, które byłyby potrzebne do obsługi zdarzeń lub do ponownego renderowania tych samych instancji komponentów.

†Istnieje specjalny wyjątek dla programu obsługi zdarzeń @onsubmit formularzy, który jest zawsze funkcjonalny, niezależnie od trybu renderowania.

Jest to odpowiednik sposobu działania składników podczas prerenderingu, zanim zostanie uruchomiony obwód BlazorSignalR lub środowisko uruchomieniowe WebAssembly platformy .NET.

W przypadku składników, których jedyną rolą jest tworzenie zawartości DOM tylko do odczytu, te zachowania dla statycznego SSR są całkowicie wystarczające. Jednak autorzy bibliotek muszą rozważyć, jakie podejście przyjąć w przypadku dołączania komponentów interaktywnych w bibliotekach.

Opcje dla autorów składników

Są trzy główne podejścia:

  • Nie stosuj interaktywnych zachowań (Podstawy)

    W przypadku składników, których jedyną rolą jest tworzenie zawartości DOM tylko do odczytu, deweloper nie musi podejmować żadnych specjalnych akcji. Te składniki naturalnie działają w dowolnym trybie renderowania.

    Przykłady:

    • Składnik "karty użytkownika", który ładuje dane odpowiadające osobie i renderuje je w stylizowanym interfejsie użytkownika ze zdjęciem, stanowiskiem i innymi szczegółami.
    • Składnik "wideo", który działa jako otoka wokół elementu HTML <video> , dzięki czemu jest bardziej wygodny do użycia w składniku Razor .
  • Wymagaj renderowania interakcyjnego (podstawowa)

    Możesz wymagać, aby składnik był używany tylko z renderowaniem interaktywnym. Ogranicza to zastosowanie twojego komponentu, ale oznacza to, że możesz swobodnie polegać na dowolnych programach obsługi zdarzeń. Nawet wtedy należy unikać deklarowania określonego @rendermode i pozwolić autorowi aplikacji korzystającej z biblioteki wybrać go.

    Przykłady:

    • Składnik do edycji wideo, w którym użytkownicy mogą łączyć i zmieniać kolejność segmentów wideo. Nawet jeśli istnieje sposób reprezentowania tych operacji edycji przy użyciu zwykłych przycisków HTML i wpisów w formularzach, komfort użytkowania byłby niedopuszczalny bez rzeczywistej interakcyjności.
    • Edytor dokumentów do współpracy, który musi pokazywać działania innych użytkowników w czasie rzeczywistym.
  • Używaj interaktywnych zachowań, ale projektuj z myślą o statycznym SSR i stopniowym ulepszaniu (zaawansowane)

    Wiele interaktywnych zachowań można zaimplementować tylko przy użyciu funkcji HTML. Przy dobrym zrozumieniu kodu HTML i CSS często można utworzyć przydatny podstawowy zakres funkcjonalności, który działa ze statycznym SSR. Nadal można zadeklarować programy obsługi zdarzeń, które implementują bardziej zaawansowane, opcjonalne zachowania, które działają tylko w interaktywnych trybach renderowania.

    Przykłady:

    • Komponent siatki. W statycznym SSR składnik może obsługiwać tylko wyświetlanie danych i nawigowanie między stronami (zaimplementowane za pomocą <a> linków). W przypadku użycia z renderowaniem interaktywnym składnik może dodać sortowanie i filtrowanie na żywo.
    • Komponent zestawu kart. Dopóki nawigacja między kartami jest osiągana przy użyciu linków <a>, a stan jest przechowywany tylko w parametrach zapytania adresu URL, składnik może działać bez @onclick.
    • Zaawansowany komponent przesyłania plików. W przypadku statycznego SSR składnik może zachowywać się jak natywny <input type=file>. W przypadku użycia z renderowaniem interaktywnym składnik może również wyświetlać postęp przesyłania.
    • Ticker giełdowy. W obszarze statycznego SSR składnik może wyświetlać kurs akcji w momencie renderowania kodu HTML. W przypadku użycia z renderowaniem interaktywnym składnik może następnie zaktualizować cenę akcji w czasie rzeczywistym.

W przypadku dowolnej z tych strategii istnieje również opcja implementowania funkcji interaktywnych za pomocą języka JavaScript.

Aby wybrać spośród tych podejść, autorzy składników wielokrotnego użytku Razor muszą dokonać analizy kompromisu między kosztami a korzyściami. Składnik jest bardziej przydatny i ma szerszą potencjalną bazę użytkowników, jeśli obsługuje wszystkie tryby renderowania, w tym statyczny SSR. Jednak potrzeba więcej pracy, aby zaprojektować i zaimplementować składnik, który obsługuje i najlepiej wykorzystuje każdy tryb renderowania.

Kiedy należy użyć @rendermode dyrektywy

W większości przypadków autorzy składników wielokrotnego użytku nie powinni określać trybu renderowania, nawet jeśli jest wymagana interakcyjność. Dzieje się tak dlatego, że autor składnika nie wie, czy aplikacja włącza obsługę elementów InteractiveServer, InteractiveWebAssembly lub obu z elementem InteractiveAuto. Nie określając @rendermodeelementu , autor składnika pozostawia deweloperowi aplikacji wybór.

Nawet jeśli autor składnika uważa, że wymagana jest interakcyjność, nadal może istnieć sytuacja, w której autor aplikacji uzna samo statyczne SSR za wystarczające. Na przykład składnik mapy z interakcyjnością przeciągania i powiększania może wydawać się wymagać interakcyjności. Jednak niektóre scenariusze mogą wymagać jedynie renderowania statycznego obrazu mapy, bez funkcji przeciągania i powiększania.

Jedynym powodem, dla którego autor składnika wielokrotnego użytku powinien używać dyrektywy @rendermode w swoim składniku, jest to, że implementacja jest zasadniczo połączona z jednym określonym trybem renderowania i z pewnością spowoduje błąd, jeśli składnik jest używany w innym trybie. Rozważ składnik z podstawowym celem interakcji bezpośrednio z systemem operacyjnym hosta przy użyciu interfejsów API specyficznych dla systemu Windows lub Linux. Użycie takiego komponentu w zestawie WebAssembly może być niemożliwe. Jeśli tak, uzasadnione jest zadeklarowanie komponentu @rendermode InteractiveServer.

Renderowanie strumieniowe

Komponenty wielokrotnego użytku Razor mogą swobodnie deklarować @attribute [StreamRendering] do renderowania strumieniowego ([StreamRendering] API atrybutu). Powoduje to przyrostowe aktualizacje interfejsu użytkownika podczas statycznego renderowania po stronie serwera (SSR). Ponieważ te same wzorce ładowania danych generują przyrostowe aktualizacje interfejsu użytkownika podczas renderowania interakcyjnego, niezależnie od obecności atrybutu [StreamRendering] , składnik może zachowywać się poprawnie we wszystkich przypadkach. Nawet w przypadkach, gdy na serwerze wyłączone jest strumieniowe renderowanie statycznego SSR, komponent nadal renderuje swój prawidłowy stan końcowy.

Komponenty wielokrotnego użytku Razor mogą używać linków i rozszerzonej nawigacji. Tagi HTML <a> powinny generować równoważne zachowania z interaktywnym składnikiem Router lub bez niego, niezależnie od tego, czy ulepszona nawigacja jest włączona czy wyłączona na poziomie elementu nadrzędnego w modelu DOM.

Używanie formularzy w trybach renderowania

Komponenty wielokrotnego użytku Razor mogą zawierać formularze (<form> lub <EditForm>), ponieważ można je zaimplementować w taki sposób, aby działały w trybach renderowania statycznego i interaktywnego.

Rozważmy następujący przykład:

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

Interfejsy API Enhance, FormName i SupplyParameterFromFormAttribute mają zastosowanie tylko podczas statycznego renderowania SSR i są ignorowane podczas renderowania interakcyjnego. Formularz działa poprawnie zarówno podczas interaktywnego, jak i statycznego SSR.

Unikaj interfejsów API specyficznych dla statycznego SSR

Funkcja HttpContext jest dostępna tylko podczas statycznego SSR, więc nie polegaj na HttpContext podczas tworzenia komponentów, które działają w różnych trybach renderowania. Nie ma sensu używać interfejsu HttpContext API podczas renderowania interakcyjnego, ponieważ w tym czasie nie ma aktywnego żądania HTTP w locie. Nie ma sensu myśleć o ustawianiu kodu stanu HTTP lub zapisywaniu do odpowiedzi HTTP.

Komponenty wielokrotnego użytku mogą otrzymać HttpContext, gdy są dostępne, w następujący sposób:

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

Wartość wynosi null podczas renderowania interakcyjnego i jest ustawiana tylko podczas statycznego SSR.

W wielu przypadkach istnieją lepsze alternatywy niż użycie HttpContext. Jeśli musisz znać bieżący adres URL lub wykonać przekierowanie, interfejsy API na NavigationManager działają ze wszystkimi trybami renderowania. Jeśli musisz znać stan uwierzytelnienia użytkownika, użyj usługi BlazorAuthenticationStateProvider (AuthenticationStateProvider dokumentację) zamiast używać HttpContext.User.