Sdílet prostřednictvím

Vytvoření opakovaně použitelného uživatelského rozhraní pomocí Razor projektu knihovny tříd v ASP.NET Core

  • Článek

Autor: Rick Anderson

Razor zobrazení, stránky, kontrolery, modely stránek, Razor komponenty, komponenty zobrazení a datové modely lze integrovat do Razor knihovny tříd (RCL). RCL lze zabalit a znovu použít. Aplikace mohou zahrnovat RCL a přepsat zobrazení a stránky, které obsahuje. Když se ve webové aplikaci i v RCL najde zobrazení, částečné zobrazení nebo Razor stránka, přednost bude mít Razor značení (.cshtml soubor) ve webové aplikaci.

Informace o tom, jak integrovat npm a webpack do procesu sestavení pro knihovnu tříd Razor (RCL), najdete v tématu Vytvoření webových prostředků klienta pro vaši Razor knihovnu tříd.

Vytvořte knihovnu tříd obsahující Razor uživatelské rozhraní

  • V sadě Visual Studio vyberte Vytvořit nový nový projekt.
  • Vyberte Razor knihovnu tříd>Další.
  • Pojmenujte knihovnu (například RazorClassLib), >Vytvořte. Aby nedocházelo ke kolizi názvu souboru s vygenerovanou knihovnou zobrazení, ujistěte se, že název knihovny nekončí .Views.
  • Pro zajištění toho, aby knihovna obsahovala stránky a/nebo zobrazení, vyberte podporu stránek a zobrazení. Ve výchozím nastavení se podporují jenom Razor komponenty. Vyberte Vytvořit.

Šablona Razor knihovny tříd standardně umožňuje Razor vývoj komponent. Možnost stránky a zobrazení podpory podporuje stránky a zobrazení. Další informace o podpoře RCL naleznete v tématu BlazorVyužití komponent ASP.NET Core z knihovny tříd (RCL).

Přidejte Razor soubory do RCL.

Šablony ASP.NET Core předpokládají, že obsah seznamu RCL je ve Areas složce. Viz níže rozložení stránek RCL pro vytvoření RCL, který zpřístupňuje obsah v ~/Pages, namísto ~/Areas/Pages.

Referenční obsah RCL

Na seznam RCL lze odkazovat pomocí:

Předdefinování zobrazení, částečných zobrazení a stránek

Když je nalezeno zobrazení, částečné zobrazení nebo Razor stránka jak ve webové aplikaci, tak v RCL, Razor značkový soubor (.cshtml soubor) ve webové aplikaci má přednost. Například přidání WebApp1/Areas/MyFeature/Pages/Page1.cshtml do WebApp1 a Stránka1 ve WebApp1 bude mít přednost před Stránkou1 v RCL.

V ukázkovém souboru přejmenujte WebApp1/Areas/MyFeature2 na WebApp1/Areas/MyFeature pro otestování priority.

Zkopírujte RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml částečné zobrazení do WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtmlsložky. Aktualizujte značkování tak, aby označovalo nové umístění. Sestavte a spusťte aplikaci, abyste ověřili, že se používá verze částečné aplikace.

Pokud RCL používá Razor stránky, povolte služby Pages a koncové body v hostitelské aplikaci:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Rozložení stránek RCL

Pokud chcete odkazovat na obsah seznamu RCL, jako by byl součástí složky webové aplikace Pages , vytvořte projekt RCL s následující strukturou souborů:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Předpokládejme, že RazorUIClassLib/Pages/Shared obsahuje dva částečné soubory: _Header.cshtml a _Footer.cshtml. Značky <partial> se dají přidat do _Layout.cshtml souboru:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

_ViewStart.cshtml Přidejte soubor do složky projektu Pages RCL pro použití _Layout.cshtml souboru z hostitelské webové aplikace:

@{
    Layout = "_Layout";
}

Vytvoření RCL se statickými prostředky

RCL může vyžadovat doprovodné statické zdroje, na které může odkazovat buď samotné RCL, nebo aplikace využívající RCL. ASP.NET Core umožňuje vytvářet seznamy RCLS, které obsahují statické prostředky, které jsou dostupné pro využívání aplikace.

Pokud chcete zahrnout doprovodné prostředky jako součást seznamu RCL, vytvořte wwwroot složku v knihovně tříd a zahrňte do této složky všechny požadované soubory.

Při balení RCL se všechny související soubory ve složce wwwroot automaticky zahrnou do balíčku.

dotnet pack Místo verze NuGet.exe nuget packpoužijte příkaz .

Přidání webových prostředků klienta do procesu sestavení

Integrace webových prostředků klienta do sestavovacího procesu je náročná. Další informace najdete v tématu Vytvoření webových prostředků klienta pro knihovnu tříd Razor.

Vyloučit statická aktiva

