tryby renderowania ASP.NET Core Blazor

W tym artykule wyjaśniono kontrolę nad renderowaniem składników Razor w Blazor Web Apps w czasie kompilacji lub w czasie wykonywania.

Te wskazówki nie dotyczą aplikacji autonomicznych Blazor WebAssembly . Blazor WebAssemblyaplikacje są renderowane tylko na kliencie za pośrednictwem środowiska uruchomieniowego webAssembly po stronie klienta i nie mają pojęcia trybu renderowania. Jeśli tryb renderowania jest stosowany do składnika w Blazor WebAssembly aplikacji, oznaczenie trybu renderowania nie ma wpływu na renderowanie składnika.

Tryby renderowania

Każdy składnik w programie Blazor Web App przyjmuje tryb renderowania w celu określenia modelu hostingu, którego używa, gdzie jest renderowany i czy jest interaktywny.

W poniższej tabeli przedstawiono dostępne tryby renderowania składników renderowania Razor w obiekcie Blazor Web App. Aby zastosować tryb renderowania do składnika, należy użyć @rendermode dyrektywy w wystąpieniu składnika lub definicji składnika. W dalszej części tego artykułu przedstawiono przykłady dla każdego scenariusza trybu renderowania.

Nazwa/nazwisko	opis	Lokalizacja renderowania	Interakcyjny
Serwer statyczny	Renderowanie statyczne po stronie serwera (statyczne SSR)	Serwer	❌Nie
Serwer interaktywny	Interaktywne renderowanie po stronie serwera (interakcyjne SSR) przy użyciu polecenia Blazor Server.	Serwer	✔️Tak
Interakcyjny zestaw WebAssembly	Renderowanie po stronie klienta (CSR) przy użyciu Blazor WebAssembly†.	Klient	✔️Tak
Autointerakcyjne	Interaktywna usługa SSR początkowo, Blazor Server a następnie CSR podczas kolejnych wizyt po Blazor pobraniu pakietu.	Serwer, a następnie klient	✔️Tak

† przyjmuje się, że renderowanie po stronie klienta (CSR) jest interaktywne. "Interaktywne renderowanie po stronie klienta" i "interakcyjne csr" nie są używane przez branżę Blazor ani w dokumentacji.

Prerendering jest domyślnie włączony dla składników interaktywnych. Wskazówki dotyczące kontrolowania prerenderingu podano w dalszej części tego artykułu. Aby uzyskać ogólną terminologię branżową dotyczącą pojęć związanych z renderowaniem klientów i serwerów, zobacz ASP.NET Podstawowe Blazor informacje.

W poniższych przykładach pokazano ustawienie trybu renderowania składnika z kilkoma podstawowymi Razor funkcjami składników.

Aby przetestować zachowania trybu renderowania lokalnie, możesz umieścić następujące składniki w aplikacji utworzonej na podstawie szablonu Blazor Web App projektu. Podczas tworzenia aplikacji wybierz opcje z menu rozwijanych (Visual Studio) lub zastosuj opcje interfejsu wiersza polecenia (interfejs wiersza polecenia platformy.NET), aby włączyć interakcyjność po stronie serwera i po stronie klienta. Aby uzyskać wskazówki dotyczące tworzenia elementu Blazor Web App, zobacz Tooling for ASP.NET Core (Narzędzia dla platformy ASP.NET Core Blazor).

Włączanie obsługi interakcyjnych trybów renderowania

Należy Blazor Web App skonfigurować element tak, aby obsługiwał tryby renderowania interakcyjnego. Następujące rozszerzenia są automatycznie stosowane do aplikacji utworzonych na podstawie Blazor Web App szablonu projektu podczas tworzenia aplikacji. Poszczególne składniki są nadal wymagane do deklarowania trybu renderowania zgodnie z sekcją Tryby renderowania po skonfigurowaniu usług składników i punktów końcowych w pliku aplikacjiProgram.

Usługi dla Razor składników są dodawane przez wywołanie metody AddRazorComponents.

Rozszerzenia konstruktora składników:

• AddInteractiveServerComponents dodaje usługi do obsługi renderowania składników interactive server.
• AddInteractiveWebAssemblyComponents dodaje usługi do obsługi renderowania składników Interactive WebAssembly.

MapRazorComponents odnajduje dostępne składniki i określa składnik główny aplikacji (pierwszy załadowany składnik), który domyślnie jest składnikiem App (App.razor).

Rozszerzenia konstruktora konwencji punktu końcowego:

• AddInteractiveServerRenderMode Konfiguruje interaktywne renderowanie po stronie serwera (interakcyjne SSR) dla aplikacji.
• AddInteractiveWebAssemblyRenderMode Konfiguruje tryb renderowania Interactive WebAssembly dla aplikacji.

Uwaga

Aby uzyskać orientację dotyczącą umieszczania interfejsu API w poniższych przykładach, sprawdź Program plik aplikacji wygenerowanej na podstawie szablonu Blazor Web App projektu. Aby uzyskać wskazówki dotyczące tworzenia elementu Blazor Web App, zobacz Tooling for ASP.NET Core (Narzędzia dla platformy ASP.NET Core Blazor).

Przykład 1: Następujący Program interfejs API plików dodaje usługi i konfigurację do włączania interakcyjnego przewodnika SSR:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

Przykład 2: Następujący Program interfejs API plików dodaje usługi i konfigurację do włączania trybu renderowania interakcyjnego zestawu WebAssembly:

builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode();

