Integrace komponent ASP.NET Core Razor do aplikací ASP.NET Core

  • Článek

Tento článek vysvětluje Razor scénáře integrace komponent pro aplikace ASP.NET Core.

Razor integrace komponent

Razor komponenty lze integrovat do Razor pages, MVC a dalších typů aplikací ASP.NET Core. Razor komponenty lze také integrovat do jakékoli webové aplikace, včetně aplikací, které nejsou založené na ASP.NET Core, jako vlastní prvky HTML.

Pokyny najdete v následujících částech v závislosti na požadavcích aplikace:

Použití nesměrovatelných komponent na stránkách nebo zobrazeních

Následující doprovodné materiály použijte k integraci Razor komponent do stránek nebo zobrazení existující Razor aplikace Pages nebo MVC s pomocným pomocníkem pro značky komponent.

Poznámka:

Pokud vaše aplikace vyžaduje přímo směrovatelné komponenty (ne vložené do stránek nebo zobrazení), přeskočte tuto část a použijte pokyny v části Přidat Blazor podporu do oddílu aplikace ASP.NET Core.

Při použití předběžného vykreslování serveru a vykreslení stránky nebo zobrazení:

  • Komponenta je předem vytyčována stránkou nebo zobrazením.
  • Počáteční stav součásti použitý pro předkreslování je ztracen.
  • Při navázání připojení se vytvoří SignalR nový stav komponenty.

Další informace o režimech vykreslování, včetně neinteraktivního vykreslování statických komponent, najdete v nápovědě značky komponenty v ASP.NET Core. Chcete-li uložit stav předseklovaných Razor komponent, přečtěte si téma Zachování pomocné rutiny značky stavu komponenty v ASP.NET Core.

Components Přidejte složku do kořenové složky projektu.

Přidejte do Components složky import soubor s následujícím obsahem. {APP NAMESPACE} Změňte zástupný symbol na obor názvů projektu.

Components/_Imports.razor:

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

V souboru rozložení projektu (Pages/Shared/_Layout.cshtml v Razor aplikacích Pages nebo Views/Shared/_Layout.cshtml v aplikacích MVC):

  • Přidejte do značky následující <base> značku a pomocné rutiny HeadOutlet <head> značky komponent:

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

    Hodnota href (základní cesta aplikace) v předchozím příkladu předpokládá, že se aplikace nachází v kořenové cestě URL (/). Pokud je aplikace dílčí aplikací, postupujte podle pokynů v části Základní cesta aplikace v článku Hostitel a nasaďte ASP.NET CoreBlazor.

    Tato komponenta HeadOutlet slouží k vykreslení obsahu hlavy (<head>) pro názvy stránek (PageTitle součást) a další hlavní prvky (HeadContent komponenta) nastavené komponentami Razor . Další informace najdete v tématu Řízení hlavního obsahu v aplikacích ASP.NET CoreBlazor.

  • <script> Přidejte značku blazor.web.js skriptu bezprostředně před Scripts oddíl vykreslení (@await RenderSectionAsync(...)):

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

    Architektura Blazor automaticky přidá blazor.web.js skript do aplikace.

Poznámka:

Rozložení se obvykle načte prostřednictvím _ViewStart.cshtml souboru.

Přidejte do projektu neoperativně (no-op) App komponentu.

Components/App.razor:

@* No-op App component *@

Pokud jsou služby zaregistrované, přidejte služby pro Razor komponenty a služby, které podporují vykreslování komponent Interactive Serveru.

V horní části Program souboru přidejte using do horní části souboru příkaz pro komponenty projektu:

using {APP NAMESPACE}.Components;

Na předchozím řádku změňte {APP NAMESPACE} zástupný symbol na obor názvů aplikace. Příklad:

using BlazorSample.Components;

Program V souboru před řádkem, který sestaví aplikaci (builder.Build()):

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

Další informace o přidání podpory pro součásti Interactive Server a WebAssembly najdete v tématu ASP.NET Režimy vykreslování CoreBlazor.