Chcete-li vyloučit statické prostředky, přidejte požadovanou cestu vyloučení do $(DefaultItemExcludes) skupiny vlastností v souboru projektu. Oddělte položky středníkem (;).

V následujícím příkladu se šablona stylů lib.css ve složce wwwroot nepovažuje za statický prostředek a není zahrnuta v publikovaném RCL.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integrace TypeScriptu

Chcete-li zahrnout soubory TypeScript do RCL:

  • Odkazujte na Microsoft.TypeScript.MSBuild balíček NuGet v projektu.

    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.

  • Umístěte soubory TypeScriptu (.ts) mimo wwwroot složku. Například soubory umístěte do Client složky.

  • Do souboru projektu přidejte následující kód:

    • Nakonfigurujte výstup sestavení TypeScriptu pro složku wwwroot s vlastností TypescriptOutDir.
    • Zahrňte cíl TypeScriptu jako závislost cíle PrepareForBuildDependsOn.
    • Odeberte výstup v wwwroot folder.
<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    // Markup removed for brevity.
    <TypescriptOutDir>wwwroot</TypescriptOutDir>
    <PrepareForBuildDependsOn>
      CompileTypeScriptWithTSConfig;
      GetTypeScriptOutputForPublishing;$(PrepareForBuildDependsOn)
    </PrepareForBuildDependsOn>
  </PropertyGroup>

  <ItemGroup>
    <Content Remove="wwwroot\{path-to-typescript-outputs}" />
  </ItemGroup>

</Project>

Využívání obsahu z odkazovaného RCL

Soubory ve složce wwwroot v RCL jsou vystaveny buď RCL, nebo cílové aplikaci pod předponou _content/{PACKAGE ID}/. Například knihovna s názvem sestavení Razor.Class.Lib a bez uvedení <PackageId> ve svém projektovém souboru vede k cestě ke statickému obsahu na adrese _content/Razor.Class.Lib/. Při vytváření balíčku NuGet a název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu pro {PACKAGE ID}.

Využívající aplikace odkazuje na statické prostředky poskytované knihovnou s použitím značek <script>, <style>, <img> a dalších HTML značek. Konzumní aplikace musí mít povolenou podporu statických souborů:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Při spuštění spotřební aplikace z výstupu sestavení (dotnet run) jsou statické webové prostředky ve vývojovém prostředí ve výchozím nastavení povoleny. Pokud chcete podporovat prostředky v jiných prostředích při spuštění z výstupu sestavení, zavolejte UseStaticWebAssets tvůrce hostitelů v Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseWebRoot("wwwroot");
builder.WebHost.UseStaticWebAssets();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Volání UseStaticWebAssets se nevyžaduje při spuštění aplikace z publikovaného výstupu (dotnet publish).

Víceprojektový vývojový tok

Při spuštění spotřební aplikace:

  • Prostředky v RCL zůstanou v původních složkách. Prostředky se nepřesouvají do spotřebovávající aplikace.
  • Jakákoli změna ve složce RCL wwwroot se projeví v aplikaci, která RCL používá, po opětovném sestavení RCL, aniž by bylo nutné znovu sestavit samotnou uživatelskou aplikaci.

Při sestavení RCL se vytvoří manifest, který popisuje umístění statických webových prostředků. Spotřebovávající aplikace načítá manifest během běhu, aby čerpala prostředky z odkazovaných projektů a balíčků. Když se do RCL přidá nový prostředek, musí být RCL přestavěno, aby se aktualizoval jeho manifest a aplikace mohla získat přístup k novému prostředku.

Publikovat

Při publikování aplikace se doprovodné prostředky ze všech odkazovaných projektů a balíčků zkopírují do wwwroot složky publikované aplikace v části _content/{PACKAGE ID}/. Při vytváření balíčku NuGet a pokud název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu, při zkoumání složky wwwroot s publikovanými prostředky pro {PACKAGE ID}.

Další materiály

Razor zobrazení, stránky, kontrolery, modely stránek, Razor komponenty, komponenty zobrazení a datové modely lze integrovat do Razor knihovny tříd (RCL). RCL lze zabalit a znovu použít. Aplikace mohou zahrnout RCL a přepsat zobrazení a stránky, které tento komponent obsahuje. Když se v webové aplikaci i v RCL najde zobrazení, částečné zobrazení nebo Razor stránka, má přednost značka (.cshtml soubor) ve webové aplikaci.

Informace o tom, jak integrovat npm a webpack do procesu sestavení knihovny Razor tříd, naleznete v tématu Sestavení webových prostředků klienta pro knihovnu Razortříd.

Vytvořte knihovnu tříd obsahující Razor uživatelské rozhraní

  • V sadě Visual Studio vyberte Vytvořit nový nový projekt.
  • Vyberte Razor knihovnu tříd>Další.
  • Pojmenujte knihovnu (například RazorClassLib), >Vytvořte. Aby nedocházelo ke kolizi názvu souboru s vygenerovanou knihovnou zobrazení, ujistěte se, že název knihovny nekončí .Views.
  • Vyberte stránky a zobrazení podpory, pokud potřebujete podporovat zobrazení. Ve výchozím nastavení se podporují jenom Razor stránky. Vyberte Vytvořit.

