Udostępnij za pomocą

Integrowanie składników ASP.NET Core Razor z MVC lub Strony Razor

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z aktualną wersją, zobacz artykuł w wersji .NET 10.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu .NET 9.

Razor składniki można zintegrować ze stronami lub aplikacjami Razor MVC. Gdy strona lub widok jest renderowany, składniki mogą być w tym samym czasie prerenderowane.

Ważne

Zmiany struktury w wersjach ASP.NET Core doprowadziły do różnych zestawów instrukcji w tym artykule. Przed użyciem wskazówek w tym artykule upewnij się, że selektor wersji dokumentu w górnej części tego artykułu jest zgodny z wersją ASP.NET Core, która ma być używana dla aplikacji.

Prerendering może poprawić optymalizację dla wyszukiwarek (SEO) przez renderowanie zawartości dla początkowej odpowiedzi HTTP, które wyszukiwarki mogą wykorzystać do obliczenia rankingu strony.

Po skonfigurowaniu projektu skorzystaj ze wskazówek w poniższych sekcjach w zależności od wymagań projektu:

  • W przypadku składników, które można bezpośrednio skierować z żądań użytkowników. Postępuj zgodnie z poniższymi wskazówkami, gdy odwiedzający powinni mieć możliwość wysłania żądania HTTP w przeglądarce dla składnika z dyrektywą @page .
  • W przypadku składników, które nie są bezpośrednio dostępne z żądań użytkowników, zobacz sekcję dotyczącą renderowania składników ze strony lub widoku. Postępuj zgodnie z tymi wskazówkami, gdy aplikacja osadza składniki na istniejących stronach lub widokach za pomocą pomocnika tagów składników.

Konfigurowanie

Skorzystaj z poniższych wskazówek, aby zintegrować Razor składniki ze stronami lub widokami istniejącej Razor aplikacji Pages lub MVC.

  1. Dodaj plik importowania do folderu głównego projektu z następującą zawartością. Zmień znacznik {APP NAMESPACE} na przestrzeń nazw projektu.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  2. W pliku układu projektu (Pages/Shared/_Layout.cshtml w Razor aplikacjach Pages lub Views/Shared/_Layout.cshtml w aplikacjach MVC):

    • Dodaj następujący tag <base> i pomocnik Tagu komponentu HeadOutlet do elementu <head>:

      <base href="~/" />
<component type="typeof(Microsoft.AspNetCore.Components.Web.HeadOutlet)" 
    render-mode="ServerPrerendered" />

      Wartość href ( ścieżka podstawowa aplikacji) w poprzednim przykładzie zakłada, że aplikacja znajduje się w głównej ścieżce adresu URL (/). Jeśli aplikacja jest aplikacją podrzędną, zobacz ścieżkę podstawową aplikacji ASP.NET CoreBlazor.

      Komponent HeadOutlet jest używany do renderowania zawartości nagłówka dla tytułów stron (komponent <head>PageTitle) oraz innych elementów nagłówka (komponent HeadContent) ustawianych przez komponenty Razor. Aby uzyskać więcej informacji, zapoznaj się z zawartością nagłówka kontrolnego w aplikacjach ASP.NET CoreBlazor.

    • <script> Dodaj tag skryptu blazor.server.js bezpośrednio przed sekcją renderowania Scripts (@await RenderSectionAsync(...)):

      <script src="_framework/blazor.server.js"></script>

      Struktura dodaje blazor.server.js skrypt do aplikacji. Nie ma potrzeby ręcznego dodawania pliku skryptu blazor.server.js do aplikacji.

    Uwaga

    Zazwyczaj układ jest ładowany za pośrednictwem _ViewStart.cshtml pliku.

  3. Zarejestruj usługi Blazor Server w Program.cs, gdzie usługi są rejestrowane.

    builder.Services.AddServerSideBlazor();

  4. Dodaj punkt końcowy Blazor Hub do punktów końcowych Program.cs, gdzie mapowane są trasy. Umieść następujący wiersz po wywołaniu metody MapRazorPages (Razor Pages) lub MapControllerRoute (MVC):

    app.MapBlazorHub();

  5. Integracja komponentów z dowolną stroną lub widokiem. Na przykład dodaj Counter składnik do folderu projektu Shared .

    Pages/Shared/Counter.razor (Razor Strony) lub Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Strony:

    Na stronie Index w projekcie aplikacji Pages Razor dodaj przestrzeń nazw składnika Counter i osadź składnik na stronie. Po załadowaniu strony Index, składnik Counter jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

    MVC:

    W widoku projektu Index aplikacji MVC dodaj przestrzeń nazw dla składnika Counter i zintegrować składnik z widokiem. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

Aby uzyskać więcej informacji, zobacz sekcję Render components from a page or view (Składniki renderowania na stronie lub w widoku ).