Program V souboru bezprostředně po volání mapových Razor stránek (MapRazorPages) v Razor aplikaci Pages nebo namapování výchozí trasy kontroleru (MapControllerRoute) v aplikaci MVC, voláním MapRazorComponents zjišťování dostupných komponent a určením kořenové komponenty aplikace (první načtená komponenta). Ve výchozím nastavení je kořenová komponenta aplikace komponentou App (App.razor). Zřetězte volání pro AddInteractiveServerRenderMode konfiguraci interaktivního vykreslování na straně serveru (interaktivní SSR) pro aplikaci:

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

Poznámka:

Pokud aplikace ještě nebyla aktualizována tak, aby zahrnovala Middleware Antiforgery, přidejte následující řádek po UseAuthorization zavolání:

app.UseAntiforgery();

Integrujte komponenty do libovolné stránky nebo zobrazení. Například přidejte komponentu EmbeddedCounter do složky projektu Components .

Components/EmbeddedCounter.razor:

<h1>Embedded 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 Stránky:

Na stránce Razor projektu Index aplikace Pages přidejte EmbeddedCounter obor názvů komponenty a vložte ji do stránky. Když se Index stránka načte, komponenta EmbeddedCounter je na stránce předem vyřazována. V následujícím příkladu nahraďte {APP NAMESPACE} zástupný symbol oborem názvů projektu.

Pages/Index.cshtml:

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

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

MVC:

V zobrazení projektu Index aplikace MVC přidejte EmbeddedCounter obor názvů komponenty a vložte ji do zobrazení. Když se Index zobrazení načte, komponenta EmbeddedCounter je na stránce předem vyřazována. V následujícím příkladu nahraďte {APP NAMESPACE} zástupný symbol oborem názvů projektu.

Views/Home/Index.cshtml:

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

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

Přidání Blazor podpory do aplikace ASP.NET Core

Tato část popisuje přidání Blazor podpory do aplikace ASP.NET Core:

Poznámka:

V příkladech v této části je BlazorSamplenázev a obor názvů ukázkové aplikace .

Přidání statického vykreslování na straně serveru (statická SSR)

Components Přidejte do aplikace složku.

Přidejte následující _Imports soubor pro obory názvů používané komponentami Razor .

Components/_Imports.razor:

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

Změňte zástupný symbol oboru názvů ({APP NAMESPACE}) na obor názvů aplikace. Příklad:

@using BlazorSample
@using BlazorSample.Components

Blazor Přidejte směrovač (<Router>,Router) do aplikace v komponentěRoutes, která je umístěná ve složce aplikaceComponents.

Components/Routes.razor:

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
</Router>

Přidejte do aplikace komponentu App , která slouží jako kořenová komponenta, což je první komponenta, kterou aplikace načte.

Components/App.razor:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="@Assets["{ASSEMBLY NAME}.styles.css"]" />
    <HeadOutlet />
</head>

<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>

</html>

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="{ASSEMBLY NAME}.styles.css" />
    <HeadOutlet />
</head>

<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>

</html>

Zástupný {ASSEMBLY NAME} symbol je název sestavení aplikace. Například projekt s názvem ContosoApp sestavení používá ContosoApp.styles.css název souboru šablony stylů.

Pages Přidejte do Components složky složku pro uložení směrovatelných Razor komponent.

Přidejte následující Welcome komponentu pro předvedení statického serveru SSR.

Components/Pages/Welcome.razor:

@page "/welcome"

<PageTitle>Welcome!</PageTitle>

<h1>Welcome to Blazor!</h1>

<p>@message</p>

@code {
    private string message = 
        "Hello from a Razor component and welcome to Blazor!";
}