Šablona Razor knihovny tříd (RCL) je ve výchozím nastavení nastavena na Razor vývoj komponent. Možnost Stránky a zobrazení podpory podporuje stránky a zobrazení.

Přidejte Razor soubory do RCL.

Šablony ASP.NET Core předpokládají, že obsah seznamu RCL je ve Areas složce. Prohlédněte si níže rozvržení stránek RCL pro vytvoření RCL, který zpřístupňuje obsah v ~/Pages místo ~/Areas/Pages.

Referenční obsah RCL

Na seznam RCL lze odkazovat pomocí:

Překrytí zobrazení, částečných zobrazení a stránek

Když se v webové aplikaci i v komponentě RCL najde pohled, částečný pohled nebo Razor stránka, má v webové aplikaci přednost značka Razor (.cshtml soubor). Například přidejte WebApp1/Areas/MyFeature/Pages/Page1.cshtml do WebApp1, a Stránka1 ve WebApp1 bude mít přednost před Stránkou1 v RCL.

V ukázkovém stažení přejmenujte WebApp1/Areas/MyFeature2 na WebApp1/Areas/MyFeature a otestujte přednost.

Zkopírujte RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml částečné zobrazení do WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Aktualizujte označení tak, aby naznačovalo nové umístění. Sestavte a spusťte aplikaci, abyste ověřili, že se používá částečná verze aplikace.

Pokud RCL používá Razor stránky, povolte služby a koncové body stránek Razor v hostitelské aplikaci.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Rozložení stránek RCL

Pokud chcete odkazovat na obsah seznamu RCL, jako by byl součástí složky webové aplikace Pages , vytvořte projekt RCL s následující strukturou souborů:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Předpokládejme, že RazorUIClassLib/Pages/Shared obsahuje dva částečné soubory: _Header.cshtml a _Footer.cshtml. Značky <partial> se dají přidat do _Layout.cshtml souboru:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

_ViewStart.cshtml Přidejte soubor do složky projektu Pages RCL pro použití _Layout.cshtml souboru z hostitelské webové aplikace:

@{
    Layout = "_Layout";
}

Vytvořit RCL s statickými prostředky

RCL může vyžadovat doprovodné statické prostředky, na které může odkazovat buď RCL, nebo aplikace, která RCL využívá. ASP.NET Core umožňuje vytvářet seznamy RCLS, které obsahují statické prostředky, které jsou dostupné pro využívání aplikace.

Pokud chcete zahrnout doprovodné prostředky jako součást seznamu RCL, vytvořte wwwroot složku v knihovně tříd a zahrňte do této složky všechny požadované soubory.

Při balení RCL balíku se všechny doprovodné soubory ve složce wwwroot automaticky zahrnou do balíčku.

dotnet pack Místo verze NuGet.exe nuget packpoužijte příkaz .

Vyloučit statická aktiva

Chcete-li vyloučit statické prostředky, přidejte požadovanou cestu vyloučení do $(DefaultItemExcludes) skupiny vlastností v souboru projektu. Oddělte položky středníkem (;).

V následujícím příkladu se šablona stylů lib.css ve složce wwwroot nepovažuje za statický prostředek a není zahrnuta do publikovaného RCL:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integrace TypeScriptu

Zahrnutí souborů TypeScript do balíčku RCL:

  1. Odkazujte na Microsoft.TypeScript.MSBuild balíček NuGet v projektu.

    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.

  2. Umístěte soubory TypeScriptu (.ts) mimo wwwroot složku. Například soubory umístěte do Client složky.

  3. Nakonfigurujte výstup sestavení TypeScriptu pro složku wwwroot. TypescriptOutDir Nastavte vlastnost uvnitř PropertyGroup souboru projektu:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>

  4. Zahrňte cíl TypeScriptu jako závislost PrepareForBuildDependsOn cíle tak, že do PropertyGroup souboru projektu přidáte následující cíl:

    <PrepareForBuildDependsOn>
  CompileTypeScript;
  GetTypeScriptOutputForPublishing;$(PrepareForBuildDependsOn)
</PrepareForBuildDependsOn>

Spotřebovat obsah z odkazovaného RCL

Soubory zahrnuté ve složce wwwroot v RCL jsou vystaveny buď RCL samotné, nebo aplikaci využívající RCL, pod předponou _content/{PACKAGE ID}/. Například knihovna sestavení s názvem Razor.Class.Lib a bez zadaného <PackageId> v souboru projektu vede k cestě ke statickému obsahu na adrese _content/Razor.Class.Lib/. Při vytváření balíčku NuGet a název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu pro {PACKAGE ID}.