Użyj komponentów routowalnych w aplikacji Pages Razor

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać składniki routingu Razor w Razor aplikacjach Pages:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. _Host Dodaj stronę do projektu z następującą zawartością. Zastąp {APP NAMESPACE} miejsce przestrzenią nazw aplikacji.

    Pages/_Host.cshtml:

    @page
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<component type="typeof(App)" render-mode="ServerPrerendered" />

    Uwaga

    W poprzednim przykładzie przyjęto założenie, że składnik HeadOutlet i skrypt Blazor (_framework/blazor.server.js) są renderowane przez układ aplikacji. Aby uzyskać więcej informacji, zobacz sekcję Konfiguracja .

    W wersji .NET 10 lub nowszej skrypt Blazor jest dołączany przez ramy, jeśli projekt zawiera co najmniej jeden plik składnika Razor (.razor). Jeśli aplikacja wymaga skryptu Blazor , ale nie zawiera co najmniej jednego składnika, dodaj następującą właściwość MSBuild do pliku projektu aplikacji, aby wymusić dołączenie skryptu bezwarunkowego:

    <RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. Program.cs W punktach końcowych dodaj trasę o niskim priorytecie dla _Host strony jako ostatni punkt końcowy:

    app.MapFallbackToPage("/_Host");

  5. Dodaj routowalne składniki do projektu. Poniższy przykład jest komponentem RoutableCounter, opartym na komponencie Counter w szablonach projektowych Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Używanie składników routingu w aplikacji MVC

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać routowalne składniki Razor w aplikacjach MVC:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. _Host Dodaj widok do projektu z następującą zawartością. Zastąp {APP NAMESPACE} miejsce przestrzenią nazw aplikacji.

    Views/Home/_Host.cshtml:

    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<component type="typeof(App)" render-mode="ServerPrerendered" />

    Uwaga

    W poprzednim przykładzie przyjęto założenie, że składnik HeadOutlet i skrypt Blazor (_framework/blazor.server.js) są renderowane przez układ aplikacji. Aby uzyskać więcej informacji, zobacz sekcję Konfiguracja .

    W programie .NET 10 lub nowszym Blazor skrypt jest dołączany przez platformę, jeśli projekt zawiera co najmniej jeden Razor plik składnika (.razor). Jeśli aplikacja wymaga skryptu Blazor , ale nie zawiera co najmniej jednego składnika, dodaj następującą właściwość MSBuild do pliku projektu aplikacji, aby wymusić dołączenie skryptu bezwarunkowego:

    <RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. Dodaj akcję do Home kontrolera.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. W punktach końcowych Program.cs dodaj trasę o niskim priorytecie dla akcji kontrolera zwracającej widok _Host.

    app.MapFallbackToController("Blazor", "Home");

  6. Pages Utwórz folder w aplikacji MVC i dodaj składniki routingu. Poniższy przykład jest komponentem RoutableCounter, opartym na komponencie Counter w szablonach projektowych Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Renderowanie składników ze strony lub widoku

Ta sekcja dotyczy implementacji komponentów do stron internetowych lub widoków aplikacji, gdzie komponenty nie są bezpośrednio trasowane przez żądania użytkowników.

Aby renderować składnik ze strony lub widoku, użyj pomocnika tagów składników.

Renderowanie stanowych komponentów interakcyjnych

Komponenty interaktywne stanowe można dodać do strony lub widoku Razor.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie renderowany z stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązania SignalR połączenia.

Razor Poniższa strona renderuje Counter składnik:

<h1>Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Renderowanie składników nieinteraktywnych

Na poniższej Razor stronie komponent Counter jest statycznie renderowany z początkową wartością określoną za pomocą formularza. Ponieważ składnik jest renderowany statycznie, składnik nie jest interaktywny:

<h1>Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Przestrzenie nazw składników

Podczas używania niestandardowego folderu do przechowywania składników projektu Razor, dodaj przestrzeń nazw, która reprezentuje ten folder, do strony lub widoku lub do pliku _ViewImports.cshtml. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol zastępczy {APP NAMESPACE} to ta przestrzeń nazw projektu. Components reprezentuje nazwę folderu.
@using {APP NAMESPACE}.Components

Plik _ViewImports.cshtml znajduje się w Pages folderze Razor aplikacji Pages lub Views folderze aplikacji MVC.

Aby uzyskać więcej informacji, zobacz ASP.NET Core Razor składniki.

Utrzymanie stanu wstępnie renderowanego

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 skonfigurowany asynchronicznie, interfejs użytkownika może migać, ponieważ wstępnie wyrenderowany interfejs użytkownika jest zastępowany tymczasowymi symbolami zastępczymi, a następnie ponownie w pełni renderowany.

Aby zachować stan dla prerenderowanych składników, należy użyć Tag Helpera do utrwalania stanu składnika (dokumentacji referencyjnej). Dodaj tag Pomocnika Tagów <persist-component-state />, wewnątrz zamykającego tagu </body> strony _Host w aplikacji, która prerenderuje składniki.

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