V souboru projektu Program ASP.NET Core:

  • using Přidejte příkaz na začátek souboru pro komponenty projektu:

    using {APP NAMESPACE}.Components;

    Na předchozím řádku změňte {APP NAMESPACE} zástupný symbol na obor názvů aplikace. Příklad:

    using BlazorSample.Components;

  • Přidání Razor služeb komponent (AddRazorComponents), které také automaticky přidávají antiforgery (AddAntiforgery). Před řádek, který volá, builder.Build()přidejte následující řádek ):

    builder.Services.AddRazorComponents();

  • Přidejte middleware Antiforgery do kanálu zpracování požadavků pomocí UseAntiforgery. UseAntiforgery je volána po volání UseRouting. Pokud existují volání UseRouting a UseEndpointsvolání musí UseAntiforgery jít mezi nimi. Hovor UseAntiforgery musí být umístěn po volání a UseAuthentication UseAuthorization.

    app.UseAntiforgery();

  • Přidejte MapRazorComponents do kanálu zpracování požadavků aplikace s komponentou App (App.razor) určenou jako výchozí kořenová komponenta (první načtená komponenta). Před řádek, který volá app.Run, umístěte následující kód:

    app.MapRazorComponents<App>();

Po spuštění Welcome aplikace se ke komponentě přistupuje v koncovém /welcome bodu.

Povolení interaktivního vykreslování na straně serveru (interaktivní SSR)

Postupujte podle pokynů v části Přidání statického vykreslování na straně serveru (statická služba SSR).

V souboru aplikace Program přidejte volání, do AddInteractiveServerComponents kterého Razor se přidávají služby komponent:AddRazorComponents

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

Přidejte volání, do AddInteractiveServerRenderMode kterého Razor se komponenty mapují:MapRazorComponents

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

Přidejte do aplikace následující Counter komponentu, která přijímá interaktivní vykreslování na straně serveru (interaktivní SSR).

Components/Pages/Counter.razor:

@page "/counter"
@rendermode InteractiveServer

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

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

Když je aplikace spuštěna, Counter je komponenta přístupná na adrese /counter.

Povolení interaktivního automatického (automatického) nebo klientského vykreslování (CSR)

Postupujte podle pokynů v části Přidání statického vykreslování na straně serveru (statická služba SSR).

Komponenty používající režim interaktivního automatického vykreslování zpočátku používají interaktivní SSR. Modul runtime .NET a sada aplikací se stáhnou do klienta na pozadí a uloží se do mezipaměti, aby je bylo možné použít při budoucích návštěvách. Komponenty používající režim interaktivního vykreslování WebAssembly se v klientovi vykreslují interaktivně pouze po Blazor stažení sady a aktivaci Blazor modulu runtime. Mějte na paměti, že při použití režimu interaktivního automatického nebo interaktivního vykreslování WebAssembly není kód komponenty stažený do klienta soukromý. Další informace najdete v tématu ASP.NET režimy vykreslování coreBlazor.

Po rozhodnutí, který režim vykreslování se má přijmout:

Přidejte do aplikace odkaz na Microsoft.AspNetCore.Components.WebAssembly.Server balíček NuGet.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Vytvořte dárca Blazor Web App , který aplikaci poskytne prostředky. Při generování Blazor Web Appšablony postupujte podle pokynů v nástrojích pro ASP.NET Core Blazor a vyberte podporu pro následující funkce šablony.

Jako název aplikace použijte stejný název jako aplikace ASP.NET Core, což má za následek odpovídající kód názvu aplikace v komponentách a odpovídajících oborech názvů v kódu. Použití stejného názvu nebo oboru názvů není nezbytně nutné, protože obory názvů je možné upravit po přesunu prostředků z aplikace dárců do aplikace ASP.NET Core. Čas se však ukládá tak, že se na začátku shoduje s obory názvů.

Visual Studio:

  • V režimu interaktivního vykreslování vyberte Možnost Automaticky (Server a WebAssembly).
  • Nastavte umístění interaktivity na jednotlivé stránky nebo součásti.
  • Zrušte zaškrtnutí políčka u ukázkových stránek zahrnout.

.NET CLI:

  • Použijte tuto -int Auto možnost.
  • Tuto možnost nepoužívejte -ai|--all-interactive .
  • -e|--empty Předejte možnost.

Od dárce Blazor Web Appzkopírujte celý .Client projekt do složky řešení aplikace ASP.NET Core.

Důležité