Spotřebitelská aplikace odkazuje na statické prostředky poskytované knihovnou se značkami <script>, <style>, <img> a dalšími značkami HTML. Aplikace, která spotřebovává, musí mít povolenou podporu statických souborů:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Když spustíte konzumní aplikaci z výstupu sestavení (dotnet run), ve vývojovém prostředí jsou ve výchozím nastavení povoleny statické webové prostředky. Pokud chcete podporovat prostředky v jiných prostředích při spuštění z výstupu sestavení, zavolejte UseStaticWebAssets tvůrce hostitelů v Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseWebRoot("wwwroot").UseStaticWebAssets();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Poznámka: .NET 6 vyžaduje pouze volání builder.WebHost.UseWebRoot("wwwroot").UseStaticWebAssets. Další informace najdete u tohoto problému na GitHubu.

Volání UseStaticWebAssets se nevyžaduje při spuštění aplikace z publikovaného výstupu (dotnet publish).

Proces vývoje s více projekty

Při spuštění spotřebovávající aplikace:

  • Prostředky v RCL zůstanou v původních složkách. Prostředky se nepřesouvají do spotřebovávající aplikace.
  • Jakákoli změna ve složce RCL wwwroot se projeví v aplikaci, která RCL využívá, po opětovném sestavení RCL a není třeba znovu sestavovat aplikaci, která RCL využívá.

Při sestavení RCL se vytvoří manifest, který popisuje umístění statických webových prostředků. Aplikace používající načte manifest během běhu, aby využila prostředky z odkazovaných projektů a balíčků. Když se do seznamu RCL přidá nový prostředek, musí být seznam RCL znovu sestaven, aby se aktualizoval jeho manifest, aby mohl uživatel získat přístup k novému prostředku.

Publikovat

Při publikování aplikace se doprovodné prostředky ze všech odkazovaných projektů a balíčků zkopírují do wwwroot složky publikované aplikace v části _content/{PACKAGE ID}/. Při vytváření balíčku NuGet a název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu pro {PACKAGE ID} zkoumání wwwroot složky publikovaných prostředků.

Další materiály

Razor zobrazení, stránky, kontrolery, modely stránek, Razor komponenty, komponenty zobrazení a datové modely lze integrovat do Razor knihovny tříd (RCL). RCL lze zabalit a znovu použít. Aplikace můžou zahrnovat RCL a přepsat jeho zobrazení a stránky. Když se ve webové aplikaci i v RCL najde zobrazení, částečné zobrazení nebo Razor stránka, má přednost Razor značka (.cshtml soubor) ve webové aplikaci.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Vytvořte knihovnu tříd obsahující Razor uživatelské rozhraní

  • V sadě Visual Studio vyberte Vytvořit nový projekt.
  • Vyberte Razor knihovnu tříd>Další.
  • Pojmenujte knihovnu (například "RazorClassLib"), >Vytvořte>Další. Aby nedocházelo ke kolizi názvu souboru s vygenerovanou knihovnou zobrazení, ujistěte se, že název knihovny nekončí .Views.
  • Vyberte cílovou architekturu. Zkontrolujte ☑ stránky podpory a zobrazení pro podporu zobrazení. Ve výchozím nastavení se podporují jenom Razor komponenty. Vyberte Vytvořit.

Šablona Razor knihovny tříd (RCL) je ve výchozím nastavení určena pro vývoj Razor komponent. Možnost Podpora stránek a zobrazení podporuje stránky a zobrazení.

Přidejte Razor soubory do RCL.

Šablony ASP.NET Core předpokládají, že obsah seznamu RCL je ve Areas složce. Podívejte se na rozložení stránky RCL a vytvořte RCL, který zpřístupňuje obsah v ~/Pages místo v ~/Areas/Pages.

Referenční obsah RCL

Na seznam RCL lze odkazovat pomocí:

Přizpůsobení zobrazení, částečných zobrazení a stránek

Když se ve webové aplikaci i v RCL najde zobrazení, částečné zobrazení nebo Razor Stránka, Razor označení (.cshtml soubor) ve webové aplikaci má přednost. Například přidání WebApp1/Areas/MyFeature/Pages/Page1.cshtml do WebApp1 a Stránka1 ve WebApp1 bude mít přednost před Stránkou1 v RCL.

Ve vzorovém souboru ke stažení přejmenujte WebApp1/Areas/MyFeature2 na WebApp1/Areas/MyFeature pro otestování precedence.

Zkopírujte RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml částečné zobrazení do WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml složky. Aktualizujte značky, aby označovaly nové umístění. Sestavte a spusťte aplikaci, abyste ověřili, že se používá částečná verze aplikace.

Rozložení stránek RCL