W aplikacjach Pages/_Host.cshtmlBlazor znajdujących się ServerPrerendered w aplikacji Blazor Server:

<body>
    ...

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

Zdecyduj, jaki stan ma być trwały przy użyciu PersistentComponentState usługi. Atrybut[PersistentState] zastosowany do właściwości rejestruje wywołanie zwrotne w celu utrwalania stanu podczas prerenderingu i ładuje go, gdy składnik jest renderowany interaktywnie lub usługa jest utworzona.

W poniższym przykładzie {TYPE} symbol zastępczy reprezentuje typ danych do utrwalania (na przykład WeatherForecast[]).

@code {
    [PersistentState]
    public {TYPE} Data { get; set; }

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

W poniższym przykładzie WeatherForecastPreserveState składnik utrzymuje stan prognozy pogody podczas prerenderingu, a następnie pobiera stan w celu zainicjowania składnika. Pomocnik Tagów do utrwalania stanu komponentu zachowuje stan komponentu po wszystkich jego wywołaniach.

WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@using BlazorSample.Shared
@inject IWeatherForecastService WeatherForecastService

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (Forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in Forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    [PersistentState]
    public WeatherForecast[]? Forecasts { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Forecasts ??= await WeatherForecastService.GetForecastAsync(
            DateOnly.FromDateTime(DateTime.Now));
    }
}

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. Wykonaj wywołanie na końcu kodu inicjowania, aby uniknąć potencjalnego stanu wyścigu podczas zamykania aplikacji.

W poniższym przykładzie:

  • Symbol {TYPE} zastępczy reprezentuje typ danych do utrwalania (na przykład WeatherForecast[]).
  • Symbol zastępczy {TOKEN} jest ciągiem identyfikatora stanu (na przykład fetchdata).
@implements IDisposable
@inject PersistentComponentState ApplicationState

...

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

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

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

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

        return Task.CompletedTask;
    }

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

W poniższym przykładzie WeatherForecastPreserveState składnik utrzymuje stan prognozy pogody podczas prerenderingu, a następnie pobiera stan w celu zainicjowania składnika. Pomocnik Tagów do utrwalania stanu komponentu zachowuje stan komponentu po wszystkich jego wywołaniach.

Pages/WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@using BlazorSample.Shared
@implements IDisposable
@inject IWeatherForecastService WeatherForecastService
@inject PersistentComponentState ApplicationState

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[] forecasts = Array.Empty<WeatherForecast>();
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(
                    DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), forecasts);

        return Task.CompletedTask;
    }

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

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 trwały i wyrenderowany jest przesyłany do klienta, gdzie jest używany do przywracania stanu komponentu. ASP.NET Core Data Protection gwarantuje, że dane są bezpiecznie przesyłane w Blazor Server aplikacjach.

Rozmiar uprzednio renderowanego stanu i SignalR limit rozmiaru komunikatu

Rozmiar dużego stanu prerenderowanego może przekroczyć limit rozmiaru komunikatu obwodu, co prowadzi do następujących konsekwencji:

  • Nie można zainicjować SignalR układu przez błąd na kliencie: Circuit host not initialized.
  • Interfejs użytkownika ponownego nawiązywania połączenia na kliencie jest wyświetlany, gdy obwód ulegnie awarii. Odzyskiwanie nie jest możliwe.

Aby rozwiązać ten problem, użyj jednej z następujących metod:

  • Zmniejsz ilość danych umieszczanych w stanie wstępnie utworzonym.
  • Zwiększ limitSignalR OSTRZEŻENIE: Zwiększenie limitu może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS).

Dodatkowe Blazor Server zasoby

Prerendering może poprawić optymalizację dla wyszukiwarek (SEO) przez renderowanie zawartości dla początkowej odpowiedzi HTTP, które wyszukiwarki mogą wykorzystać do obliczenia rankingu strony.

Po skonfigurowaniu projektu skorzystaj ze wskazówek w poniższych sekcjach w zależności od wymagań projektu:

Konfigurowanie

Skorzystaj z poniższych wskazówek, aby zintegrować Razor składniki ze stronami lub widokami istniejącej Razor aplikacji Pages lub MVC.

Ważne

Użycie strony układu (_Layout.cshtml) z Pomocnikiem tagu składnika () dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitle składnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zapoznaj się z zawartością nagłówka kontrolnego w aplikacjach ASP.NET CoreBlazor.

  1. W pliku układu projektu:

    • Dodaj następujący <base> tag i HeadOutlet komponent Tag Helper do elementu <head> w Pages/Shared/_Layout.cshtml (Razor Pages) lub Views/Shared/_Layout.cshtml (MVC):

      <base href="~/" />