Složku nekopírujte .Client do složky projektu ASP.NET Core. Nejlepším přístupem pro uspořádání řešení .NET je umístit každý projekt řešení do vlastní složky ve složce řešení nejvyšší úrovně. Pokud složka řešení nad složkou ASP.NET Core projektu neexistuje, vytvořte ji. V dalším kroku zkopírujte .Client složku projektu od dárce Blazor Web App do složky řešení. Konečná struktura složek projektu by měla mít následující rozložení:

  • BlazorSampleSolution (složka řešení nejvyšší úrovně)
    • BlazorSample (původní projekt ASP.NET Core)
    • BlazorSample.Client (.Client projektová složka od dárce Blazor Web App)

U souboru řešení ASP.NET Core ho můžete ponechat ve složce projektu ASP.NET Core. Případně můžete přesunout soubor řešení nebo vytvořit nový soubor ve složce řešení nejvyšší úrovně, pokud projekt správně odkazuje na soubory projektu (.csproj) obou projektů ve složce řešení.

Pokud jste při vytváření projektu dárce Blazor Web App pojmenovali stejného jako aplikace ASP.NET Core, odpovídají obory názvů využívané darovanými prostředky těm, které jsou v aplikaci ASP.NET Core. Neměli byste provádět další kroky, které by odpovídaly oborům názvů. Pokud jste při vytváření projektu dárce Blazor Web App použili jiný obor názvů, musíte upravit obory názvů v rámci darovaných prostředků tak, aby odpovídaly, pokud chcete použít rest tyto pokyny přesně tak, jak je uvedeno. Pokud se obory názvů neshodují, upravte obory názvů před pokračováním nebo upravte obory názvů podle zbývajících pokynů v této části.

Odstraňte dárca Blazor Web App, protože v tomto procesu nemá žádné další použití.

.Client Přidejte projekt do řešení:

  • Visual Studio: Klikněte pravým tlačítkem na řešení v Průzkumník řešení a vyberte Přidat>existující projekt. Přejděte do .Client složky a vyberte soubor projektu (.csproj).

  • .NET CLI: Pomocí dotnet sln add příkazu přidejte .Client projekt do řešení.

Do klientského projektu přidejte odkaz na projekt ASP.NET Core:

  • Visual Studio: Klikněte pravým tlačítkem na projekt ASP.NET Core a vyberte Přidat>odkaz na projekt. .Client Vyberte projekt a vyberte OK.

  • .NET CLI: Ze složky projektu ASP.NET Core použijte následující příkaz:

    dotnet add reference ../BlazorSample.Client/BlazorSample.Client.csproj

    Předchozí příkaz předpokládá následující:

    • Název souboru projektu je BlazorSample.Client.csproj.
    • Projekt .Client je ve BlazorSample.Client složce uvnitř složky řešení. Složka .Client je vedle složky projektu ASP.NET Core.

    Další informace o dotnet add reference příkazu najdete dotnet add reference v dokumentaci k .NET.

V souboru aplikace Program ASP.NET Core proveďte následující změny:

  • Přidat interaktivní služby komponent WebAssembly s umístěním AddInteractiveWebAssemblyComponents Razor komponent služby jsou přidány s AddRazorComponents.

    Interaktivní automatické vykreslování:

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

    Pouze pro interaktivní vykreslování WebAssembly:

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

  • Přidejte interaktivní režim vykreslování WebAssembly (AddInteractiveWebAssemblyRenderMode) a další sestavení pro .Client projekt, ve kterém Razor jsou komponenty mapovány MapRazorComponents.

    Interaktivní automatické vykreslování:

    app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

    Pouze pro interaktivní vykreslování WebAssembly:

    app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

    V předchozích příkladech změňte BlazorSample.Client shodu s oborem .Client názvů projektu.

Pages Přidejte do .Client projektu složku.

Pokud má projekt ASP.NET Core existující Counter komponentu:

  • Přesuňte komponentu Pages do složky .Client projektu.
  • Odeberte direktivu @rendermode v horní části souboru komponenty.

Pokud aplikace ASP.NET Core nemá komponentuCounter, přidejte do projektu následující Counter komponentu .Client (Pages/Counter.razor):

