Udostępnij za pośrednictwem

Integrowanie składników ASP.NET Core Razor z mvC lub Razor pages

  • Artykuł

Uwaga

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

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 platformy .NET 9.

Ważne

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

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

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ę aparatu wyszukiwania (SEO) przez renderowanie zawartości początkowej odpowiedzi HTTP, za pomocą których wyszukiwarki mogą obliczyć rangę 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.

  1. Dodaj plik importowania do folderu głównego projektu z następującą zawartością. {APP NAMESPACE} Zmień symbol zastępczy 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 <base> tag i HeadOutlet pomocnik tagu składnika do <head> elementu:

      <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ą, postępuj zgodnie ze wskazówkami w sekcji Ścieżka podstawowa aplikacji w artykule Host i wdróż ASP.NET CoreBlazor.

      Składnik jest używany do renderowania HeadOutlet zawartości nagłówka () dla tytułów stron (<head>PageTitleskładnik) i innych elementów głównych (HeadContentskładnik) ustawionych przez Razor składniki. Aby uzyskać więcej informacji, zobacz Control head content in ASP.NET Core apps (Kontrolowanie zawartości głównej w aplikacjach platformy 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. Blazor Server Zarejestruj usługi, w Program.cs których są zarejestrowane usługi:

    builder.Services.AddServerSideBlazor();

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

    app.MapBlazorHub();

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

    Pages/Shared/Counter.razor (Razor Pages) 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 Razor projektu Index aplikacji Pages dodaj Counter przestrzeń nazw składnika i osadź składnik na stronie. Po załadowaniu Index Counter strony składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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 Counter przestrzeń nazw składnika i osadź składnik w widoku. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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żywanie składników routingu Razor w aplikacji Pages

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routingiem z żą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. App Dodaj składnik 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} symbol zastępczy 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 HeadOutlet składnik i Blazor skrypt (_framework/blazor.server.js) są renderowane przez układ aplikacji. Aby uzyskać więcej informacji, zobacz sekcję Konfiguracja .

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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 składniki routingu do projektu. Poniższy przykład jest składnikiem opartym RoutableCounter na składniku Counter Blazor w szablonach projektu.

    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 routingiem z żądań użytkowników.

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

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

  2. App Dodaj składnik 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} symbol zastępczy 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 HeadOutlet składnik i Blazor skrypt (_framework/blazor.server.js) są renderowane przez układ aplikacji. Aby uzyskać więcej informacji, zobacz sekcję Konfiguracja .

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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. Program.cs W punktach końcowych dodaj trasę o niskim priorytecie dla akcji kontrolera zwracającej _Host widok:

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

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

    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 dodawania składników do stron lub widoków, gdzie składniki nie są bezpośrednio routingowe z żądań użytkowników.

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

Renderowanie składników interakcyjnych stanowych

Składniki interaktywne stanowe można dodać do Razor strony lub widoku.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie wypełniony stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązywania 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 Counter składnik jest statycznie renderowany z wartością początkową określoną przy użyciu 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

W przypadku przechowywania składników projektu Razor przy użyciu folderu niestandardowego dodaj przestrzeń nazw reprezentującą folder do strony/widoku lub do _ViewImports.cshtml pliku. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol {APP NAMESPACE} zastępczy to 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 Podstawowe Razor składniki.

Utrwalanie stanu wstępnego

Bez utrwalania stanu wstępnego, stan używany podczas prerenderingu jest utracony i musi zostać utworzony ponownie, gdy aplikacja jest w pełni załadowana. Jeśli jakikolwiek stan jest skonfigurowany asynchronicznie, interfejs użytkownika może migać, ponieważ wstępnie wypełniony interfejs użytkownika jest zastępowany symbolami zastępczymi tymczasowymi, a następnie w pełni renderowany ponownie.