Pokud chcete odkazovat na obsah seznamu RCL, jako by byl součástí složky webové aplikace Pages , vytvořte projekt RCL s následující strukturou souborů:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Předpokládejme, že RazorUIClassLib/Pages/Shared obsahuje dva částečné soubory: _Header.cshtml a _Footer.cshtml. Značky <partial> se dají přidat do _Layout.cshtml souboru:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

_ViewStart.cshtml Přidejte soubor do složky projektu Pages RCL pro použití _Layout.cshtml souboru z hostitelské webové aplikace:

@{
    Layout = "_Layout";
}

Vytvořte RCL se statickými soubory

RCL může vyžadovat doprovodné statické prostředky, na které může odkazovat buď samotné RCL, nebo aplikace využívající RCL. ASP.NET Core umožňuje vytvářet RCL, které obsahují statické zdroje, které jsou dostupné pro použití aplikací.

Pokud chcete zahrnout doprovodné prostředky jako součást seznamu RCL, vytvořte wwwroot složku v knihovně tříd a zahrňte do této složky všechny požadované soubory.

Při balení RCL balíčku se všechny doprovodné prostředky ve složce wwwroot automaticky zahrnují do balíčku.

dotnet pack Místo verze NuGet.exe nuget packpoužijte příkaz .

Vyloučení statických prostředků

Chcete-li vyloučit statické prostředky, přidejte požadovanou cestu vyloučení do $(DefaultItemExcludes) skupiny vlastností v souboru projektu. Oddělte položky středníkem (;).

V následujícím příkladu se lib.css šablona stylů ve složce wwwroot nepovažuje za statický prostředek a není součástí publikovaného RCL.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integrace TypeScriptu

Zahrnutí souborů TypeScript do seznamu RCL:

  1. Odkazujte na Microsoft.TypeScript.MSBuild balíček NuGet v projektu.

    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.

  2. Umístěte soubory TypeScriptu (.ts) mimo wwwroot složku. Například soubory umístěte do Client složky.

  3. Nakonfigurujte výstup sestavení TypeScriptu pro složku wwwroot. TypescriptOutDir Nastavte vlastnost uvnitř PropertyGroup souboru projektu:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>

  4. Zahrňte cíl TypeScriptu jako závislost ResolveCurrentProjectStaticWebAssets cíle tak, že do PropertyGroup souboru projektu přidáte následující cíl:

    <ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
  CompileTypeScript;
  $(ResolveCurrentProjectStaticWebAssetsInputs)
</ResolveCurrentProjectStaticWebAssetsInputsDependsOn>

Používat obsah z odkazovaného RCL

Soubory zahrnuté ve wwwroot složce RCL jsou dostupné buď pro RCL, nebo pro spotřebitelskou aplikaci pod předponou _content/{PACKAGE ID}/. Například knihovna s názvem sestavení Razor.Class.Lib a bez specifikovaného <PackageId> ve svém projektovém souboru vede k cestě ke statickému obsahu na adrese _content/Razor.Class.Lib/. Při vytváření balíčku NuGet a název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu pro {PACKAGE ID}.

Aplikace, která využívá, odkazuje na statické zdroje poskytované knihovnou pomocí značek <script>, <style>, <img> a dalších značek HTML. Aplikace, která tuto funkci využívá, musí mít v Startup.Configurepovolenou podporu statických souborů:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseStaticFiles();

    ...
}

Při spuštění spotřebitelské aplikace z výstupu sestavení (dotnet run) jsou statické webové prostředky ve vývojovém prostředí ve výchozím nastavení povoleny. Pokud chcete podporovat prostředky v jiných prostředích při spuštění z výsledného sestavení, zavolejte UseStaticWebAssets na tvůrce hostitele v Program.cs:

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

Volání UseStaticWebAssets se nevyžaduje při spuštění aplikace z publikovaného výstupu (dotnet publish).

Proces vývoje pro více projektů

Při spuštění aplikace:

  • Prostředky v RCL zůstanou v původních složkách. Majetek není přesouván do spotřební aplikace.
  • Jakákoli změna ve složce RCL wwwroot se projeví ve spotřebovávané aplikaci po přestavení RCL, a to bez nutnosti opětovného sestavení této aplikace.

Při sestavení knihovny RCL se vytvoří manifest, který popisuje umístění statických webových prostředků. Spotřební aplikace načte manifest za běhu, aby využila prostředky z odkazovaných projektů a balíčků. Když se do knihovny RCL přidá nový prostředek, musí být RCL znovu sestavena, aby se aktualizoval její manifest, než může přistupující aplikace získat přístup k novému prostředku.

Publikovat

Při publikování aplikace se doprovodné prostředky ze všech odkazovaných projektů a balíčků zkopírují do wwwroot složky publikované aplikace v části _content/{PACKAGE ID}/. Při vytváření balíčku NuGet a když název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu při zkoumání složky wwwroot pro publikované prostředky.

Další materiály