@page "/counter"
@rendermode InteractiveAuto

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

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

Pokud aplikace přijímá pouze interaktivní vykreslování WebAssembly, odeberte direktivu @rendermode a hodnotu:

- @rendermode InteractiveAuto

Spusťte řešení z projektu aplikace ASP.NET Core:

  • Visual Studio: Ověřte, že při spuštění aplikace je vybraný projekt ASP.NET Core v Průzkumník řešení.

  • .NET CLI: Spusťte projekt ze složky projektu ASP.NET Core.

Chcete-li načíst Counter součást, přejděte na /counter.

Implementace Blazorrozložení a stylů

Volitelně můžete přiřadit výchozí komponentu rozložení pomocí RouteView.DefaultLayout parametru RouteView komponenty.

V Routes.razornásledujícím příkladu MainLayout se jako výchozí rozložení používá komponenta:

<RouteView RouteData="routeData" DefaultLayout="typeof(MainLayout)" />

Další informace najdete v tématu ASP.NET rozložení jádraBlazor.

Blazor Rozložení šablony projektu a šablony stylů jsou k dispozici v dotnet/aspnetcore úložišti GitHub:

  • MainLayout.razor
  • MainLayout.razor.css
  • NavMenu.razor
  • NavMenu.razor.css

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

V závislosti na tom, jak v aplikaci uspořádáte soubory rozložení, budete možná muset do souboru aplikace _Imports.razor přidat @using příkaz pro složku souborů rozložení, abyste je mohli zobrazit pro použití v komponentách aplikace.

Při použití izolace šablon stylů CSS není nutné explicitně odkazovat na šablony stylů. Architektura Blazor automaticky sbalí jednotlivé šablony stylů komponent. Sada šablon stylů aplikace je již odkazována v komponentě App aplikace ({ASSEMBLY NAME}.styles.csskde {ASSEMBLY NAME} zástupný symbol je název sestavení aplikace).

RazorComponentResult Vrácení akce kontroleru MVC

Akce kontroleru MVC může vrátit komponentu s RazorComponentResult<TComponent>.

Components/Welcome.razor:

<PageTitle>Welcome!</PageTitle>

<h1>Welcome!</h1>

<p>@Message</p>

@code {
    [Parameter]
    public string? Message { get; set; }
}

V kontroleru:

public IResult GetWelcomeComponent() => 
    new RazorComponentResult<Welcome>(new { Message = "Hello, world!" });

Vrátí se pouze kód HTML pro vykreslovanou komponentu. Rozložení a značky stránky HTML nejsou automaticky vykresleny komponentou. Aby se vytvořila úplná stránka HTML, může aplikace udržovat Blazor rozložení, které poskytuje kód HTML pro <html>, <body><head>a další značky. Komponenta obsahuje rozložení se direktivou @layoutRazor v horní části definičního souboru komponenty, Welcome.razor například v této části. Následující příklad předpokládá, že aplikace má rozložení s názvem RazorComponentResultLayout (Components/Layout/RazorComponentResultLayout.razor):

@using BlazorSample.Components.Layout
@layout RazorComponentResultLayout

Příkaz pro Layout složku můžete umístit @using do jednotlivých komponent tak, že ho přesunete do souboru aplikace_Imports.razor.

Další informace najdete v tématu ASP.NET rozložení jádraBlazor.

Obory názvů komponent

Při použití vlastní složky k uložení součástí projektu Razor přidejte obor názvů představující složku do stránky nebo zobrazení nebo do _ViewImports.cshtml souboru. V následujícím příkladu:

  • Komponenty jsou uloženy ve Components složce projektu.
  • Zástupný {APP NAMESPACE} symbol je obor názvů projektu. Components představuje název složky.
@using {APP NAMESPACE}.Components

Příklad:

@using BlazorSample.Components

Soubor _ViewImports.cshtml se nachází ve Pages složce Razor aplikace Pages nebo Views ve složce aplikace MVC.

Další informace najdete v tématu ASP.NET základní Razor komponenty.

Další materiály

Prerender ASP.NET Core Razor components