<component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

      Wartość href ( ścieżka podstawowa aplikacji) w poprzednim przykładzie zakłada, że aplikacja znajduje się w głównej ścieżce adresu URL (/). Jeśli aplikacja jest aplikacją podrzędną, zobacz ścieżkę podstawową aplikacji ASP.NET CoreBlazor.

      Komponent HeadOutlet jest używany do renderowania zawartości nagłówka dla tytułów stron (komponent <head>PageTitle) oraz innych elementów nagłówka (komponent HeadContent) ustawianych przez komponenty Razor. Aby uzyskać więcej informacji, zapoznaj się z zawartością nagłówka kontrolnego w aplikacjach ASP.NET CoreBlazor.

    • Dodaj tag <script> dla skryptu blazor.server.js bezpośrednio przed sekcją renderowania Scripts (@await RenderSectionAsync(...)) w układzie aplikacji.

      Pages/Shared/_Layout.cshtml (Razor Strony) lub Views/Shared/_Layout.cshtml (MVC):

      <script src="_framework/blazor.server.js"></script>

      Struktura dodaje blazor.server.js skrypt do aplikacji. Nie ma potrzeby ręcznego dodawania pliku skryptu blazor.server.js do aplikacji.

  2. Dodaj plik importowania do folderu głównego projektu z następującą zawartością. Zmień znacznik {APP NAMESPACE} na przestrzeń nazw projektu.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  3. Zarejestruj usługi Blazor Server w Program.cs, gdzie usługi są rejestrowane.

    builder.Services.AddServerSideBlazor();

  4. Dodaj punkt końcowy Blazor Hub do punktów końcowych Program.cs, gdzie mapowane są trasy.

    Umieść następujący wiersz po wywołaniu metody MapRazorPages (Razor Pages) lub MapControllerRoute (MVC):

    app.MapBlazorHub();

  5. Integracja komponentów z dowolną stroną lub widokiem. Na przykład dodaj Counter składnik do folderu projektu Shared .

    Pages/Shared/Counter.razor (Razor Strony) lub Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Strony:

    Na stronie Index w projekcie aplikacji Pages Razor dodaj przestrzeń nazw składnika Counter i osadź składnik na stronie. Po załadowaniu strony Index, składnik Counter jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

    MVC:

    W widoku projektu Index aplikacji MVC dodaj przestrzeń nazw dla składnika Counter i zintegrować składnik z widokiem. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

Aby uzyskać więcej informacji, zobacz sekcję Render components from a page or view (Składniki renderowania na stronie lub w widoku ).

Użyj komponentów routowalnych w aplikacji Pages Razor

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać składniki routingu Razor w Razor aplikacjach Pages:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. _Host Dodaj stronę do projektu z następującą zawartością.

    Pages/_Host.cshtml:

    @page "/blazor"
@namespace {APP NAMESPACE}.Pages.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

<component type="typeof(App)" render-mode="ServerPrerendered" />

    W tym scenariuszu składniki używają udostępnionego pliku _Layout.cshtml do układu.

    Ważne

    Użycie strony układu (_Layout.cshtml) z Pomocnikiem tagu składnika () dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitle składnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zapoznaj się z zawartością nagłówka kontrolnego w aplikacjach ASP.NET CoreBlazor.

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. Program.cs W punktach końcowych dodaj trasę o niskim priorytecie dla _Host strony jako ostatni punkt końcowy:

    app.MapFallbackToPage("/_Host");

  5. Dodaj routowalne składniki do projektu. Poniższy przykład jest komponentem RoutableCounter, opartym na komponencie Counter w szablonach projektowych Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Używanie składników routingu w aplikacji MVC

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać routowalne składniki Razor w aplikacjach MVC:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. _Host Dodaj widok do projektu z następującą zawartością.

    Views/Home/_Host.cshtml:

    @namespace {APP NAMESPACE}.Views.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

<component type="typeof(App)" render-mode="ServerPrerendered" />

    Składniki używają udostępnionego pliku _Layout.cshtml dla swojego rozmieszczenia.

    Ważne

    Użycie strony układu (_Layout.cshtml) z Pomocnikiem tagu składnika () dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitle składnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zapoznaj się z zawartością nagłówka kontrolnego w aplikacjach ASP.NET CoreBlazor.

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. Dodaj akcję do Home kontrolera.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. W punktach końcowych Program.cs dodaj trasę o niskim priorytecie dla akcji kontrolera zwracającej widok _Host.

    app.MapFallbackToController("Blazor", "Home");

  6. Pages Utwórz folder w aplikacji MVC i dodaj składniki routingu. Poniższy przykład jest komponentem RoutableCounter, opartym na komponencie Counter w szablonach projektowych Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Renderowanie składników ze strony lub widoku

Ta sekcja dotyczy implementacji komponentów do stron internetowych lub widoków aplikacji, gdzie komponenty nie są bezpośrednio trasowane przez żądania użytkowników.

