Składniki prerender ASP.NET Core Razor

W tym artykule opisano Razor scenariusze prerendering składników dla składników renderowanych na serwerze w programie Blazor Web Apps.

Prerendering to proces początkowego renderowania zawartości strony na serwerze bez włączania procedur obsługi zdarzeń dla renderowanych kontrolek. Serwer zwraca interfejs użytkownika HTML strony tak szybko, jak to możliwe w odpowiedzi na początkowe żądanie, co sprawia, że aplikacja czuje się bardziej elastyczna dla użytkowników. Prerendering może również poprawić optymalizację aparatu wyszukiwania (SEO) przez renderowanie zawartości początkowej odpowiedzi HTTP używanej przez wyszukiwarki do obliczania rangi strony.

Utrwalanie stanu wstępnego

Bez utrwalania stanu wstępnego, stan używany podczas prerenderingu jest utracony i musi zostać utworzony ponownie, gdy aplikacja jest w pełni załadowana. Jeśli jakikolwiek stan jest tworzony asynchronicznie, interfejs użytkownika może migać, ponieważ wstępnie utworzony interfejs użytkownika jest zastępowany, gdy składnik jest rerendered.

Rozważ następujący PrerenderedCounter1 składnik licznika. Składnik ustawia początkową losową wartość licznika podczas prerenderingu w OnInitialized metodzie cyklu życia. Po nawiązaniu SignalR połączenia z klientem element rerenders składnika i początkowa wartość licznika jest zastępowana podczas OnInitialized wykonywania po raz drugi.

PrerenderedCounter1.razor:

@page "/prerendered-counter-1"
@rendermode @(new InteractiveServerRenderMode(prerender: true))
@inject ILogger<PrerenderedCounter1> Logger

<PageTitle>Prerendered Counter 1</PageTitle>

<h1>Prerendered Counter 1</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount;

    protected override void OnInitialized()
    {
        currentCount = Random.Shared.Next(100);
        Logger.LogInformation("currentCount set to {Count}", currentCount);
    }

    private void IncrementCount() => currentCount++;
}

Uruchom aplikację i sprawdź rejestrowanie ze składnika. Poniżej przedstawiono przykładowe dane wyjściowe.

info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 41
info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 92

Pierwsza zarejestrowana liczba występuje podczas prerenderingu. Liczba jest ponownie ustawiana po wstępnieenderingu, gdy składnik jest rerendered. W interfejsie użytkownika występuje również migotanie, gdy liczba aktualizacji z zakresu od 41 do 92.

Aby zachować początkową wartość licznika podczas prerenderingu, Blazor obsługuje utrwalanie stanu na stronie prerendered przy użyciu PersistentComponentState usługi (oraz składników osadzonych na stronach lub widokach Razor stron lub aplikacji MVC, Pomocnik utrwalania tagu stanu składnika).

Aby zachować stan wstępnego, zdecyduj, jaki stan ma być trwały przy użyciu PersistentComponentState usługi. PersistentComponentState.RegisterOnPersisting rejestruje wywołanie zwrotne, aby utrwało stan składnika przed wstrzymaniem aplikacji. Stan jest pobierany po wznowieniu działania aplikacji.

W poniższym przykładzie przedstawiono ogólny wzorzec:

• Symbol {TYPE} zastępczy reprezentuje typ danych do utrwalania.
• Symbol {TOKEN} zastępczy jest ciągiem identyfikatora stanu. Rozważ użycie elementu nameof({VARIABLE}), gdzie {VARIABLE} symbol zastępczy jest nazwą zmiennej, która przechowuje stan. Użycie nameof() dla identyfikatora stanu pozwala uniknąć użycia cytowanego ciągu.

@implements IDisposable
@inject PersistentComponentState ApplicationState

...

@code {
    private {TYPE} data;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistData);

        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("{TOKEN}", data);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Poniższy przykład składnika licznika utrwala stan licznika podczas wstępnegoenderowania i pobiera stan w celu zainicjowania składnika.

PrerenderedCounter2.razor:

