tryby renderowania ASP.NET Core Blazor

  • Artykuł

W tym artykule wyjaśniono kontrolę nad renderowaniem składników Razor w Blazor usłudze 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 Blazor aplikacji internetowej przyjmuje tryb renderowania w celu określenia używanego przez niego modelu hostingu, miejsca renderowania i tego, czy jest interakcyjny.

W poniższej tabeli przedstawiono dostępne tryby renderowania składników renderowania RazorBlazor w aplikacji internetowej. 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
Serwer interaktywny Interaktywne renderowanie po stronie serwera (interakcyjne SSR) przy użyciu polecenia Blazor Server. Serwer
Interakcyjny zestaw WebAssembly Renderowanie po stronie klienta (CSR) przy użyciu Blazor WebAssembly†. Klient
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

† 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 Blazor na podstawie szablonu projektu aplikacji internetowej. 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 Blazor aplikacji internetowej, zobacz Tooling for ASP.NET Core (Narzędzia dla platformy ASP.NET Core Blazor).

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

Blazor Aby obsługiwać tryby renderowania interakcyjnego, należy skonfigurować aplikację internetową. Następujące rozszerzenia są automatycznie stosowane do aplikacji utworzonych na podstawie Blazor szablonu projektu aplikacji internetowej 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:

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:

Uwaga

Aby uzyskać orientację dotyczącą umieszczania interfejsu API w poniższych przykładach, sprawdź Program plik aplikacji wygenerowanej na Blazor podstawie szablonu projektu aplikacji internetowej. Aby uzyskać wskazówki dotyczące tworzenia Blazor aplikacji internetowej, 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 aplikacji internetowej 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 routingu domyślnie używają tego samego trybu renderowania co Router składnik renderujący stronę.

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 projektu aplikacji internetowej 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 aplikacji internetowej wygenerowanej 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 Blazor aplikacji internetowej:

  • 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 przez wystąpienie składnika, jest szczególnie przydatne, gdy specyfikacja aplikacji wywołuje jeden z następujących scenariuszy:

  • Masz obszar (folder) aplikacji ze składnikami, które muszą wdrażać statyczne renderowanie po stronie serwera (statyczne SSR) i uruchamiać je tylko na serwerze. Aplikacja kontroluje tryb renderowania globalnie, ustawiając tryb renderowania na składniku Routes w App składniku na podstawie ścieżki do folderu.
  • Składniki aplikacji są dostępne w różnych lokalizacjach (nie w jednym folderze), które muszą przyjmować statyczne reguły SSR i uruchamiać je tylko na serwerze. Aplikacja kontroluje tryb renderowania dla poszczególnych składników, ustawiając tryb renderowania z dyrektywą @rendermode w wystąpieniach składników. Emocje ion jest używany w składniku App do ustawiania trybu renderowania w składnikuRoutes.

W obu przypadkach składnik, który musi przyjąć statyczny przewodnik SSR, musi również wymusić ponowne ładowanie pełnej strony.

Poprzednie dwa scenariusze zostały omówione w przykładach w sekcji Fine control of render modes (Precyzyjna kontrola trybów renderowania) w dalszej części tego artykułu. Poniższe dwie podsekcje koncentrują się na podstawowych podejściach do ustawiania trybu renderowania.

Ustawianie trybu renderowania według definicji składnika

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

@rendermode renderModeForPage

...

@code {
    private static IComponentRenderMode renderModeForPage = 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="RenderModeForPage" />

...

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

Dodatkowe informacje na temat propagacji trybu renderowania znajdują się w sekcji Propagacja trybu renderowania w dalszej części tego artykułu. Sekcja Fine control of render mode (Precyzyjne sterowanie trybami renderowania) pokazuje, jak użyć powyższego podejścia do wdrożenia statycznego przewodnika SSR w określonych obszarach aplikacji (folderów) lub dla określonych składników rozmieszczonych wokół aplikacji z przypisaniami trybu renderowania poszczególnych składników.

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.

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 projektu Aplikacja internetowa 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)

Domyślnie 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 aplikacji internetowej, 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:

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 lokalnie w Blazor aplikacji internetowej, 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 aplikacji internetowej, 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 aplikacji internetowej, 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 interakcyjnego składnika podrzędnego ze statycznego elementu nadrzędnego muszą być JSw trybie serializowalnym. 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 aplikacji internetowej, 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 obsługiwane (domyślnie) i są wyświetlane po wyświetleniu strony w przeglądarce.

  • Pierwszy SharedMessage składnik z interaktywnym renderowaniem po stronie serwera (interactive SSR) jest interaktywny po ustanowieniu obwodu SignalR .
  • Drugi SharedMessage składnik z renderowaniem po stronie klienta (CSR) jest interaktywny poBlazor 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 projektu aplikacji internetowej z 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.