Aby renderować składnik ze strony lub widoku, użyj pomocnika tagów składników.

Renderowanie stanowych komponentów interakcyjnych

Komponenty interaktywne stanowe można dodać do strony lub widoku Razor.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie renderowany z stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązania SignalR połączenia.

Razor Poniższa strona renderuje Counter składnik:

<h1>Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Ważne

Użycie strony układu (_Layout.cshtml) z Pomocnikiem tagu składnika () dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitle składnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zapoznaj się z zawartością nagłówka kontrolnego w aplikacjach ASP.NET CoreBlazor.

Renderowanie składników nieinteraktywnych

Na poniższej Razor stronie komponent Counter jest statycznie renderowany z początkową wartością określoną za pomocą formularza. Ponieważ składnik jest renderowany statycznie, składnik nie jest interaktywny:

<h1>Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Ważne

Użycie strony układu (_Layout.cshtml) z Pomocnikiem tagu składnika () dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitle składnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zapoznaj się z zawartością nagłówka kontrolnego w aplikacjach ASP.NET CoreBlazor.

Przestrzenie nazw składników

Podczas używania niestandardowego folderu do przechowywania składników projektu Razor, dodaj przestrzeń nazw, która reprezentuje ten folder, do strony lub widoku lub do pliku _ViewImports.cshtml. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol zastępczy {APP NAMESPACE} to ta przestrzeń nazw projektu. Components reprezentuje nazwę folderu.
@using {APP NAMESPACE}.Components

Plik _ViewImports.cshtml znajduje się w Pages folderze Razor aplikacji Pages lub Views folderze aplikacji MVC.

Aby uzyskać więcej informacji, zobacz ASP.NET Core Razor składniki.

Utrzymanie stanu wstępnie renderowanego

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 skonfigurowany asynchronicznie, interfejs użytkownika może migać, ponieważ wstępnie wyrenderowany interfejs użytkownika jest zastępowany tymczasowymi symbolami zastępczymi, a następnie ponownie w pełni renderowany.

Aby rozwiązać te problemy, Blazor wspiera utrwalanie stanu komponentu na stronie przetworzonej przy użyciu pomocnika tagu stanu komponentu. Dodaj tag Pomocnika tagu , <persist-component-state />wewnątrz tagu zamykającego </body> .

Pages/_Layout.cshtml:

<body>
    ...

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

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. Wykonaj wywołanie na końcu kodu inicjowania, aby uniknąć potencjalnego stanu wyścigu podczas zamykania aplikacji.

W poniższym przykładzie WeatherForecastPreserveState składnik utrzymuje stan prognozy pogody podczas prerenderingu, a następnie pobiera stan w celu zainicjowania składnika. Pomocnik Tagów do utrwalania stanu komponentu zachowuje stan komponentu po wszystkich jego wywołaniach.

Pages/WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@implements IDisposable
@using BlazorSample.Shared
@inject IWeatherForecastService WeatherForecastService
@inject PersistentComponentState ApplicationState

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[] forecasts = Array.Empty<WeatherForecast>();
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateTime.Now);
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), forecasts);

        return Task.CompletedTask;
    }

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

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 trwały i wyrenderowany jest przesyłany do klienta, gdzie jest używany do przywracania stanu komponentu. ASP.NET Core Data Protection gwarantuje, że dane są bezpiecznie przesyłane w Blazor Server aplikacjach.

Rozmiar uprzednio renderowanego stanu i SignalR limit rozmiaru komunikatu

Rozmiar dużego stanu prerenderowanego może przekroczyć limit rozmiaru komunikatu obwodu, co prowadzi do następujących konsekwencji:

  • Nie można zainicjować SignalR układu przez błąd na kliencie: Circuit host not initialized.
  • Interfejs użytkownika ponownego nawiązywania połączenia na kliencie jest wyświetlany, gdy obwód ulegnie awarii. Odzyskiwanie nie jest możliwe.

Aby rozwiązać ten problem, użyj jednej z następujących metod:

  • Zmniejsz ilość danych umieszczanych w stanie wstępnie utworzonym.
  • Zwiększ limitSignalR OSTRZEŻENIE: Zwiększenie limitu może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS).

Dodatkowe Blazor Server zasoby

Prerendering może poprawić optymalizację dla wyszukiwarek (SEO) przez renderowanie zawartości dla początkowej odpowiedzi HTTP, które wyszukiwarki mogą wykorzystać do obliczenia rankingu strony.

Po skonfigurowaniu projektu skorzystaj ze wskazówek w poniższych sekcjach w zależności od wymagań projektu:

Konfigurowanie