Przykład 3: Następujący Program interfejs API plików dodaje usługi i konfigurację do włączania trybu renderowania Interactive Server, Interactive WebAssembly i Interactive Auto render:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode();

Blazor używa modelu hostingu do pobierania Blazor WebAssembly i wykonywania składników korzystających z trybu renderowania interactive WebAssembly. Do skonfigurowania Blazor WebAssembly hostingu dla tych składników jest wymagany oddzielny projekt klienta. Projekt klienta zawiera kod uruchamiania hosta Blazor WebAssembly i konfiguruje środowisko uruchomieniowe platformy .NET do uruchamiania w przeglądarce. Szablon Blazor Web App dodaje ten projekt klienta po wybraniu opcji włączenia interakcyjności zestawu WebAssembly. Wszystkie składniki korzystające z trybu renderowania Interactive WebAssembly powinny być kompilowane z projektu klienta, aby zostały uwzględnione w pobranym pakiecie aplikacji.

Stosowanie trybu renderowania do wystąpienia składnika

Aby zastosować tryb renderowania do wystąpienia składnika, użyj atrybutu @rendermodeRazor dyrektywy, w którym jest używany składnik.

W poniższym przykładzie interakcyjne renderowanie po stronie serwera (interakcyjne SSR) jest stosowane do Dialog wystąpienia składnika:

<Dialog @rendermode="InteractiveServer" />

Uwaga

Blazor szablony zawierają dyrektywę statyczną using dla RenderMode pliku aplikacji _Imports (Components/_Imports.razor) w celu uzyskania krótszej @rendermode składni:

@using static Microsoft.AspNetCore.Components.Web.RenderMode

Bez powyższej dyrektywy składniki muszą określać klasę statyczną RenderMode w @rendermode składni:

<Dialog @rendermode="RenderMode.InteractiveServer" />

Możesz również odwoływać się do wystąpień niestandardowego trybu renderowania bezpośrednio przy użyciu konfiguracji niestandardowej. Aby uzyskać więcej informacji, zobacz sekcję Niestandardowe tryby renderowania skróconego w dalszej części tego artykułu.

Stosowanie trybu renderowania do definicji składnika

Aby określić tryb renderowania składnika w ramach jego definicji, użyj @rendermodeRazor dyrektywy i odpowiedniego atrybutu trybu renderowania.

@page "..."
@rendermode InteractiveServer

Stosowanie trybu renderowania do definicji składnika jest często używane podczas stosowania trybu renderowania do określonej strony. Strony routable używają tego samego trybu renderowania co Router składnik renderowany na stronie.

Technicznie jest zarówno dyrektywą, @rendermode jak Razori atrybutemRazor dyrektywy. Semantyka jest podobna, ale istnieją różnice. @rendermode Dyrektywa dotyczy definicji składnika, więc wystąpienie trybu renderowania, do którego się odwołuje, musi być statyczne. Atrybut @rendermode dyrektywy może przyjmować dowolne wystąpienie trybu renderowania.

Uwaga

Autorzy składników powinni unikać sprzęgania implementacji składnika z określonym trybem renderowania. Zamiast tego autorzy składników powinni zazwyczaj projektować składniki do obsługi dowolnego trybu renderowania lub modelu hostingu. Implementacja składnika powinna unikać założeń dotyczących tego, gdzie jest uruchomiona (serwer lub klient) i powinna bezpiecznie zmniejszyć wydajność podczas renderowania statycznego. Określenie trybu renderowania w definicji składnika może być konieczne, jeśli składnik nie jest tworzone bezpośrednio (na przykład za pomocą składnika strony routingu) lub aby określić tryb renderowania dla wszystkich wystąpień składników.

Stosowanie trybu renderowania do całej aplikacji

Aby ustawić tryb renderowania dla całej aplikacji, wskaż tryb renderowania na najwyższym poziomie składnika interaktywnego w hierarchii składników aplikacji, który nie jest składnikiem głównym.

Uwaga

Tworzenie składnika głównego interakcyjnego, takiego jak App składnik, nie jest obsługiwane. W związku z tym tryb renderowania dla całej aplikacji nie może być ustawiany bezpośrednio przez App składnik.