Razor zobrazení, stránky, kontrolery, modely stránek, Razor komponenty, komponenty zobrazení a datové modely lze integrovat do Razor knihovny tříd (RCL). RCL lze zabalit a znovu použít. Aplikace mohou zahrnovat RCL a přepsat zobrazení a stránky, které RCL obsahuje. Když se ve webové aplikaci i v knihovně RCL najde zobrazení, částečné zobrazení nebo Razor stránka, má přednost Razor značení (.cshtml soubor) ve webové aplikaci.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Vytvořte knihovnu tříd obsahující Razor uživatelské rozhraní

  • V nabídce Soubor Visual Studio vyberte Nový>Projekt.
  • Vyberte ASP.NET Základní webová aplikace.
  • Pojmenujte knihovnu (například RazorClassLib). > Aby nedocházelo ke kolizi názvu souboru s vygenerovanou knihovnou zobrazení, ujistěte se, že název knihovny nekončí .Views.
  • Ověřte, zda je vybrána možnost ASP.NET Core 2.1 nebo novější.
  • Vyberte Razor knihovnu tříd>OK.

Soubor projektu RCL je následující:

<Project Sdk="Microsoft.NET.Sdk.Razor">

    <PropertyGroup>
        <TargetFramework>netcoreapp3.1</TargetFramework>
        <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
    </PropertyGroup>

    <ItemGroup>
        <FrameworkReference Include="Microsoft.AspNetCore.App" />
    </ItemGroup>


</Project>

Přidejte Razor soubory do RCL.

Šablony ASP.NET Core předpokládají, že obsah seznamu RCL je ve Areas složce. Podívejte se na rozložení stránek RCL a vytvořte RCL, který zpřístupňuje obsah v ~/Pages namísto ~/Areas/Pages.

Referenční obsah RCL

Na seznam RCL lze odkazovat pomocí:

Návod: Vytvoření projektu RCL a jeho použití v projektu Pages Razor

Celý projekt si můžete stáhnout a otestovat ho místo jeho vytváření. Ukázkový soubor ke stažení obsahuje další kód a odkazy, které usnadňují testování projektu. Můžete zanechat zpětnou vazbu v této GitHub issue s komentáři ohledně stahování ukázek ve srovnání s podrobnými pokyny.

Otestování aplikace pro stažení

Pokud byste raději vytvořili projekt návodu místo stahování dokončené aplikace, přejděte na další část.

Otevřete soubor .sln v sadě Visual Studio. Spustit aplikaci.

Postupujte podle pokynů v testovací webové aplikaci 1.

Vytvořte RCL

V této části se vytvoří RCL. Razor soubory jsou přidány do RCL.

Vytvořte projekt RCL:

  • V nabídce Soubor sady Visual Studio vyberte Nový>Projekt.
  • Vyberte ASP.NET Základní webová aplikace.
  • Pojmenujte aplikaci RazorUIClassLib>OK.
  • Ověřte, že je vybraná ASP.NET Core 2.1 nebo novější.
  • Vyberte Razor knihovnu tříd>OK.
  • Přidejte částečný Razor soubor zobrazení s názvem RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.

Přidání Razor souborů a složek do projektu

  • Nahraďte kód RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml následujícím kódem:

    <h3>_Message.cshtml partial view.</h3>

<p>RazorUIClassLib\Areas\MyFeature\Pages\Shared\_Message.cshtml</p>

  • Nahraďte kód RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml následujícím kódem:

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

<h2>Hello from a Razor UI class library!</h2>
<p> From  RazorUIClassLib\Areas\MyFeature\Pages\Page1.cshtml</p>

<partial name="_Message" />

    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers je potřeba k použití částečného zobrazení (<partial name="_Message" />). Místo zahrnutí @addTagHelper direktivy můžete přidat _ViewImports.cshtml soubor. Příklad:

    dotnet new viewimports -o RazorUIClassLib/Areas/MyFeature/Pages

    Další informace o _ViewImports.cshtmlimportu sdílených direktiv naleznete v tématu Import sdílených direktiv.

  • Sestavte knihovnu tříd, abyste ověřili, že neexistují žádné chyby kompilátoru:

    dotnet build RazorUIClassLib

Výstup sestavení obsahuje RazorUIClassLib.dll a RazorUIClassLib.Views.dll. RazorUIClassLib.Views.dll obsahuje zkompilovaný Razor obsah.

Použijte knihovnu uživatelského rozhraní z projektu Pages RazorRazor

Razor Vytvořte webovou aplikaci Pages:

  • V Průzkumník řešení klikněte pravým tlačítkem na řešení >Přidat>nový projekt.

  • Vyberte ASP.NET Základní webová aplikace.

  • Pojmenujte webovou aplikaci 1.

  • Ověřte, že je vybrán ASP.NET Core 2.1 nebo novější.

  • Vyberte Webová aplikace>OK.

  • V Průzkumník řešení klikněte pravým tlačítkem na WebApp1 a vyberte Nastavit jako počáteční projekt.

  • V Průzkumník řešení klikněte pravým tlačítkem na WebApp1 a vyberte Sestavit závislosti> projektu.

  • Zkontrolujte RazorUIClassLib jako závislost WebApp1.

  • Z Průzkumníka řešení klikněte pravým tlačítkem na WebApp1 a vyberte Přidat>Odkaz.

  • V dialogovém okně Správce odkazů zkontrolujte RazorUIClassLib a klikněte na OK>.