Istniejąca Razor aplikacja Pages lub MVC może integrować Razor składniki ze stronami lub widokami:

  1. W pliku układu projektu:

    • Dodaj następujący tag <base> do elementu <head> w Pages/Shared/_Layout.cshtml (Razor Pages) lub Views/Shared/_Layout.cshtml (MVC):

      <base href="~/" />

      Wartość href ( ścieżka podstawowa aplikacji) w poprzednim przykładzie zakłada, że aplikacja znajduje się w głównej ścieżce adresu URL (/). Jeśli aplikacja jest aplikacją podrzędną, zobacz ścieżkę podstawową aplikacji ASP.NET CoreBlazor.

    • Dodaj tag <script> dla skryptu blazor.server.js bezpośrednio przed sekcją Scripts renderowania.

      Pages/Shared/_Layout.cshtml (Razor Strony) lub Views/Shared/_Layout.cshtml (MVC):

          ...
    <script src="_framework/blazor.server.js"></script>

    @await RenderSectionAsync("Scripts", required: false)
</body>

      Struktura dodaje blazor.server.js skrypt do aplikacji. Nie ma potrzeby ręcznego dodawania pliku skryptu blazor.server.js do aplikacji.

  2. Dodaj plik importowania do folderu głównego projektu z następującą zawartością. Zmień znacznik {APP NAMESPACE} na przestrzeń nazw projektu.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  3. Zarejestruj usługę Blazor Server w programie Startup.ConfigureServices.

    W pliku Startup.cs:

    services.AddServerSideBlazor();

  4. Dodaj punkt końcowy koncentratora Blazor do punktów końcowych app.UseEndpointsStartup.Configure.

    Startup.cs:

    endpoints.MapBlazorHub();

  5. Integracja komponentów z dowolną stroną lub widokiem. Na przykład dodaj Counter składnik do folderu projektu Shared .

    Pages/Shared/Counter.razor (Razor Strony) lub Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Strony:

    Na stronie Index w projekcie aplikacji Pages Razor dodaj przestrzeń nazw składnika Counter i osadź składnik na stronie. Po załadowaniu strony Index, składnik Counter jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

    W poprzednim przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw aplikacji.

    MVC:

    W widoku projektu Index aplikacji MVC dodaj przestrzeń nazw dla składnika Counter i zintegrować składnik z widokiem. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

Aby uzyskać więcej informacji, zobacz sekcję Render components from a page or view (Składniki renderowania na stronie lub w widoku ).

Użyj komponentów routowalnych w aplikacji Pages Razor

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać składniki routingu Razor w Razor aplikacjach Pages:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Uwaga

    Wraz z wydaniem platformy .NET 5.0.1 i wszystkimi dodatkowymi wersjami 5.x składnik zawiera parametr Router ustawiony na wartość PreferExactMatches. Aby uzyskać więcej informacji, zobacz Migrowanie z platformy ASP.NET Core 3.1 do platformy .NET 5.

  3. _Host Dodaj stronę do projektu z następującą zawartością.

    Pages/_Host.cshtml:

    @page "/blazor"