@page "/prerendered-counter-2"
@implements IDisposable
@inject ILogger<PrerenderedCounter2> Logger
@inject PersistentComponentState ApplicationState

<PageTitle>Prerendered Counter 2</PageTitle>

<h1>Prerendered Counter 2</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override void OnInitialized()
    {
        persistingSubscription =
            ApplicationState.RegisterOnPersisting(PersistCount);

        if (!ApplicationState.TryTakeFromJson<int>(
            nameof(currentCount), out var restoredCount))
        {
            currentCount = Random.Shared.Next(100);
            Logger.LogInformation("currentCount set to {Count}", currentCount);
        }
        else
        {
            currentCount = restoredCount!;
            Logger.LogInformation("currentCount restored to {Count}", currentCount);
        }
    }

    private Task PersistCount()
    {
        ApplicationState.PersistAsJson(nameof(currentCount), currentCount);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose() => persistingSubscription.Dispose();

    private void IncrementCount() => currentCount++;
}

Gdy składnik jest wykonywany, currentCount jest ustawiany tylko raz podczas prerenderingu. Wartość jest przywracana, gdy składnik jest rerendered. Poniżej przedstawiono przykładowe dane wyjściowe.

info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount restored to 96

Inicjując składniki o tym samym stanie używanym podczas prerenderingu, wszystkie kosztowne kroki inicjowania są wykonywane tylko raz. Renderowany interfejs użytkownika jest również zgodny ze wstępnie zdefiniowanym interfejsem użytkownika, więc w przeglądarce nie występuje migotanie.

Stan utrwalonego wstępnego jest przenoszony do klienta, gdzie jest używany do przywrócenia stanu składnika. Podczas renderowania po stronie klienta (CSR, InteractiveWebAssembly) dane są udostępniane w przeglądarce i nie mogą zawierać poufnych, prywatnych informacji. Podczas interaktywnego renderowania po stronie serwera (interakcyjne usługi SSR, InteractiveServer) ASP.NET Core Data Protection zapewnia bezpieczny transfer danych. Tryb renderowania InteractiveAuto łączy zestaw WebAssembly i interakcyjność serwera, dlatego konieczne jest rozważenie ujawnienia danych w przeglądarce, tak jak w przypadku CSR.

Składniki osadzone na stronach i widokach (Razor Pages/MVC)

W przypadku składników osadzonych na stronie lub widoku Razor aplikacji Pages lub MVC należy dodać Pomocnik tagu stanu składnika utrwalania z <persist-component-state /> tagiem HTML wewnątrz tagu zamykającego </body> układu aplikacji. Jest to wymagane tylko w przypadku Razor aplikacji Pages i MVC. Aby uzyskać więcej informacji, zobacz Utrwalanie pomocnika tagu stanu składnika w ASP.NET Core.

Pages/Shared/_Layout.cshtml:

<body>
    ...

    <persist-component-state />
</body>

Routing interakcyjny i wstępne tworzenie

Gdy składnik Routes nie definiuje trybu renderowania, aplikacja korzysta z interakcyjności poszczególnych stron/składników i nawigacji. Korzystając z nawigacji między stronami/składnikami, nawigacja wewnętrzna† jest obsługiwana przez ulepszonego routingu po tym, jak aplikacja stanie się interaktywna. †wewnętrzny w tym kontekście oznacza, że miejsce docelowe adresu URL zdarzenia nawigacji jest Blazor punktem końcowym wewnątrz aplikacji.

Usługa PersistentComponentState działa tylko na początkowym ładowaniu strony, a nie we wewnętrznych rozszerzonych zdarzeniach nawigacji stron.

Jeśli aplikacja wykonuje pełną (nie rozszerzoną) nawigację do strony korzystającej ze stanu trwałego składnika, stan utrwalonego jest udostępniany aplikacji do użycia, gdy stanie się interakcyjny.