Precyzyjna kontrola trybów renderowania

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 reszta aplikacji korzysta z interaktywnego trybu renderowania.

Istnieją dwa podejścia, które można podjąć w celu precyzyjnej kontroli trybów renderowania, z których każda jest opisana w następujących podsekcjach:

  • Obszar (folder) statycznych składników SSR: masz obszar (folder) aplikacji ze składnikami, które muszą przyjąć statyczny przewodnik SSR i współużytkować ten sam prefiks ścieżki trasy. Aplikacja kontroluje tryb renderowania globalnie, ustawiając tryb renderowania na składniku Routes w App składniku na podstawie ścieżki do folderu.

  • Statyczne składniki SSR rozłożone w całej aplikacji: składniki są rozmieszczone wokół aplikacji w różnych lokalizacjach, które muszą przyjąć statyczny przewodnik SSR i uruchamiane tylko na serwerze. Statyczne składniki tylko do obsługi ZSR nie są w jednym folderze i nie mają wspólnego prefiksu ścieżki trasy. Aplikacja kontroluje tryb renderowania dla poszczególnych składników, ustawiając tryb renderowania z dyrektywą @rendermode w wystąpieniach składników. Emocje ion jest używany w składniku App do ustawiania trybu renderowania w składnikuRoutes.

W obu przypadkach składnik, który musi przyjąć statyczny przewodnik SSR, musi również wymusić ponowne ładowanie pełnej strony.

W poniższych przykładach użyto parametru HttpContext kaskadowego, aby określić, czy strona jest renderowana statycznie. Element nullHttpContext wskazuje, że składnik renderuje interaktywnie, co jest przydatne jako sygnał w kodzie aplikacji w celu wyzwolenia ponownego ładowania pełnostronicowego.

Obszar (folder) statycznych składników SSR

Podejście opisane w tej podsekcji jest używane przez Blazor szablon projektu Aplikacji internetowej z indywidualnym uwierzytelnianiem i globalną interakcyjnością.

Obszar (folder) aplikacji zawiera składniki, które muszą przyjąć statyczny protokół SSR i uruchamiać je tylko na serwerze. Składniki w folderze mają ten sam prefiks ścieżki trasy. Na przykład IdentityRazor składniki Blazor szablonu projektu aplikacji internetowej znajdują się w Components/Account/Pages folderze i udostępniają prefiks ścieżki /Accountgłównej .

Folder zawiera _Imports.razor również plik, który stosuje niestandardowy układ konta do składników w folderze:

@using BlazorSample.Components.Account.Shared
@layout AccountLayout

Folder Shared obsługuje AccountLayout składnik układu. Składnik używa elementu HttpContext w celu określenia, czy składnik renderuje na serwerze. Identity składniki muszą być renderowane na serwerze ze statycznym zestawem SSR, ponieważ są ustawione Identitycookie. Jeśli wartość parametru HttpContext to null, składnik jest renderowany interaktywnie, a ponowne ładowanie pełnej strony odbywa się przez wywołanie NavigationManager.Refresh polecenia z ustawioną wartością forceLoadtrue. Wymusza to pełny rerender strony przy użyciu statycznego SSR.

Components/Account/Shared/AccountLayout.razor:

@inherits LayoutComponentBase
@layout BlazorSample.Components.Layout.MainLayout
@inject NavigationManager NavigationManager

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            NavigationManager.Refresh(forceReload: true);
        }
    }
}

Uwaga

W szablonie Blazor projektu aplikacji internetowej znajduje się drugi plik układu (ManageLayout.razor w Components/Account/Shared folderze) dla Identity składników w folderze Components/Account/Pages/Manage . Folder Manage ma własny _Imports.razor plik do zastosowania do ManageLayout składników w folderze . We własnych aplikacjach użycie plików zagnieżdżonych _Imports.razor jest przydatną metodą stosowania układów niestandardowych do grup stron.

W składniku App każde żądanie składnika w Account folderze stosuje tryb renderowania, który wymusza statyczną usługę null SSR. Inne żądania składników odbierają globalną aplikację interakcyjnego trybu renderowania SSR (InteractiveServer).

Ważne

Zastosowanie trybu renderowania null nie zawsze wymusza statyczne SSR. Dzieje się tak po prostu przy użyciu podejścia pokazanego w tej sekcji.

null Tryb renderowania jest w rzeczywistości taki sam, jak nieokreślizowanie trybu renderowania, co powoduje, że składnik dziedziczy tryb renderowania elementu nadrzędnego. W takim przypadku App składnik jest renderowany przy użyciu statycznego przewodnika SSR, więc null tryb renderowania powoduje Routes , że składnik dziedziczy statyczny SSR ze App składnika. Jeśli dla składnika podrzędnego określono tryb renderowania o wartości null, którego element nadrzędny używa trybu renderowania interakcyjnego, element podrzędny dziedziczy ten sam interaktywny tryb renderowania.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

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

    private IComponentRenderMode? RenderModeForPage => 
        HttpContext.Request.Path.StartsWithSegments("/Account")
            ? null
            : {INTERACTIVE RENDER MODE};
}

