Udostępnij za pośrednictwem

ASP.NET Biblioteki klas core Razor (RCLS) ze statycznym renderowaniem po stronie serwera (statycznym SSR)

  • Artykuł

Uwaga

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

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

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 składników open source i komercyjnych, formalnie nazywanych Razor bibliotekami klas (RCLS). Deweloperzy mogą również tworzyć składniki wielokrotnego użytku do udostępniania składników prywatnie 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 trybami renderowania. Statyczny przewodnik SSR wprowadza dodatkowe ograniczenia, które mogą być trudniejsze do obsługi niż tryby renderowania interaktywnego.

Omówienie możliwości i ograniczeń statycznych usług SSR

Statyczny protokół SSR to tryb, w którym składniki są uruchamiane, gdy serwer obsługuje przychodzące żądanie HTTP. Blazor Renderuje składnik jako KOD HTML, który jest uwzględniony w odpowiedzi. Po wysłaniu odpowiedzi składnik po stronie serwera i stan renderowania zostanie odrzucony, więc pozostaje cały kod HTML w przeglądarce.

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 ładunek zestawu WebAssembly.

Wszystkie istniejące składniki mogą być nadal używane ze statycznym 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, aby je uruchomić.
  • Serwer natychmiast odrzucił wszystkie składniki i stan modułu renderowania, które byłyby potrzebne do wykonania programów obsługi zdarzeń lub do rerender tego samego wystąpienia składnika.

† Wyjątki specjalne dla programu obsługi zdarzeń dla @onsubmit formularzy, który jest zawsze funkcjonalny, niezależnie od trybu renderowania.

Jest to odpowiednik sposobu działania składników podczas prerenderingu przed Blazoruruchomieniem obwodu lub środowiska uruchomieniowego zestawu webAssembly platformy SignalR .NET.

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

Opcje dla autorów składników

Są trzy główne podejścia:

  • Nie używaj zachowań interaktywnych (podstawowa)

    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 możliwość stosowania składnika, ale oznacza to, że możesz swobodnie polegać na dowolnych programach obsługi zdarzeń. Nawet wtedy należy unikać deklarowania określonego @rendermode elementu i zezwalać autorowi aplikacji, który korzysta z biblioteki, aby go wybrać.

    Przykłady:

    • Składnik do edycji wideo, w którym użytkownicy mogą splice i re-order segmenty wideo. Nawet jeśli istnieje sposób reprezentowania tych operacji edycji przy użyciu zwykłych przycisków HTML i wpisów w formularzach, środowisko użytkownika byłoby niedopuszczalne bez rzeczywistej interakcyjności.
    • Edytor dokumentów współpracy, który musi pokazywać działania innych użytkowników w czasie rzeczywistym.

  • Korzystanie z interaktywnych zachowań, ale projektowanie statycznych rozszerzeń SSR i progresywnych (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 punkt odniesienia funkcji, które współdziałają ze statycznym usługą 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:

    • Składnik 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.
    • Składnik zestawu tabulacji. Dopóki nawigacja między kartami jest osiągana przy użyciu <a> łączy i stanu jest przechowywana tylko w parametrach zapytania adresu URL, składnik może działać bez @onclickparametrów .
    • Zaawansowany składnik przekazywania plików. W obszarze statycznego SSR składnik może zachowywać się jako natywny <input type=file>. W przypadku użycia z renderowaniem interaktywnym składnik może również wyświetlać postęp przekazywania.
    • Znacznik akcji. W obszarze statycznego SSR składnik może wyświetlać ofertę giełdy 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ć kompromisu kosztów/korzyści. Składnik jest bardziej przydatny i ma szerszą potencjalną bazę użytkowników, jeśli obsługuje wszystkie tryby renderowania, w tym statyczny protokół 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, czy w obu przypadkach 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 ją za wystarczającą do użycia samego statycznego przewodnika SSR. 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ą wywoływać tylko renderowanie obrazu mapy statycznej i unikać przeciągania/powiększania funkcji.

Jedynym powodem, dla którego autor składnika wielokrotnego użytku powinien używać @rendermode dyrektywy 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 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 składnika w zestawie WebAssembly może być niemożliwe. Jeśli tak, uzasadnione jest zadeklarowanie @rendermode InteractiveServer składnika.

Renderowanie przesyłania strumieniowego

Składniki wielokrotnego użytku Razor są bezpłatne do deklarowania @attribute [StreamRendering] na potrzeby renderowania przesyłania strumieniowego ([StreamRendering] interfejs API atrybutów). Powoduje to przyrostowe aktualizacje interfejsu użytkownika podczas statycznego rejestrowania 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 jest pomijane przesyłanie strumieniowe statycznych SSR, składnik nadal renderuje prawidłowy stan końcowy.

Składniki wielokrotnego użytku Razor mogą używać linków i rozszerzonej nawigacji. Tagi HTML <a> powinny generować równoważne zachowania z lub bez składnika interakcyjnego Router i określać, czy ulepszona nawigacja jest włączona/wyłączona na poziomie nadrzędnym w modelu DOM.

Używanie formularzy w trybach renderowania

Składniki 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="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()
    {
        ...
    }
}

Interfejsy EnhanceAPI , FormNamei SupplyParameterFromFormAttribute są używane tylko podczas statycznego rejestrowania sSR i są ignorowane podczas renderowania interakcyjnego. Formularz działa poprawnie zarówno podczas interakcyjnego, jak i statycznego przewodnika SSR.

Unikaj interfejsów API specyficznych dla statycznego przewodnika SSR

HttpContext funkcja jest dostępna tylko podczas statycznego przewodnika SSR, więc nie polegaj na HttpContext tworzeniu składników, które działają w trybach renderowania. Interfejs HttpContext API nie ma sensu używać podczas renderowania interakcyjnego, ponieważ w tym czasie nie ma aktywnego żądania HTTP w locie. Nie ma znaczenia, aby myśleć o ustawieniu kodu stanu HTTP lub zapisie w odpowiedzi HTTP.

Składniki wielokrotnego użytku są bezpłatne do odbierania HttpContext , gdy są dostępne, w następujący sposób:

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

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

W wielu przypadkach istnieją lepsze alternatywy niż użycie metody HttpContext. Jeśli musisz znać bieżący adres URL lub wykonać przekierowanie, interfejsy API współpracują NavigationManager ze wszystkimi trybami renderowania. Jeśli musisz znać stan uwierzytelniania użytkownika, użyj Blazorusługi (AuthenticationStateProviderAuthenticationStateProviderdokumentacji) za pomocą polecenia .HttpContext.User