Aby utrwały stan dla wstępnie wstępnie użytych składników, należy użyć pomocnika tagu stanu składnika (źródło referencyjne). Dodaj tag <persist-component-state />Pomocnika tagu , wewnątrz tagu _Host zamykającego </body> strony w aplikacji, która prerenders składników.

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 Pages/_Host.cshtml aplikacjach Blazor , które znajdują się ServerPrerendered w Blazor Server aplikacji:

<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.

W poniższym przykładzie:

  • Symbol {TYPE} zastępczy reprezentuje typ danych do utrwalania (na przykład WeatherForecast[]).
  • Symbol {TOKEN} zastępczy 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()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistData);

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

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

        return Task.CompletedTask;
    }

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

Poniższy przykład to zaktualizowana wersja FetchData składnika na podstawie szablonu Blazor projektu. Składnik WeatherForecastPreserveState utrzymuje stan prognozy pogody podczas prerenderingu, a następnie pobiera stan w celu zainicjowania składnika. Pomocnik stanu stanu składnika utrwala stan składnika po wywołaniach wszystkich składników.

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()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistForecasts);

        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            "fetchdata", out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }
    }

    private Task PersistForecasts()
    {
        ApplicationState.PersistAsJson("fetchdata", 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 utrwalonego wstępnego jest przenoszony do klienta, gdzie jest używany do przywrócenia stanu składnika. ASP.NET Core Data Protection gwarantuje, że dane są bezpiecznie przesyłane w Blazor Server aplikacjach.

Rozmiar stanu wstępnego i SignalR limit rozmiaru komunikatu

Duży rozmiar stanu wstępnego może przekroczyć Blazorlimit rozmiaru komunikatu obwodu SignalR , co powoduje następujące kwestie:

  • Nie SignalR można zainicjować obwodu z powodu błędu 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 limit rozmiaru komunikatu.SignalR 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ę aparatu wyszukiwania (SEO) przez renderowanie zawartości początkowej odpowiedzi HTTP, za pomocą których wyszukiwarki mogą obliczyć rangę 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 tagów składnika dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitleskładnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zobacz Control head content in ASP.NET Core apps (Kontrolowanie zawartości głównej w aplikacjach platformy ASP.NET CoreBlazor).

  1. W pliku układu projektu:

    • Dodaj następujący <base> tag i HeadOutlet składnik Pomocnik tagów do <head> elementu w ( Pages/Shared/_Layout.cshtmlRazor 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ą, postępuj zgodnie ze wskazówkami w sekcji Ścieżka podstawowa aplikacji w artykule Host i wdróż ASP.NET CoreBlazor.

      Składnik jest używany do renderowania HeadOutlet zawartości nagłówka () dla tytułów stron (<head>PageTitleskładnik) i innych elementów głównych (HeadContentskładnik) ustawionych przez Razor składniki. Aby uzyskać więcej informacji, zobacz Control head content in ASP.NET Core apps (Kontrolowanie zawartości głównej w aplikacjach platformy ASP.NET CoreBlazor).

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

      Pages/Shared/_Layout.cshtml (Razor Pages) 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ą. {APP NAMESPACE} Zmień symbol zastępczy 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. Blazor Server Zarejestruj usługi, w Program.cs których są zarejestrowane usługi:

    builder.Services.AddServerSideBlazor();

  4. Blazor Dodaj punkt końcowy centrum do punktów końcowychProgram.cs, w których są mapowane trasy.

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

    app.MapBlazorHub();

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

    Pages/Shared/Counter.razor (Razor Pages) 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 Razor projektu Index aplikacji Pages dodaj Counter przestrzeń nazw składnika i osadź składnik na stronie. Po załadowaniu Index Counter strony składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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 Counter przestrzeń nazw składnika i osadź składnik w widoku. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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żywanie składników routingu Razor w aplikacji Pages

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routingiem z żą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. App Dodaj składnik 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 _Layout.cshtml pliku do ich układu.

    Ważne

    Użycie strony układu (_Layout.cshtml) z pomocnikiem tagów składnika dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitleskładnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zobacz Control head content in ASP.NET Core apps (Kontrolowanie zawartości głównej w aplikacjach platformy ASP.NET CoreBlazor).

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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 składniki routingu do projektu. Poniższy przykład jest składnikiem opartym RoutableCounter na składniku Counter Blazor w szablonach projektu.

    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 routingiem z żądań użytkowników.

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

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

  2. App Dodaj składnik 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 _Layout.cshtml pliku do ich układu.

    Ważne

    Użycie strony układu (_Layout.cshtml) z pomocnikiem tagów składnika dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitleskładnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zobacz Control head content in ASP.NET Core apps (Kontrolowanie zawartości głównej w aplikacjach platformy ASP.NET CoreBlazor).

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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. Program.cs W punktach końcowych dodaj trasę o niskim priorytecie dla akcji kontrolera zwracającej _Host widok:

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

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

    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 dodawania składników do stron lub widoków, gdzie składniki nie są bezpośrednio routingowe z żądań użytkowników.

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

Renderowanie składników interakcyjnych stanowych

Składniki interaktywne stanowe można dodać do Razor strony lub widoku.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie wypełniony stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązywania 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 tagów składnika dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitleskładnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zobacz Control head content in ASP.NET Core apps (Kontrolowanie zawartości głównej w aplikacjach platformy ASP.NET CoreBlazor).

Renderowanie składników nieinteraktywnych

Na poniższej Razor stronie Counter składnik jest statycznie renderowany z wartością początkową określoną przy użyciu 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 tagów składnika dla HeadOutlet składnika jest wymagane do kontrolowania <head> zawartości, takiej jak tytuł strony (PageTitleskładnik) i inne elementy główne (HeadContent składnik). Aby uzyskać więcej informacji, zobacz Control head content in ASP.NET Core apps (Kontrolowanie zawartości głównej w aplikacjach platformy ASP.NET CoreBlazor).

Przestrzenie nazw składników

W przypadku przechowywania składników projektu Razor przy użyciu folderu niestandardowego dodaj przestrzeń nazw reprezentującą folder do strony/widoku lub do _ViewImports.cshtml pliku. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol {APP NAMESPACE} zastępczy to 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 Podstawowe Razor składniki.

Utrwalanie stanu wstępnego

Bez utrwalania stanu wstępnego, stan używany podczas prerenderingu jest utracony i musi zostać utworzony ponownie, gdy aplikacja jest w pełni załadowana. Jeśli jakikolwiek stan jest skonfigurowany asynchronicznie, interfejs użytkownika może migać, ponieważ wstępnie wypełniony interfejs użytkownika jest zastępowany symbolami zastępczymi tymczasowymi, a następnie w pełni renderowany ponownie.

Aby rozwiązać te problemy, Blazor obsługuje stan utrwalania na stronie wstępnie obsługiwanej przy użyciu pomocnika Tag stanu składnika utrwalania. 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.

Poniższy przykład to zaktualizowana wersja FetchData składnika na podstawie szablonu Blazor projektu. Składnik WeatherForecastPreserveState utrzymuje stan prognozy pogody podczas prerenderingu, a następnie pobiera stan w celu zainicjowania składnika. Pomocnik stanu stanu składnika utrwala stan składnika po wywołaniach wszystkich składników.

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()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistForecasts);

        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            "fetchdata", out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateTime.Now);
        }
        else
        {
            forecasts = restored!;
        }
    }

    private Task PersistForecasts()
    {
        ApplicationState.PersistAsJson("fetchdata", 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 utrwalonego wstępnego jest przenoszony do klienta, gdzie jest używany do przywrócenia stanu składnika. ASP.NET Core Data Protection gwarantuje, że dane są bezpiecznie przesyłane w Blazor Server aplikacjach.

Rozmiar stanu wstępnego i SignalR limit rozmiaru komunikatu

Duży rozmiar stanu wstępnego może przekroczyć Blazorlimit rozmiaru komunikatu obwodu SignalR , co powoduje następujące kwestie:

  • Nie SignalR można zainicjować obwodu z powodu błędu 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 limit rozmiaru komunikatu.SignalR 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ę aparatu wyszukiwania (SEO) przez renderowanie zawartości początkowej odpowiedzi HTTP, za pomocą których wyszukiwarki mogą obliczyć rangę 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 <base> tag do <head> elementu w (Razor Pages/Shared/_Layout.cshtml 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ą, postępuj zgodnie ze wskazówkami w sekcji Ścieżka podstawowa aplikacji w artykule Host i wdróż ASP.NET CoreBlazor.

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

      Pages/Shared/_Layout.cshtml (Razor Pages) 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ą. {APP NAMESPACE} Zmień symbol zastępczy 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. Blazor Dodaj punkt końcowy centrum do punktów końcowych (app.UseEndpoints) z Startup.Configure.

    Startup.cs:

    endpoints.MapBlazorHub();

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

    Pages/Shared/Counter.razor (Razor Pages) 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 Razor projektu Index aplikacji Pages dodaj Counter przestrzeń nazw składnika i osadź składnik na stronie. Po załadowaniu Index Counter strony składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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 {APP NAMESPACE} symbol zastępczy przestrzenią nazw aplikacji.

    MVC:

    W widoku projektu Index aplikacji MVC dodaj Counter przestrzeń nazw składnika i osadź składnik w widoku. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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żywanie składników routingu Razor w aplikacji Pages

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routingiem z żą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. App Dodaj składnik 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

    Od wydania wersji ASP.NET Core 5.0.1 i w przypadku wszelkich dodatkowych wydań 5.x składnik Router zawiera parametr PreferExactMatches ustawiony na wartość @true. Aby uzyskać więcej informacji, zobacz Migracja z platformy ASP.NET Core w wersji 3.1 do wersji 5.0.

  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 _Layout.cshtml pliku do ich układu.

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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. Startup.Configure W punktach końcowych programu dodaj trasę o niskim priorytecie Startup.csdla _Host strony jako ostatni punkt końcowy:

    endpoints.MapFallbackToPage("/_Host");

    W poniższym przykładzie pokazano dodany wiersz w typowej konfiguracji punktu końcowego aplikacji:

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

  5. Dodaj składniki routingu 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 routingiem z żądań użytkowników.

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

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

  2. App Dodaj składnik 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

    Od wydania wersji ASP.NET Core 5.0.1 i w przypadku wszelkich dodatkowych wydań 5.x składnik Router zawiera parametr PreferExactMatches ustawiony na wartość @true. Aby uzyskać więcej informacji, zobacz Migracja z platformy ASP.NET Core w wersji 3.1 do wersji 5.0.

  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 _Layout.cshtml pliku do ich układu.

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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 programu dodaj trasę o niskim priorytecie Startup.csdla akcji kontrolera zwracającej _Host widok:

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

    W poniższym przykładzie pokazano dodany wiersz 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 składniki routingu 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 dodawania składników do stron lub widoków, gdzie składniki nie są bezpośrednio routingowe z żądań użytkowników.

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

Renderowanie składników interakcyjnych stanowych

Składniki interaktywne stanowe można dodać do Razor strony lub widoku.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie wypełniony stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązywania 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 Counter składnik jest statycznie renderowany z wartością początkową określoną przy użyciu 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

W przypadku przechowywania składników projektu Razor przy użyciu folderu niestandardowego dodaj przestrzeń nazw reprezentującą folder do strony/widoku lub do _ViewImports.cshtml pliku. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol {APP NAMESPACE} zastępczy to 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 Podstawowe Razor składniki.

Rozmiar stanu wstępnego i SignalR limit rozmiaru komunikatu

Duży rozmiar stanu wstępnego może przekroczyć Blazorlimit rozmiaru komunikatu obwodu SignalR , co powoduje następujące kwestie:

  • Nie SignalR można zainicjować obwodu z powodu błędu 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 limit rozmiaru komunikatu.SignalR 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ę aparatu wyszukiwania (SEO) przez renderowanie zawartości początkowej odpowiedzi HTTP, za pomocą których wyszukiwarki mogą obliczyć rangę 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 <base> tag do <head> elementu w (Razor Pages/Shared/_Layout.cshtml 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ą, postępuj zgodnie ze wskazówkami w sekcji Ścieżka podstawowa aplikacji w artykule Host i wdróż ASP.NET CoreBlazor.

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

      Pages/Shared/_Layout.cshtml (Razor Pages) 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ą. {APP NAMESPACE} Zmień symbol zastępczy 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. Blazor Dodaj punkt końcowy centrum do punktów końcowych (app.UseEndpoints) z Startup.Configure.

    Startup.cs:

    endpoints.MapBlazorHub();

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

    Pages/Shared/Counter.razor (Razor Pages) 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 Razor projektu Index aplikacji Pages dodaj Counter przestrzeń nazw składnika i osadź składnik na stronie. Po załadowaniu Index Counter strony składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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 {APP NAMESPACE} symbol zastępczy przestrzenią nazw aplikacji.

    MVC:

    W widoku projektu Index aplikacji MVC dodaj Counter przestrzeń nazw składnika i osadź składnik w widoku. Index Gdy widok zostanie załadowany, Counter składnik jest wstępnie zainstalowany na stronie. W poniższym przykładzie zastąp {APP NAMESPACE} symbol zastępczy 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żywanie składników routingu Razor w aplikacji Pages

Ta sekcja dotyczy dodawania składników, które są bezpośrednio routingiem z żą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. App Dodaj składnik 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 _Layout.cshtml pliku do ich układu.

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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. Startup.Configure W punktach końcowych programu dodaj trasę o niskim priorytecie Startup.csdla _Host strony jako ostatni punkt końcowy:

    endpoints.MapFallbackToPage("/_Host");

    W poniższym przykładzie pokazano dodany wiersz w typowej konfiguracji punktu końcowego aplikacji:

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

  5. Dodaj składniki routingu 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 routingiem z żądań użytkowników.

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

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

  2. App Dodaj składnik 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 _Layout.cshtml pliku do ich układu.

    RenderMode konfiguruje, czy App składnik:

    • Jest wstępnie załadowany do strony.
    • Jest renderowany jako statyczny kod HTML na stronie lub jeśli zawiera informacje niezbędne do uruchomienia Blazor aplikacji z 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 programu dodaj trasę o niskim priorytecie Startup.csdla akcji kontrolera zwracającej _Host widok:

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

    W poniższym przykładzie pokazano dodany wiersz 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 składniki routingu 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 dodawania składników do stron lub widoków, gdzie składniki nie są bezpośrednio routingowe z żądań użytkowników.

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

Renderowanie składników interakcyjnych stanowych

Składniki interaktywne stanowe można dodać do Razor strony lub widoku.

Gdy strona lub widok są renderowane:

  • Składnik jest wstępnie wypełniony stroną lub widokiem.
  • Utracono początkowy stan składnika używany do prerenderingu.
  • Nowy stan składnika jest tworzony podczas nawiązywania 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 Counter składnik jest statycznie renderowany z wartością początkową określoną przy użyciu 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

W przypadku przechowywania składników projektu Razor przy użyciu folderu niestandardowego dodaj przestrzeń nazw reprezentującą folder do strony/widoku lub do _ViewImports.cshtml pliku. W poniższym przykładzie:

  • Składniki są przechowywane w Components folderze projektu.
  • Symbol {APP NAMESPACE} zastępczy to 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 Podstawowe Razor składniki.

Rozmiar stanu wstępnego i SignalR limit rozmiaru komunikatu

Duży rozmiar stanu wstępnego może przekroczyć Blazorlimit rozmiaru komunikatu obwodu SignalR , co powoduje następujące kwestie:

  • Nie SignalR można zainicjować obwodu z powodu błędu 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 limit rozmiaru komunikatu.SignalR OSTRZEŻENIE: Zwiększenie limitu może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS).

Dodatkowe Blazor Server zasoby