@{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Składniki używają udostępnionego pliku _Layout.cshtml dla swojego rozmieszczenia.

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. W punktach końcowych Startup.Configure, dodaj trasę o niskim priorytecie dla strony Startup.cs jako ostatni punkt końcowy:

    endpoints.MapFallbackToPage("/_Host");

    W poniższym przykładzie pokazano dodaną linię w typowej konfiguracji punktu końcowego aplikacji.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Dodaj routowalne składniki do projektu.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Używanie składników routingu w aplikacji MVC

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać routowalne składniki Razor w aplikacjach MVC:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Uwaga

    Wraz z wydaniem platformy .NET 5.0.1 i wszystkimi dodatkowymi wersjami 5.x składnik zawiera parametr Router ustawiony na wartość PreferExactMatches. Aby uzyskać więcej informacji, zobacz Migrowanie z platformy ASP.NET Core 3.1 do platformy .NET 5.

  3. _Host Dodaj widok do projektu z następującą zawartością.

    Views/Home/_Host.cshtml:

    @{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Składniki używają udostępnionego pliku _Layout.cshtml dla swojego rozmieszczenia.

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. Dodaj akcję do Home kontrolera.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. Startup.Configure W punktach końcowych Startup.cs dodaj trasę o niskim priorytecie dla akcji kontrolera, która zwraca widok _Host.

    endpoints.MapFallbackToController("Blazor", "Home");

    W poniższym przykładzie pokazano dodaną linię w typowej konfiguracji punktu końcowego aplikacji.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Dodaj routowalne składniki do projektu.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Renderowanie składników ze strony lub widoku

Ta sekcja dotyczy implementacji komponentów do stron internetowych lub widoków aplikacji, gdzie komponenty nie są bezpośrednio trasowane przez żądania użytkowników.

Aby renderować składnik ze strony lub widoku, użyj pomocnika tagów składników.

Renderowanie stanowych komponentów interakcyjnych

Komponenty interaktywne stanowe można dodać do strony lub widoku Razor.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie renderowany z stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązania SignalR połączenia.

Razor Poniższa strona renderuje Counter składnik:

<h1>My Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Renderowanie składników nieinteraktywnych

Na poniższej Razor stronie komponent Counter jest statycznie renderowany z początkową wartością określoną za pomocą formularza. Ponieważ składnik jest renderowany statycznie, składnik nie jest interaktywny:

<h1>My Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Przestrzenie nazw składników

Podczas używania niestandardowego folderu do przechowywania składników projektu Razor, dodaj przestrzeń nazw, która reprezentuje ten folder, do strony lub widoku lub do pliku _ViewImports.cshtml. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol zastępczy {APP NAMESPACE} to ta przestrzeń nazw projektu. Components reprezentuje nazwę folderu.
@using {APP NAMESPACE}.Components

Plik _ViewImports.cshtml znajduje się w Pages folderze Razor aplikacji Pages lub Views folderze aplikacji MVC.

Aby uzyskać więcej informacji, zobacz ASP.NET Core Razor składniki.

Rozmiar uprzednio renderowanego stanu i SignalR limit rozmiaru komunikatu

Rozmiar dużego stanu prerenderowanego może przekroczyć limit rozmiaru komunikatu obwodu, co prowadzi do następujących konsekwencji:

  • Nie można zainicjować SignalR układu przez błąd na kliencie: Circuit host not initialized.
  • Interfejs użytkownika ponownego nawiązywania połączenia na kliencie jest wyświetlany, gdy obwód ulegnie awarii. Odzyskiwanie nie jest możliwe.

Aby rozwiązać ten problem, użyj jednej z następujących metod:

  • Zmniejsz ilość danych umieszczanych w stanie wstępnie utworzonym.
  • Zwiększ limitSignalR OSTRZEŻENIE: Zwiększenie limitu może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS).

Dodatkowe Blazor Server zasoby

Razor składniki można zintegrować ze stronami lub aplikacjami Razor MVC. Gdy strona lub widok jest renderowany, składniki mogą być w tym samym czasie prerenderowane.

Prerendering może poprawić optymalizację dla wyszukiwarek (SEO) przez renderowanie zawartości dla początkowej odpowiedzi HTTP, które wyszukiwarki mogą wykorzystać do obliczenia rankingu strony.

Po skonfigurowaniu projektu skorzystaj ze wskazówek w poniższych sekcjach w zależności od wymagań projektu:

Konfigurowanie

Istniejąca Razor aplikacja Pages lub MVC może integrować Razor składniki ze stronami lub widokami:

  1. W pliku układu projektu:

    • Dodaj następujący tag <base> do elementu <head> w Pages/Shared/_Layout.cshtml (Razor Pages) lub Views/Shared/_Layout.cshtml (MVC):

      + <base href="~/" />

      Wartość href ( ścieżka podstawowa aplikacji) w poprzednim przykładzie zakłada, że aplikacja znajduje się w głównej ścieżce adresu URL (/). Jeśli aplikacja jest aplikacją podrzędną, zobacz ścieżkę podstawową aplikacji ASP.NET CoreBlazor.

    • Dodaj tag <script> dla skryptu blazor.server.js bezpośrednio przed sekcją Scripts renderowania.

      Pages/Shared/_Layout.cshtml (Razor Strony) lub Views/Shared/_Layout.cshtml (MVC):

          ...
    <script src="_framework/blazor.server.js"></script>

    @await RenderSectionAsync("Scripts", required: false)
</body>

      Struktura dodaje blazor.server.js skrypt do aplikacji. Nie ma potrzeby ręcznego dodawania pliku skryptu blazor.server.js do aplikacji.

  2. Dodaj plik importowania do folderu głównego projektu z następującą zawartością. Zmień znacznik {APP NAMESPACE} na przestrzeń nazw projektu.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  3. Zarejestruj usługę Blazor Server w programie Startup.ConfigureServices.

    Startup.cs:

    services.AddServerSideBlazor();

  4. Dodaj punkt końcowy koncentratora Blazor do punktów końcowych app.UseEndpointsStartup.Configure.

    Startup.cs:

    endpoints.MapBlazorHub();

  5. Integracja komponentów z dowolną stroną lub widokiem. Na przykład dodaj Counter składnik do folderu projektu Shared .

    Pages/Shared/Counter.razor (Razor Strony) lub Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Strony:

    Na stronie Index w projekcie aplikacji Pages Razor dodaj przestrzeń nazw składnika Counter i osadź składnik na stronie. Po załadowaniu strony Index, składnik Counter jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

    W poprzednim przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw aplikacji.

    MVC:

    W widoku projektu Index aplikacji MVC dodaj przestrzeń nazw dla składnika Counter i zintegrować składnik z widokiem. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie renderowany na stronie. W poniższym przykładzie zastąp symbol zastępczy {APP NAMESPACE} przestrzenią nazw projektu.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

Aby uzyskać więcej informacji, zobacz sekcję Render components from a page or view (Składniki renderowania na stronie lub w widoku ).

Użyj komponentów routowalnych w aplikacji Pages Razor

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać składniki routingu Razor w Razor aplikacjach Pages:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. _Host Dodaj stronę do projektu z następującą zawartością.

    Pages/_Host.cshtml:

    @page "/blazor"
@{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Składniki używają udostępnionego pliku _Layout.cshtml dla swojego rozmieszczenia.

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. W punktach końcowych Startup.Configure, dodaj trasę o niskim priorytecie dla strony Startup.cs jako ostatni punkt końcowy:

    endpoints.MapFallbackToPage("/_Host");

    W poniższym przykładzie pokazano dodaną linię w typowej konfiguracji punktu końcowego aplikacji.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Dodaj routowalne składniki do projektu.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Używanie składników routingu w aplikacji MVC

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routowane z bezpośrednich żądań użytkowników.

Aby obsługiwać routowalne składniki Razor w aplikacjach MVC:

  1. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja .

  2. Dodaj składnik App do katalogu głównego projektu z następującą zawartością.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. _Host Dodaj widok do projektu z następującą zawartością.

    Views/Home/_Host.cshtml:

    @{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Składniki używają udostępnionego pliku _Layout.cshtml dla swojego rozmieszczenia.

    RenderMode konfiguruje, czy składnik App

    • Jest wstępnie renderowany na stronie.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do zainicjowania aplikacji Blazor przez agenta użytkownika.

    Aby uzyskać więcej informacji na temat pomocnika tagów składników, w tym przekazywania parametrów i RenderMode konfiguracji, zobacz Pomocnik tagów składników w ASP.NET Core.

  4. Dodaj akcję do Home kontrolera.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. Startup.Configure W punktach końcowych Startup.cs dodaj trasę o niskim priorytecie dla akcji kontrolera, która zwraca widok _Host.

    endpoints.MapFallbackToController("Blazor", "Home");

    W poniższym przykładzie pokazano dodaną linię w typowej konfiguracji punktu końcowego aplikacji.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Dodaj routowalne składniki do projektu.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Uruchom projekt i przejdź do składnika routable RoutableCounter pod adresem /routable-counter.

Aby uzyskać więcej informacji na temat przestrzeni nazw, zobacz sekcję Przestrzenie nazw składników .

Renderowanie składników ze strony lub widoku

Ta sekcja dotyczy implementacji komponentów do stron internetowych lub widoków aplikacji, gdzie komponenty nie są bezpośrednio trasowane przez żądania użytkowników.

Aby renderować składnik ze strony lub widoku, użyj pomocnika tagów składników.

Renderowanie stanowych komponentów interakcyjnych

Komponenty interaktywne stanowe można dodać do strony lub widoku Razor.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie renderowany z stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązania SignalR połączenia.

Razor Poniższa strona renderuje Counter składnik:

<h1>My Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Renderowanie składników nieinteraktywnych

Na poniższej Razor stronie komponent Counter jest statycznie renderowany z początkową wartością określoną za pomocą formularza. Ponieważ składnik jest renderowany statycznie, składnik nie jest interaktywny:

<h1>My Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Aby uzyskać więcej informacji, zobacz Pomocnik tagów składników w programie ASP.NET Core.

Przestrzenie nazw składników

Podczas używania niestandardowego folderu do przechowywania składników projektu Razor, dodaj przestrzeń nazw, która reprezentuje ten folder, do strony lub widoku lub do pliku _ViewImports.cshtml. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol zastępczy {APP NAMESPACE} to ta przestrzeń nazw projektu. Components reprezentuje nazwę folderu.
@using {APP NAMESPACE}.Components

Plik _ViewImports.cshtml znajduje się w Pages folderze Razor aplikacji Pages lub Views folderze aplikacji MVC.

Aby uzyskać więcej informacji, zobacz ASP.NET Core Razor składniki.

Rozmiar uprzednio renderowanego stanu i SignalR limit rozmiaru komunikatu

Rozmiar dużego stanu prerenderowanego może przekroczyć limit rozmiaru komunikatu obwodu, co prowadzi do następujących konsekwencji:

  • Nie można zainicjować SignalR układu przez błąd na kliencie: Circuit host not initialized.
  • Interfejs użytkownika ponownego nawiązywania połączenia na kliencie jest wyświetlany, gdy obwód ulegnie awarii. Odzyskiwanie nie jest możliwe.

Aby rozwiązać ten problem, użyj jednej z następujących metod:

  • Zmniejsz ilość danych umieszczanych w stanie wstępnie utworzonym.
  • Zwiększ limitSignalR OSTRZEŻENIE: Zwiększenie limitu może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS).

Dodatkowe Blazor Server zasoby

  • Last updated on