Spustit aplikaci.

Test webové aplikace 1

Přejděte na /MyFeature/Page1, abyste ověřili, že je knihovna tříd uživatelského rozhraní Razor používána.

Překrytí zobrazení, částečných zobrazení a stránek

Když se zobrazení, částečné zobrazení nebo Razor stránka najde jak ve webové aplikaci, tak v knihovně RCL, bude mít přednost Razor kód (.cshtml soubor) ve webové aplikaci. Například přidání WebApp1/Areas/MyFeature/Pages/Page1.cshtml do Webové aplikace1 způsobí, že Stránka1 v Webové aplikaci1 bude mít přednost před Stránkou1 v RCL.

Ve stažené ukázce přejmenujte WebApp1/Areas/MyFeature2 na WebApp1/Areas/MyFeature pro otestování priority.

Zkopírujte částečné zobrazení z RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml do WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Aktualizujte označení tak, aby označit nové umístění. Sestavte a spusťte aplikaci, abyste ověřili, že se používá verze částečné aplikace.

Rozložení stránek RCL

Pokud chcete odkazovat na obsah seznamu RCL, jako by byl součástí složky webové aplikace Pages , vytvořte projekt RCL s následující strukturou souborů:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Předpokládejme, že RazorUIClassLib/Pages/Shared obsahuje dva částečné soubory: _Header.cshtml a _Footer.cshtml. Značky <partial> se dají přidat do _Layout.cshtml souboru:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Razor zobrazení, stránky, kontrolery, modely stránek, Razor komponenty, komponenty zobrazení a datové modely lze integrovat do Razor knihovny tříd (RCL). RCL lze zabalit a znovu použít. Aplikace můžou obsahovat seznam RCL a přepsat zobrazení a stránky, které obsahuje. Když se ve webové aplikaci i v knihovně RCL najde zobrazení, částečné zobrazení nebo Razor stránka, Razor značka (.cshtml soubor) ve webové aplikaci má přednost.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Vytvořte knihovnu tříd obsahující Razor uživatelské rozhraní

  • V sadě Visual Studio vyberte Vytvořit nový nový projekt.
  • Vyberte Razor knihovnu tříd>Další.
  • Pojmenujte knihovnu (například RazorClassLib), >Vytvořte. Aby nedocházelo ke kolizi názvu souboru s vygenerovanou knihovnou zobrazení, ujistěte se, že název knihovny nekončí .Views.
  • Pokud potřebujete nastavit podporu pro zobrazení, vyberte podpůrné stránky a zobrazení. Ve výchozím nastavení se podporují jenom Razor stránky. Vyberte Vytvořit.

Šablona knihovny tříd (RCL) Razor je ve výchozím nastavení určena pro vývoj komponent Razor. Možnost Podpora stránek a zobrazení podporuje stránky a zobrazení.

Přidejte Razor soubory do RCL.

Šablony ASP.NET Core předpokládají, že obsah seznamu RCL je ve Areas složce. Podívejte se níže na rozložení stránek RCL, abyste vytvořili RCL, který zpřístupňuje obsah v ~/Pages místo ~/Areas/Pages.

Referenční obsah RCL

Na seznam RCL lze odkazovat pomocí:

Přepsání zobrazení, částečných zobrazení a stránek

Když se ve webové aplikaci i v RCL najde zobrazení, částečné zobrazení nebo Razor stránka, Razor značkování (.cshtml soubor) ve webové aplikaci má přednost. Například přidání WebApp1/Areas/MyFeature/Pages/Page1.cshtml do WebApp1 znamená, že Stránka1 v této aplikaci bude mít prioritu před Stránkou1 v RCL.

V ukázkovém stažení přejmenujte WebApp1/Areas/MyFeature2 na WebApp1/Areas/MyFeature pro testování precedence.

Zkopírujte částečné zobrazení RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml do WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Aktualizujte značení tak, aby označovalo nové umístění. Sestavte a spusťte aplikaci, abyste ověřili, že se používá verze části aplikace.

Pokud RCL používá Razor Pages, povolte v hostitelské aplikaci služby a koncové body Razor Pages.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
    services.AddRazorPages();
}

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");

        endpoints.MapRazorPages();
    });
}

Rozložení Stránek RCL

Pokud chcete odkazovat na obsah seznamu RCL, jako by byl součástí složky webové aplikace Pages , vytvořte projekt RCL s následující strukturou souborů:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Předpokládejme, že RazorUIClassLib/Pages/Shared obsahuje dva částečné soubory: _Header.cshtml a _Footer.cshtml. Značky <partial> se dají přidat do _Layout.cshtml souboru:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