W poprzednim kodzie zmień {INTERACTIVE RENDER MODE} symbol zastępczy na odpowiednią wartość, w zależności od tego, czy reszta aplikacji powinna przyjąć globalne InteractiveServerInteractiveWebAssembly, lub InteractiveAuto renderowanie.

Składniki, które muszą przyjąć statyczny przewodnik SSR w Account folderze, nie są wymagane do ustawienia układu, ponieważ są one stosowane za pośrednictwem _Imports.razor pliku, a składniki nie ustawiają trybu renderowania, ponieważ powinny być renderowane przy użyciu statycznego przewodnika SSR. Aby wymusić statyczny przewodnik SSR, nie należy wykonywać żadnych dalszych czynności dla składników w Account folderze.

Statyczne składniki SSR rozmieszczone w aplikacji

W poprzedniej podsekcji aplikacja kontroluje tryb renderowania składników, ustawiając tryb renderowania globalnie w składniku App . Alternatywnie App składnik może również przyjąć tryby renderowania poszczególnych składników do ustawiania trybu renderowania, co pozwala składnikom rozmieszczonym wokół aplikacji wymusić wdrożenie statycznego przewodnika SSR. W tej podsekcji opisano podejście.

Aplikacja ma niestandardowy układ, który można zastosować do składników wokół aplikacji. Zazwyczaj składnik udostępniony aplikacji jest umieszczany w folderze Components/Layout . Składnik używa elementu HttpContext w celu określenia, czy składnik renderuje na serwerze. Jeśli wartość parametru HttpContext to null, składnik jest renderowany interaktywnie, a ponowne ładowanie pełnej strony odbywa się przez wywołanie NavigationManager.Refresh polecenia z ustawioną wartością forceLoadtrue. Spowoduje to wyzwolenie żądania do serwera dla składnika.

Components/Layout/StaticSsrLayout.razor:

@inherits LayoutComponentBase
@layout MainLayout
@inject NavigationManager NavigationManager

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            NavigationManager.Refresh(forceReload: true);
        }
    }
}

W składniku App odbicie służy do ustawiania trybu renderowania. Dowolny tryb renderowania jest przypisywany do pojedynczego Routes pliku definicji składnika do składnika.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

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

    private IComponentRenderMode? RenderModeForPage =>
        HttpContext.GetEndpoint()?.Metadata.GetMetadata<RenderModeAttribute>()?
            .Mode;
}

Każdy składnik, który musi przyjąć statyczny SSR ustawia układ niestandardowy i nie określa trybu renderowania. Nieokreślizowanie trybu renderowania powoduje null wyświetlenie wartości RenderModeAttribute.Mode w składniku App , co powoduje, że nie przypisano trybu renderowania do Routes wystąpienia składnika i wymuszania statycznego SSR.

Ważne

Zastosowanie trybu renderowania null nie zawsze wymusza statyczne SSR. Dzieje się tak po prostu przy użyciu podejścia pokazanego w tej sekcji.

null Tryb renderowania jest w rzeczywistości taki sam, jak nieokreślizowanie trybu renderowania, co powoduje, że składnik dziedziczy tryb renderowania elementu nadrzędnego. W takim przypadku App składnik jest renderowany przy użyciu statycznego przewodnika SSR, więc null tryb renderowania powoduje Routes , że składnik dziedziczy statyczny SSR ze App składnika. Jeśli dla składnika podrzędnego określono tryb renderowania o wartości null, którego element nadrzędny używa trybu renderowania interakcyjnego, element podrzędny dziedziczy ten sam interaktywny tryb renderowania.

Nie należy wykonywać żadnych dalszych czynności, aby składniki wymuszały statyczny protokół SSR niż stosowanie układu niestandardowego bez ustawiania interaktywnego trybu renderowania:

@layout BlazorSample.Components.Layout.StaticSsrLayout

Składniki interakcyjne wokół aplikacji unikają stosowania niestandardowego układu statycznego SSR i ustawiają tylko odpowiedni interaktywny tryb renderowania, który po odbiciu w App składniku Routes jest stosowany do składnika:

@rendermode {INTERACTIVE RENDER MODE}

W poprzednim kodzie zmień {INTERACTIVE RENDER MODE} symbol zastępczy na odpowiednią wartość, w zależności od tego, czy składnik powinien przyjąć InteractiveServerInteractiveWebAssembly, lub InteractiveAuto renderowanie.

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 aplikacji internetowej z globalnym interaktywnym zestawem Blazor 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" w typie "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 tylko usługi Web Apps.

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