Jeśli obwód interakcyjny został już ustanowiony i ulepszona nawigacja jest wykonywana do strony korzystającej ze stanu trwałego składnika, stan nie jest udostępniany w istniejącym obwodzie, aby składnik mógł go używać. Nie ma prerenderingu dla wewnętrznego żądania strony, a usługa PersistentComponentState nie jest świadoma, że wystąpiła ulepszona nawigacja. Nie ma mechanizmu dostarczania aktualizacji stanu do komponentów, które są już uruchomione w istniejącym obwodzie. Przyczyną jest to, że Blazor obsługuje tylko przekazywanie stanu z serwera do klienta w czasie inicjowania środowiska uruchomieniowego, a nie po uruchomieniu środowiska uruchomieniowego.

Dodatkowe prace nad platformą Blazor w celu rozwiązania tego scenariusza są brane pod uwagę w przypadku platformy .NET 10 (listopad 2025 r.). Aby uzyskać więcej informacji i dyskusji w społeczności na temat nieobsługiwanych sposobów obejścia, zobacz Wspieranie trwałego stanu komponentu podczas rozszerzonych nawigacji stron (dotnet/aspnetcore #51584). •Nieobsługiwane obejścia nie są zaakceptowane przez firmę Microsoft do użytku w aplikacjach Blazor. Użyj pakietów, podejść i kodu innych firm na własne ryzyko.

Wyłączenie rozszerzonej nawigacji, co zmniejsza wydajność, ale także pozwala uniknąć problemu z ładowaniem stanu z PersistentComponentState dla żądań stron wewnętrznych, jest omówione w routingu i nawigacji w ASP.NET Core Blazor.

Wskazówki dotyczące prerenderingu

Wskazówki dotyczące prerenderingu są zorganizowane w dokumentacji według tematu Blazor . Poniższe linki obejmują wszystkie wskazówki dotyczące prerenderingu w całej dokumentacji ustawionej według tematu:

• Podstawy

  • OnNavigateAsyncjest wykonywany dwa razy, gdy wstępne renderowanie: Obsługa zdarzeń nawigacji asynchronicznej za pomocą poleceniaOnNavigateAsync
  • Uruchamianie: kontrolowanie nagłówków w kodzie języka C#
  • Obsługa błędów: wstępneenderowanie
  • SignalR: Rozmiar stanu wstępnego i SignalR limit rozmiaru komunikatu

• Tryby renderowania: prerendering

• Składniki

  • Kontrolowanie <head> zawartości podczas prerenderingu
  • Razor tematy cyklu życia składników dotyczące prerenderingu
    • Inicjowanie składnika (OnInitialized{Async})
    • Po renderowaniu składnika (OnAfterRender{Async})
    • Ponowne łączenie stanowe po wstępnym zakończeniu
    • dotyczących wywoływania języka JavaScript z platformy .NET i wywoływania platformy .NET z języka JavaScript.
    • Obsługa niekompletnych działań asynchronicznych podczasrenderowania: wskazówki dotyczące opóźnionego renderowania wynikające z długotrwałych zadań cyklu życia podczas przetwarzania wstępnego na serwerze.
  • Przykładowa aplikacja składnika QuickGrid: aplikacja QuickGrid dla Blazor przykładowej aplikacji jest hostowana na stronach GitHub Pages. Witryna ładuje się szybko dzięki statycznym prerenderingowi przy użyciu projektuBlazorWasmPrerendering.Build przez społeczność.
  • Prerendering podczas integrowania składników z aplikacjami Razor Pages i MVC

• Uwierzytelnianie i autoryzacja

  • Ograniczanie zagrożeń po stronie serwera: wykonywanie skryptów między witrynami (XSS)
  • Wyświetlanie nieautoryzowanej zawartości po stronie serwera podczas wstępnej obsługi niestandardowej AuthenticationStateProvider
  • Blazor WebAssembly uwierzytelnianie składników renderowanych z prerenderingiem

• Zarządzanie stanem: Obsługa prerenderingu: oprócz sekcji Obsługa prerenderingu kilka innych sekcji artykułu zawiera uwagi dotyczące prerenderingu.