_ViewStart.cshtml Přidejte soubor do složky projektu Pages RCL pro použití _Layout.cshtml souboru z hostitelské webové aplikace:

@{
    Layout = "_Layout";
}

Vytvořit RCL se statickými prostředky

RCL může vyžadovat doprovodné statické soubory, na které může odkazovat buď samotné RCL nebo aplikace, které používají RCL. ASP.NET Core umožňuje vytvářet seznamy RCLS, které obsahují statické prostředky, které jsou dostupné pro využívání aplikace.

Pokud chcete zahrnout doprovodné prostředky jako součást seznamu RCL, vytvořte wwwroot složku v knihovně tříd a zahrňte do této složky všechny požadované soubory.

Při balení RCL se všechny doprovodné prostředky ve složce wwwroot automaticky zahrnou do balíčku.

dotnet pack Místo verze NuGet.exe nuget packpoužijte příkaz .

Vyloučit statická aktiva

Chcete-li vyloučit statické prostředky, přidejte požadovanou cestu vyloučení do $(DefaultItemExcludes) skupiny vlastností v souboru projektu. Oddělte položky středníkem (;).

V následujícím příkladu se lib.css šablona stylů ve složce wwwroot nepovažuje za statický prostředek a není součástí publikovaného RCL.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integrace TypeScriptu

Chcete-li zahrnout soubory TypeScript v rámci RCL:

  1. Odkazujte na Microsoft.TypeScript.MSBuild balíček NuGet v projektu.

    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.

  2. Umístěte soubory TypeScriptu (.ts) mimo wwwroot složku. Například soubory umístěte do Client složky.

  3. Nakonfigurujte výstup sestavení TypeScriptu pro složku wwwroot. TypescriptOutDir Nastavte vlastnost uvnitř PropertyGroup souboru projektu:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>

  4. Zahrňte cíl TypeScriptu jako závislost ResolveCurrentProjectStaticWebAssets cíle tak, že do PropertyGroup souboru projektu přidáte následující cíl:

    <ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
  CompileTypeScript;
  $(ResolveCurrentProjectStaticWebAssetsInputs)
</ResolveCurrentProjectStaticWebAssetsInputsDependsOn>

Spotřebovat obsah z odkazovaného RCL

Soubory zahrnuté ve wwwroot složce RCL jsou vystaveny buď RCL, nebo spotřebovávající aplikaci pod předponou _content/{PACKAGE ID}/. Například knihovna sestavení s názvem Razor.Class.Lib a bez zadaného <PackageId> v souboru projektu vede k cestě ke statickému obsahu na adrese _content/Razor.Class.Lib/. Při vytváření balíčku NuGet a název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu pro {PACKAGE ID}.

Spotřebovávající aplikace odkazuje na statické prostředky poskytované knihovnou se značkami <script>, <style> a dalšími značkami, jako je <img> v HTML. Konzumní aplikace musí mít povolenou podporu statických souborů v Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseStaticFiles();

    ...
}

Při spuštění aplikace z výstupu sestavení (dotnet run) jsou ve vývojovém prostředí ve výchozím nastavení povolené statické webové prostředky. Pokud chcete podporovat prostředky v jiných prostředích při spuštění z výstupu sestavení, zavolejte UseStaticWebAssets tvůrce hostitelů v Program.cs:

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

Volání UseStaticWebAssets se nevyžaduje při spuštění aplikace z publikovaného výstupu (dotnet publish).

Víceprojektový vývojový tok

Když běží spotřebovávající aplikace:

  • Prostředky v RCL zůstanou v původních složkách. Prostředky se nepřesouvají do spotřebovávající aplikace.
  • Jakákoli změna ve složce wwwroot RCL se projeví v aplikaci, která používá RCL, po opětovném sestavení RCL, aniž by se spotřebová aplikace musela znovu sestavit.

Když je RCL sestaveno, vytvoří se manifest, který popisuje umístění statických webových prostředků. Konzumentní aplikace načte manifest za běhu programu, aby využila prostředky z odkazovaných projektů a balíčků. Když se do knihovny RCL přidá nový prostředek, musí být knihovna RCL znovu sestavena, aby se aktualizoval její manifest, než k novému prostředku získá přístup spotřební aplikace.

Publikovat

Při publikování aplikace se doprovodné prostředky ze všech odkazovaných projektů a balíčků zkopírují do wwwroot složky publikované aplikace v části _content/{PACKAGE ID}/. Při vytváření balíčku NuGet, pokud název sestavení není stejný jako ID balíčku (<PackageId> v souboru projektu knihovny), použijte ID balíčku, jak je uvedeno v souboru projektu, při zkoumání složky wwwroot publikovaných prostředků.

Další materiály