W przypadku aplikacji opartych na szablonie Blazor Web App projektu tryb renderowania przypisany do całej aplikacji jest zwykle określany, gdzie Routes składnik jest używany w składniku App (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Składnik Router propaguje jego tryb renderowania na stronach, które kieruje.

Zazwyczaj należy również ustawić ten sam tryb renderowania interaktywnego w składnikuHeadOutlet, który znajduje się również w App składniku Blazor Web App wygenerowanym na podstawie szablonu projektu:

<HeadOutlet @rendermode="InteractiveServer" />

W przypadku aplikacji, które przyjmują interaktywny tryb renderowania po stronie klienta (WebAssembly lub Auto) i włączają tryb renderowania dla całej aplikacji za pośrednictwem Routes składnika:

• Umieść lub przenieś pliki układu i nawigacji folderu aplikacji Components/Layout serwera do .Client folderu projektu Layout . Layout Utwórz folder w projekcie.Client, jeśli nie istnieje.
• Umieść lub przenieś składniki folderu aplikacji Components/Pages serwera do .Client folderu projektu Pages . Pages Utwórz folder w projekcie.Client, jeśli nie istnieje.
• Umieść lub przenieś Routes składnik folderu aplikacji Components serwera do .Client folderu głównego projektu.

Aby włączyć globalną interakcyjność podczas tworzenia elementu Blazor Web App:

• Visual Studio: ustaw listę rozwijaną Lokalizacja interakcyjna na Global.
• Interfejs wiersza polecenia platformy -ai|--all-interactive .NET: użyj opcji .

Aby uzyskać więcej informacji, zobacz Tooling for ASP.NET Core Blazor.

Programowe stosowanie trybu renderowania

Właściwości i pola mogą przypisywać tryb renderowania.

Drugie podejście opisane w tej sekcji, ustawienie trybu renderowania według wystąpienia składnika, jest szczególnie przydatne, gdy specyfikacja aplikacji wywołuje jeden lub więcej składników do wdrożenia statycznego przewodnika SSR w aplikacji interaktywnej globalnie. Ten scenariusz jest omówiony na stronach statycznych usług SSR w globalnej sekcji aplikacji interaktywnej w dalszej części tego artykułu.

Ustawianie trybu renderowania według definicji składnika

Definicja składnika może definiować tryb renderowania za pomocą pola prywatnego:

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

Ustawianie trybu renderowania według wystąpienia składnika

Poniższy przykład dotyczy interaktywnego renderowania po stronie serwera (interakcyjnego żądania SSR).

<Routes @rendermode="PageRenderMode" />

...

@code {
    private IComponentRenderMode? PageRenderMode => InteractiveServer;
}

Dodatkowe informacje na temat propagacji trybu renderowania znajdują się w sekcji Propagacja trybu renderowania w dalszej części tego artykułu. Na stronach statycznych usług SSR w globalnej interaktywnej aplikacji pokazano, jak za pomocą powyższego podejścia wdrożyć statyczny przewodnik SSR w aplikacji interaktywnej globalnie.

Wykrywanie lokalizacji renderowania, interakcyjności i przypisanego trybu renderowania w czasie wykonywania

Właściwości ComponentBase.RendererInfo i ComponentBase.AssignedRenderMode umożliwiają aplikacji wykrywanie szczegółów dotyczących lokalizacji, interakcyjności i przypisanego trybu renderowania składnika:

• RendererInfo.Name zwraca lokalizację, w której jest wykonywany składnik:
  • Static: Na serwerze (SSR) i niezdolności do interakcyjności.
  • Server: Na serwerze (SSR) i może interakcyjnie działać po wstępnego przetwarzania.
  • WebAssembly: Na kliencie (CSR) i mogącym interakcyjnie działać po wstępnie.
  • WebView: na urządzeniu natywnym i może interakcyjnie działać po wstępnegoenderowania.
• RendererInfo.IsInteractive wskazuje, czy składnik obsługuje interakcyjność w czasie renderowania. Wartość jest true określana podczas interakcyjnego renderowania lub false w przypadku prerenderingu lub statycznego przewodnika SSR (RendererInfo.Name z Static).
• ComponentBase.AssignedRenderMode Uwidacznia przypisany przez składnik tryb renderowania:
  • InteractiveServer dla serwera interakcyjnego.
  • InteractiveAuto w przypadku autointerakcyjnego.
  • InteractiveWebAssembly w przypadku interaktywnego zestawu WebAssembly.

Składniki używają tych właściwości do renderowania zawartości w zależności od ich lokalizacji lub stanu interakcyjności. W poniższych przykładach przedstawiono typowe przypadki użycia.

Wyświetlaj zawartość do momentu interakcyjnego składnika:

@if (!RendererInfo.IsInteractive)
{
    <p>Connecting to the assistant...</p>
}
else
{
    ...
}

Wyłącz przycisk, dopóki składnik nie będzie interakcyjny:

<button @onclick="Send" disabled="@(!RendererInfo.IsInteractive)">
    Send
</button>

Wyłącz formularz podczas prerenderingu i włącz formularz, gdy składnik jest interaktywny:

<EditForm Model="Movie" ...>
    <fieldset disabled="@disabled">

        ...

        <button type="submit" >Save</button>
    </fieldset>
</EditForm>

@code {
    private bool disabled = true;

    [SupplyParameterFromForm]
    private Movie? Movie { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Movie ??= await ...;

        if (RendererInfo.IsInteractive)
        {
            disabled = false;
        }
    }
}

Renderowanie znaczników w celu obsługi regularnej akcji HTML, jeśli składnik jest statycznie renderowany:

@if (AssignedRenderMode is null)
{
    // The render mode is Static Server
    <form action="/movies">
        <input type="text" name="titleFilter" />
        <input type="submit" value="Search" />
    </form>
}
else
{
    // The render mode is Interactive Server, WebAssembly, or Auto
    <input @bind="titleFilter" />
    <button @onclick="FilterMovies">Search</button>
}

W powyższym przykładzie:

• Gdy wartość parametru AssignedRenderMode to null, składnik przyjmuje statyczny SSR. Blazor Obsługa zdarzeń nie działa w przeglądarce ze statycznym żądaniem SSR, dlatego składnik przesyła formularz (żądanie GET) z ciągiem zapytania ustawionym titleFilter na wartość użytkownika <input> . Składnik Movie (/movie) może odczytać ciąg zapytania i przetworzyć wartość w titleFilter celu renderowania składnika z filtrowanych wyników.
• W przeciwnym razie tryb renderowania to dowolny z InteractiveServer, InteractiveWebAssemblylub InteractiveAuto. Składnik może używać delegata programu obsługi zdarzeń (FilterMovies) i wartości powiązanej <input> z elementem (titleFilter) w celu interakcyjnego filtrowania filmów za pośrednictwem połączenia w tle SignalR .

Blazor przykłady dokumentacji dla programu Blazor Web Apps

W przypadku korzystania z elementu Blazor Web Appwiększość przykładowych Blazor składników dokumentacji wymaga interakcyjności do działania i zademonstrowania pojęć omówionych w artykułach. Podczas testowania przykładowego składnika dostarczonego przez artykuł upewnij się, że aplikacja przyjmuje globalną interakcyjność lub składnik przyjmuje tryb renderowania interaktywnego.

Prerendering

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.

Prerendering jest domyślnie włączony dla składników interaktywnych.

Nawigacja wewnętrzna na potrzeby routingu interakcyjnego nie obejmuje żądania nowej zawartości strony z serwera. W związku z tym wstępne przetwarzanie nie występuje w przypadku żądań stron wewnętrznych, w tym dla rozszerzonej nawigacji. Aby uzyskać więcej informacji, zobacz Routing statyczny i interakcyjny, Routing interakcyjny i wstępne oraz Ulepszona nawigacja i obsługa formularzy.

Wyłączenie prerenderingu przy użyciu poniższych technik ma zastosowanie tylko w przypadku trybów renderowania najwyższego poziomu. Jeśli składnik nadrzędny określa tryb renderowania, ustawienia wstępne jego elementów podrzędnych są ignorowane. To zachowanie jest badane pod kątem możliwych zmian w wydaniu platformy .NET 10 w listopadzie 2025 r.

Aby wyłączyć prerendering dla wystąpienia składnika, przekaż prerender flagę z wartością false do trybu renderowania:

• <... @rendermode="new InteractiveServerRenderMode(prerender: false)" />
• <... @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />
• <... @rendermode="new InteractiveAutoRenderMode(prerender: false)" />

Aby wyłączyć prerendering w definicji składnika:

• @rendermode @(new InteractiveServerRenderMode(prerender: false))
• @rendermode @(new InteractiveWebAssemblyRenderMode(prerender: false))
• @rendermode @(new InteractiveAutoRenderMode(prerender: false))

Aby wyłączyć wstępne przetwarzanie dla całej aplikacji, wskaż tryb renderowania na najwyższym poziomie składnika interaktywnego w hierarchii składników aplikacji, który nie jest składnikiem głównym.

W przypadku aplikacji opartych na szablonie Blazor Web App projektu tryb renderowania przypisany do całej aplikacji jest określony, gdzie Routes składnik jest używany w składniku App (Components/App.razor). W poniższym przykładzie ustawiono tryb renderowania aplikacji na interaktywny serwer z wyłączoną prerenderingiem:

<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />

Ponadto wyłącz prerendering składnika HeadOutlet w składniku:App

<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />

Tworzenie składnika głównego, takiego jak App składnik, interakcyjne z @rendermode dyrektywą w górnej części pliku definicji składnika głównego (.razor) nie jest obsługiwane. W związku z tym prerendering nie może być wyłączony bezpośrednio przez App składnik.

Renderowanie statyczne po stronie serwera (statyczne SSR)

Składniki używają statycznego renderowania po stronie serwera (statyczny SSR). Składnik renderuje się do strumienia odpowiedzi i interakcyjność nie jest włączona.

W poniższym przykładzie nie ma oznaczenia dla trybu renderowania składnika, więc składnik dziedziczy jego tryb renderowania z elementu nadrzędnego. Ponieważ żaden składnik programu ancestor nie określa trybu renderowania, następujący składnik jest statycznie renderowany na serwerze. Przycisk nie jest interaktywny i nie wywołuje metody po wybraniu UpdateMessage . Wartość message nie zmienia się, a składnik nie jest rerendered w odpowiedzi na zdarzenia interfejsu użytkownika.

RenderMode1.razor:

@page "/render-mode-1"

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jeśli używasz poprzedniego składnika lokalnie w Blazor Web Apppliku , umieść składnik w folderze projektu Components/Pages serwera. Projekt serwera to projekt rozwiązania o nazwie, która nie kończy się na .Client. Gdy aplikacja jest uruchomiona, przejdź do /render-mode-1 na pasku adresu przeglądarki.

Podczas statycznego przetwarzania SSR Razor żądania strony składników są przetwarzane przez przetwarzanie żądań potoku oprogramowania pośredniczącego po stronie serwera ASP.NET Core na potrzeby routingu i autoryzacji. Dedykowane Blazor funkcje routingu i autoryzacji nie działają, ponieważ Razor składniki nie są renderowane podczas przetwarzania żądań po stronie serwera. Blazor funkcje routera w składniku Routes , które nie są dostępne podczas statycznego przewodnika SSR, obejmują wyświetlanie:

• Nieautoryzowana zawartość () (<NotAuthorized>...</NotAuthorized>): zazwyczaj przetwarza nieautoryzowane żądania na serwerze, dostosowując zachowanie oprogramowania pośredniczącego autoryzacji. Blazor Web AppNotAuthorized

• Nie znaleziono zawartości () (NotFound<NotFound>...</NotFound>): Blazor Web Appzazwyczaj przetwarzają nieprawidłowe żądania adresów URL na serwerze przez wyświetlenie wbudowanego interfejsu użytkownika przeglądarki 404 lub zwrócenie niestandardowej strony 404 (lub innej odpowiedzi) za pośrednictwem oprogramowania pośredniczącego ASP.NET Core (na przykład UseStatusCodePagesWithRedirects / dokumentacji interfejsu API).

Jeśli aplikacja wykazuje interakcyjność na poziomie głównym, przetwarzanie żądań po stronie serwera ASP.NET Core nie jest uwzględniane po początkowym statycznym przewodniku SSR, co oznacza, że poprzednie Blazor funkcje działają zgodnie z oczekiwaniami.

Ulepszona nawigacja przy użyciu statycznego przewodnika SSR wymaga szczególnej uwagi podczas ładowania kodu JavaScript. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor JavaScript z renderowaniem statycznym po stronie serwera (static SSR) .

Interaktywne renderowanie po stronie serwera (interakcyjne SSR)

Interaktywne renderowanie po stronie serwera (interakcyjne SSR) renderuje składnik interaktywnie z serwera przy użyciu polecenia Blazor Server. Interakcje użytkownika są obsługiwane za pośrednictwem połączenia w czasie rzeczywistym z przeglądarką. Połączenie obwodu jest ustanawiane podczas renderowania składnika serwera.

W poniższym przykładzie tryb renderowania jest ustawiany interakcyjny SSR przez dodanie @rendermode InteractiveServer do definicji składnika. Przycisk wywołuje metodę po wybraniu UpdateMessage . Wartość message zmian i składnik jest rerendered w celu zaktualizowania komunikatu w interfejsie użytkownika.

RenderMode2.razor:

@page "/render-mode-2"
@rendermode InteractiveServer

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jeśli używasz poprzedniego składnika w elemencie Blazor Web App, umieść składnik w folderze projektu Components/Pages serwera. Projekt serwera to projekt rozwiązania o nazwie, która nie kończy się na .Client. Gdy aplikacja jest uruchomiona, przejdź do /render-mode-2 na pasku adresu przeglądarki.

Renderowanie po stronie klienta (CSR)

Renderowanie po stronie klienta (CSR) renderuje składnik interaktywnie na kliencie przy użyciu polecenia Blazor WebAssembly. Środowisko uruchomieniowe platformy .NET i pakiet aplikacji są pobierane i buforowane, gdy składnik WebAssembly jest początkowo renderowany. Składniki używające csr muszą być tworzone z oddzielnego projektu klienta, który konfiguruje Blazor WebAssembly hosta.

W poniższym przykładzie tryb renderowania jest ustawiony na csr za pomocą @rendermode InteractiveWebAssemblypolecenia . Przycisk wywołuje metodę po wybraniu UpdateMessage . Wartość message zmian i składnik jest rerendered w celu zaktualizowania komunikatu w interfejsie użytkownika.

RenderMode3.razor:

@page "/render-mode-3"
@rendermode InteractiveWebAssembly

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jeśli używasz poprzedniego składnika lokalnie w Blazor Web Apppliku , umieść składnik w folderze projektu Pages klienta. Projekt klienta to projekt rozwiązania o nazwie kończącej się na .Client. Gdy aplikacja jest uruchomiona, przejdź do /render-mode-3 na pasku adresu przeglądarki.

Automatyczne renderowanie (automatyczne)

Automatyczne renderowanie (automatyczne) określa sposób renderowania składnika w czasie wykonywania. Składnik jest początkowo renderowany przy użyciu interaktywnego renderowania po stronie serwera (interakcyjnego SSR) przy użyciu modelu hostingu Blazor Server . Środowisko uruchomieniowe platformy .NET i pakiet aplikacji są pobierane do klienta w tle i buforowane, aby można było ich używać podczas przyszłych wizyt.

Tryb automatycznego renderowania nigdy nie zmienia dynamicznie trybu renderowania składnika już na stronie. Tryb automatycznego renderowania podejmuje początkową decyzję o tym, jakiego typu interakcyjność ma być używana dla składnika, a następnie składnik zachowuje ten typ interakcyjności tak długo, jak to jest na stronie. Jednym z czynników w tej początkowej decyzji jest rozważenie, czy składniki już istnieją na stronie z interakcyjnością zestawu WebAssembly/serwera. Tryb automatyczny preferuje wybranie trybu renderowania zgodnego z trybem renderowania istniejących składników interaktywnych. Powodem, dla którego tryb automatyczny preferuje korzystanie z istniejącego trybu interakcyjnego, jest uniknięcie wprowadzenia nowego interakcyjnego środowiska uruchomieniowego, które nie współużytkuje stanu z istniejącym środowiskiem uruchomieniowym.

Składniki korzystające z trybu automatycznego renderowania muszą być tworzone z oddzielnego projektu klienta, który konfiguruje Blazor WebAssembly hosta.

W poniższym przykładzie składnik jest interaktywny w całym procesie. Przycisk wywołuje metodę po wybraniu UpdateMessage . Wartość message zmian i składnik jest rerendered w celu zaktualizowania komunikatu w interfejsie użytkownika. Początkowo składnik jest renderowany interaktywnie z serwera, ale podczas kolejnych wizyt jest renderowany z klienta po pobraniu i buforowanym pakiecie aplikacji środowiska uruchomieniowego platformy .NET.

RenderMode4.razor:

@page "/render-mode-4"
@rendermode InteractiveAuto

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jeśli używasz poprzedniego składnika lokalnie w Blazor Web Apppliku , umieść składnik w folderze projektu Pages klienta. Projekt klienta to projekt rozwiązania o nazwie kończącej się na .Client. Gdy aplikacja jest uruchomiona, przejdź do /render-mode-4 na pasku adresu przeglądarki.

Propagacja trybu renderowania

Tryby renderowania propagują hierarchię składników.

Reguły stosowania trybów renderowania:

• Domyślny tryb renderowania to Statyczny.
• Tryby renderowania Interactive Server (InteractiveServer), Interactive WebAssembly (InteractiveWebAssembly) i Interactive Auto (InteractiveAuto) mogą być używane z poziomu składnika, w tym przy użyciu różnych trybów renderowania dla składników równorzędnych.
• Nie można przełączyć się na inny interaktywny tryb renderowania w składniku podrzędnym. Na przykład składnik serwera nie może być elementem podrzędnym składnika WebAssembly.
• Parametry przekazywane do interaktywnego składnika podrzędnego z elementu nadrzędnego statycznego muszą być serializowalne w formacie JSON. Oznacza to, że nie można przekazać fragmentów renderowania ani zawartości podrzędnej ze składnika nadrzędnego Static do interaktywnego składnika podrzędnego.

W poniższych przykładach użyto składnika bez routingu, niestronicowego SharedMessage . Składnik niezależny SharedMessage od trybu renderowania nie stosuje trybu renderowania z dyrektywą@attribute. Jeśli testujesz te scenariusze za pomocą Blazor Web Appelementu , umieść następujący składnik w folderze aplikacji Components .

SharedMessage.razor:

<p>@Greeting</p>

<button @onclick="UpdateMessage">Click me</button> @message

<p>@ChildContent</p>

@code {
    private string message = "Not updated yet.";

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    [Parameter]
    public string Greeting { get; set; } = "Hello!";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Dziedziczenie trybu renderowania

SharedMessage Jeśli składnik zostanie umieszczony w statycznie renderowanych składnikach nadrzędnych, SharedMessage składnik jest również renderowany statycznie i nie jest interaktywny. Przycisk nie wywołuje UpdateMessageelementu , a komunikat nie jest aktualizowany.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

SharedMessage Jeśli składnik zostanie umieszczony w składniku definiującym tryb renderowania, dziedziczy zastosowany tryb renderowania.

W poniższym przykładzie SharedMessage składnik jest interaktywny za pośrednictwem połączenia z klientem SignalR . Przycisk wywołuje metodę UpdateMessage, a komunikat jest aktualizowany.

RenderMode6.razor:

@page "/render-mode-6"
@rendermode InteractiveServer

<SharedMessage />

Składniki podrzędne z różnymi trybami renderowania

W poniższym przykładzie oba SharedMessage składniki są wstępnie zainstalowane i wyświetlane po wyświetleniu strony w przeglądarce.

• Pierwszy SharedMessage składnik z interaktywnym renderowaniem po stronie serwera (interactive SSR) jest interaktywny po Blazorustanowieniu obwodu SignalR .
• Drugi SharedMessage składnik z renderowaniem po stronie klienta (CSR) jest interaktywny po Blazor pobraniu pakietu aplikacji, a środowisko uruchomieniowe platformy .NET jest aktywne na kliencie.

RenderMode7.razor:

@page "/render-mode-7"

<SharedMessage @rendermode="InteractiveServer" />
<SharedMessage @rendermode="InteractiveWebAssembly" />

Składnik podrzędny z parametrem z możliwością serializacji

W poniższym przykładzie pokazano interakcyjny składnik podrzędny, który przyjmuje parametr . Parametry muszą być serializowalne.

RenderMode8.razor:

@page "/render-mode-8"

<SharedMessage @rendermode="InteractiveServer" Greeting="Welcome!" />

Parametry składnika, które nie można serializować, takie jak zawartość podrzędna lub fragment renderowania, nie są obsługiwane. W poniższym przykładzie przekazanie zawartości podrzędnej SharedMessage do składnika powoduje wystąpienie błędu w czasie wykonywania.

RenderMode9.razor:

@page "/render-mode-9"

<SharedMessage @rendermode="InteractiveServer">
    Child content
</SharedMessage>

❌Błąd:

System.InvalidOperationException: Nie można przekazać parametru "ChildContent" do składnika "SharedMessage" z trybem rendermode "InteractiveServerRenderMode". Jest to spowodowane tym, że parametr jest typu delegata "Microsoft.AspNetCore.Components.RenderFragment", który jest dowolnym kodem i nie można go serializować.

Aby obejść powyższe ograniczenie, opakuj składnik podrzędny w innym składniku, który nie ma parametru. Jest to podejście podjęte w szablonie Blazor Web App projektu ze składnikiem Routes (Components/Routes.razor) w celu opakowania Router składnika.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

W powyższym przykładzie:

• Zawartość podrzędna jest przekazywana do SharedMessage składnika bez generowania błędu środowiska uruchomieniowego.
• Składnik SharedMessage jest renderowany interaktywnie na serwerze.

Składnik podrzędny z innym trybem renderowania niż jego element nadrzędny

Nie próbuj stosować innego interaktywnego trybu renderowania do składnika podrzędnego niż tryb renderowania elementu nadrzędnego.

Następujący składnik powoduje błąd środowiska uruchomieniowego po renderowaniu składnika:

RenderMode11.razor:

@page "/render-mode-11"
@rendermode InteractiveServer

<SharedMessage @rendermode="InteractiveWebAssembly" />

❌Błąd:

Cannot create a component of type 'BlazorSample.Components.SharedMessage' because its render mode 'Microsoft.AspNetCore.Components.Web.InteractiveWebAssemblyRenderMode' is not supported by Interactive Server rendering.

Statyczne strony SSR w aplikacji interaktywnej globalnie

Istnieją przypadki, w których specyfikacja aplikacji wywołuje składniki do wdrożenia statycznego renderowania po stronie serwera (statycznego SSR) i działają tylko na serwerze, podczas gdy rest aplikacja używa trybu renderowania interaktywnego.

Takie podejście jest przydatne tylko wtedy, gdy aplikacja ma określone strony, które nie mogą pracować z interaktywnym serwerem lub renderowaniem zestawu WebAssembly. Na przykład zastosuj to podejście dla stron, które zależą od odczytywania/zapisywania plików cookie HTTP i mogą działać tylko w cyklu żądania/odpowiedzi zamiast renderowania interakcyjnego. W przypadku stron, które działają z renderowaniem interaktywnym, nie należy wymuszać używania statycznego renderowania SSR, ponieważ jest mniej wydajne i mniej elastyczne dla użytkownika końcowego.

Oznacz dowolną Razor stronę składnika za pomocą atrybutu przypisanego @attribute[ExcludeFromInteractiveRouting]Razor do dyrektywy:

@attribute [ExcludeFromInteractiveRouting]

Zastosowanie atrybutu powoduje przejście do strony w celu zakończenia routingu interakcyjnego. Nawigacja przychodząca jest zmuszona do ponownego załadowania pełnej strony zamiast tego rozpoznawania strony za pośrednictwem routingu interakcyjnego. Ponowne ładowanie pełnej strony wymusza składnik główny najwyższego poziomu, zazwyczaj App składnik (App.razor), aby rerender z serwera, dzięki czemu aplikacja może przełączyć się do innego trybu renderowania najwyższego poziomu.

RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting Metoda rozszerzenia umożliwia składnikowi wykrywanie, czy [ExcludeFromInteractiveRouting] atrybut jest stosowany do bieżącej strony.

W składniku App użyj wzorca w poniższym przykładzie:

• Strony, które nie są adnotacjami z atrybutem [ExcludeFromInteractiveRouting] domyślnym dla trybu renderowania InteractiveServer z globalną interakcyjnością. Możesz zastąpić InteractiveServer ciąg ciągiem InteractiveWebAssembly lub InteractiveAuto określić inny domyślny tryb renderowania globalnego.
• Strony z adnotacjami atrybutu [ExcludeFromInteractiveRouting] przyjmują statyczny SSR (PageRenderMode jest przypisany ).null

<!DOCTYPE html>
<html>
<head>
    ...
    <HeadOutlet @rendermode="@PageRenderMode" />
</head>
<body>
    <Routes @rendermode="@PageRenderMode" />
    ...
</body>
</html>

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? PageRenderMode
        => HttpContext.AcceptsInteractiveRouting() ? InteractiveServer : null;
}

Alternatywą dla metody RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting rozszerzenia jest ręczne odczytywanie metadanych punktu końcowego przy użyciu polecenia HttpContext.GetEndpoint()?.Metadata.

Nie można rozpoznać usług po stronie klienta podczas wstępnej obsługi

Zakładając, że prerendering nie jest wyłączony dla składnika lub aplikacji, składnik w .Client projekcie jest wstępnie zainstalowany na serwerze. Ponieważ serwer nie ma dostępu do zarejestrowanych usług po stronie Blazor klienta, nie można wstrzyknąć tych usług do składnika bez otrzymania błędu, że nie można odnaleźć usługi podczas prerenderingu.

Rozważmy na przykład następujący Home składnik w projekcie .Client w Blazor Web App obiekcie z globalnym interaktywnym zestawem WebAssembly lub interaktywnym renderowaniem automatycznym. Składnik próbuje wstrzyknąć, IWebAssemblyHostEnvironment aby uzyskać nazwę środowiska.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    Environment: @Environment.Environment
</p>

Podczas prerenderingu nie występuje błąd czasu kompilacji, ale występuje błąd środowiska uruchomieniowego:

Nie można podać wartości właściwości "Environment" dla typu "BlazorSample.Client.Pages".Home Nie ma zarejestrowanej usługi typu "Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment".

Ten błąd występuje, ponieważ składnik musi kompilować i wykonywać na serwerze podczas prerenderingu, ale IWebAssemblyHostEnvironment nie jest zarejestrowaną usługą na serwerze.

Jeśli aplikacja nie wymaga wartości podczas prerenderingu, ten problem można rozwiązać przez wstrzyknięcie IServiceProvider w celu uzyskania usługi zamiast samego typu usługi:

@page "/"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IServiceProvider Services

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    <b>Environment:</b> @environmentName
</p>

@code {
    private string? environmentName;

    protected override void OnInitialized()
    {
        if (Services.GetService<IWebAssemblyHostEnvironment>() is { } env)
        {
            environmentName = env.Environment;
        }
    }
}

Jednak powyższe podejście nie jest przydatne, jeśli logika wymaga wartości podczas prerenderingu.

Można również uniknąć problemu, jeśli wyłączysz prerendering dla składnika, ale jest to skrajna miara do podjęcia w wielu przypadkach, które mogą nie spełniać specyfikacji składnika.

Istnieją trzy podejścia, które można zastosować, aby rozwiązać ten scenariusz. Poniżej przedstawiono listę spośród najbardziej zalecanych do najmniej zalecanych:

• Zalecane w przypadku usług współużytkowanych struktur: w przypadku usług udostępnionych struktur, które nie są zarejestrowane po stronie serwera w głównym projekcie, zarejestruj usługi w głównym projekcie, co udostępnia je podczas prerenderingu. Aby zapoznać się z przykładem tego scenariusza, zobacz wskazówki dotyczące HttpClient usług w temacie Wywoływanie internetowego interfejsu API z aplikacji ASP.NET CoreBlazor.

• Zalecane w przypadku usług spoza platformy udostępnionej: utwórz niestandardową implementację usługi dla usługi na serwerze. Użyj usługi zwykle w interaktywnych składnikach .Client projektu. Aby zapoznać się z pokazem tego podejścia, zobacz ASP.NET Core environments (Środowiska podstawowe ASP.NET).Blazor

• Utwórz abstrakcję usługi i utwórz implementacje dla usługi w .Client projektach serwera i . Zarejestruj usługi w każdym projekcie. Wstrzykiwanie usługi niestandardowej w składniku.

• Może być możliwe dodanie .Client odwołania do pakietu projektu do pakietu po stronie serwera i powrót do korzystania z interfejsu API po stronie serwera podczas prerenderingu na serwerze.

Odnajdywanie składników z dodatkowych zestawów

Dodatkowe zestawy muszą zostać ujawnione ramom Blazor w celu odnalezienia składników routingu Razor w projektach, do których się odwołujesz. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor routing i nawigacja.

Zamykanie obwodów, gdy nie ma pozostałych składników programu Interactive Server

Składniki interaktywnego serwera obsługują zdarzenia internetowego interfejsu użytkownika przy użyciu połączenia w czasie rzeczywistym z przeglądarką nazywaną obwodem. Obwód i skojarzony z nim stan są tworzone, gdy jest renderowany główny składnik interactive server. Obwód jest zamykany, gdy na stronie nie ma żadnych pozostałych składników serwera interakcyjnego, co zwalnia zasoby serwera.

Niestandardowe tryby renderowania skróconego

Dyrektywa @rendermode przyjmuje pojedynczy parametr, który jest statycznym wystąpieniem typu IComponentRenderMode. Atrybut @rendermode dyrektywy może przyjmować dowolne wystąpienie trybu renderowania, statyczne lub nie. Platforma Blazor udostępnia klasę RenderMode statyczną z niektórymi wstępnie zdefiniowanymi trybami renderowania dla wygody, ale możesz utworzyć własne.

Zwykle składnik używa następującej @rendermode dyrektywy w celu wyłączenia wstępnegoenderingu:

@rendermode @(new InteractiveServerRenderMode(prerender: false))

Rozważmy jednak poniższy przykład, który tworzy skrócony interaktywny tryb renderowania po stronie serwera bez wstępnego przetwarzania _Imports za pośrednictwem pliku aplikacji (Components/_Imports.razor):

public static IComponentRenderMode InteractiveServerWithoutPrerendering { get; } = 
    new InteractiveServerRenderMode(prerender: false);

Użyj trybu renderowania skróconego w składnikach w folderze Components :

@rendermode InteractiveServerWithoutPrerendering

Alternatywnie pojedyncze wystąpienie składnika może zdefiniować niestandardowy tryb renderowania za pomocą pola prywatnego:

@rendermode interactiveServerWithoutPrerendering

...

@code {
    private static IComponentRenderMode interactiveServerWithoutPrerendering = 
        new InteractiveServerRenderMode(prerender: false);
}

W tej chwili podejście trybu renderowania skróconego jest prawdopodobnie przydatne tylko w przypadku zmniejszenia szczegółowości określania flagi prerender . Podejście skrócone może być bardziej przydatne w przyszłości, jeśli dodatkowe flagi staną się dostępne do renderowania interakcyjnego i chcesz utworzyć tryby renderowania skróconego z różnymi kombinacjami flag.

Wstrzykiwanie usługi za pośrednictwem pliku importu najwyższego poziomu (_Imports.razor)

Ta sekcja dotyczy Blazor Web Apptylko s.

Plik importujący najwyższego poziomu w folderze Components (Components/_Imports.razor) wprowadza odwołania do wszystkich składników w hierarchii folderów, w tym App składnik (App.razor). Składnik App jest zawsze renderowany statycznie, nawet jeśli prerendering składnika strony jest wyłączony. W związku z tym wstrzyknięcie usług za pośrednictwem pliku importowego najwyższego poziomu powoduje rozpoznawanie dwóch wystąpień usługi w składnikach strony.

Aby rozwiązać ten scenariusz, należy wstrzyknąć usługę w nowym pliku importu umieszczonym w folderze Pages (Components/Pages/_Imports.razor). Z tej lokalizacji usługa jest rozpoznawana tylko raz w składnikach strony.

Dodatkowe zasoby

• Kompresja protokołu WebSocket
  • wskazówki dotyczące platformy ASP.NET Core BlazorSignalR
  • Wskazówki dotyczące ograniczania zagrożeń na potrzeby interaktywnego renderowania po stronie serwera ASP.NET Core Blazor
• ASP.NET Core Blazor JavaScript ze statycznym renderowaniem po stronie serwera (statycznym usługą SSR)
• Kaskadowe wartości/parametry i granice trybu renderowania: zobacz również sekcję Parametry kaskadowe na poziomie głównym we wcześniejszej części artykułu.
• ASP.NET Biblioteki klas core Razor (RCLS) ze statycznym renderowaniem po stronie serwera (statycznym SSR)