Herbruikbare gebruikersinterface maken met behulp van het Razor klassebibliotheekproject in ASP.NET Core

Door Rick Anderson

Razor weergaven, pagina's, controllers, paginamodellen, Razor onderdelen, weergaveonderdelenen gegevensmodellen kunnen worden ingebouwd in een Razor klassebibliotheek (RCL). De RCL kan worden verpakt en hergebruikt. Toepassingen kunnen de RCL bevatten en de weergaven en pagina's die deze bevat overschrijven. Wanneer een weergave, gedeeltelijke weergave of Razor pagina wordt gevonden in zowel de web-app als de RCL, heeft de Razor markering (.cshtml bestand) in de web-app voorrang.

Zie Build-clientwebassets voor uw Razor Class Library-voor informatie over het integreren van npm en webpack in het buildproces voor een RCL.

Een klassebibliotheek maken met een Razor-gebruikersinterface

Visual Studio

• Selecteer in Visual Studio Een nieuw project maken.
• Selecteer Razor Klassebibliotheek>Volgende.
• Geef de bibliotheek een naam (bijvoorbeeld 'RazorClassLib'), >Create. Als u een conflict met de gegenereerde weergavebibliotheek wilt voorkomen, moet u ervoor zorgen dat de bibliotheeknaam niet eindigt op .Views.
• Selecteer Ondersteuningspagina's en weergaven als u wilt dat de bibliotheek pagina's en/of weergaven bevat. Standaard worden alleen Razor onderdelen ondersteund. Selecteer maken.

De Razor Class Library-sjabloon is standaard gericht op de ontwikkeling van Razor-componenten. De optie Ondersteuningspagina's en weergaven ondersteunt pagina's en weergaven. Zie voor meer informatie over RCL-ondersteuning in BlazorASP.NET Core Razor-onderdelen gebruiken vanuit een Razor klassebibliotheek (RCL).

.NET CLI

Voer vanaf de opdrachtregel dotnet new razorclasslibuit. Bijvoorbeeld:

dotnet new razorclasslib -o RazorUIClassLib

De sjabloon Classbibliotheek Razor is standaard ingesteld op het ontwikkelen van componenten Razor. Geef de optie --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views) door om ondersteuning te bieden voor pagina's en weergaven.

Voor meer informatie, zie dotnet new. Als u een conflict met de gegenereerde weergavebibliotheek wilt voorkomen, moet u ervoor zorgen dat de bibliotheeknaam niet eindigt op .Views.

Voeg Razor bestanden toe aan de RCL.

Bij de ASP.NET Core-sjablonen wordt ervan uitgegaan dat de RCL-inhoud zich in de map Areas bevindt. Zie indeling van RCL-pagina's hieronder om een RCL te maken waarmee inhoud in ~/Pages wordt weergegeven in plaats van ~/Areas/Pages.

Referentie RCL-inhoud

Er kan naar de RCL worden verwezen door:

• NuGet-pakket. Zie NuGet-pakketten maken en dotnet-pakket toevoegen en Een NuGet-pakket maken en publiceren.
• {ProjectName}.csproj. Zie dotnet-add reference.

Weergaven, gedeeltelijke weergaven en pagina's overschrijven

Wanneer een weergave, gedeeltelijke weergave of Razor pagina wordt gevonden in zowel de web-app als de RCL, heeft de Razor markering (.cshtml bestand) in de web-app voorrang. Voeg bijvoorbeeld WebApp1/Areas/MyFeature/Pages/Page1.cshtml toe aan WebApp1 en Page1 in de WebApp1 heeft voorrang op Page1 in de RCL.

Wijzig in het voorbeelddownload de naam van WebApp1/Areas/MyFeature2 in WebApp1/Areas/MyFeature om de prioriteit te testen.

Kopieer de RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml gedeeltelijke weergave naar WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Werk de markering bij om de nieuwe locatie aan te geven. Bouw en voer de app uit om te verifiëren dat de partiële versie van de app wordt gebruikt.

Als de RCL Razor Pages gebruikt, schakelt u de Razor Pages-services en -eindpunten in de hosting-app in:

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();

Indeling RCL-pagina's

Als u wilt verwijzen naar RCL-inhoud alsof deze deel uitmaakt van de map Pages van de web-app, maakt u het RCL-project met de volgende bestandsstructuur:

• RazorUIClassLib/Pages
• RazorUIClassLib/Pages/Shared

Stel dat RazorUIClassLib/Pages/Shared twee gedeeltelijke bestanden bevat: _Header.cshtml en _Footer.cshtml. De <partial> tags kunnen worden toegevoegd aan _Layout.cshtml bestand:

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

Voeg het _ViewStart.cshtml bestand toe aan de Pages map van het RCL-project om het _Layout.cshtml-bestand te gebruiken vanuit de hostweb-app:

@{
    Layout = "_Layout";
}

Een RCL maken met statische assets

Een RCL kan aanvullende statische onderdelen vereisen waarnaar kan worden verwezen door de RCL of de app die de RCL gebruikt. ASP.NET Core maakt het mogelijk om RCL's te maken die statische assets bevatten die beschikbaar zijn voor een verbruikende app.

Als u aanvullende assets wilt opnemen als onderdeel van een RCL, maakt u een wwwroot map in de klassebibliotheek en neemt u alle vereiste bestanden in die map op.

Wanneer u een RCL inpakt, worden alle bijbehorende assets in de map wwwroot automatisch opgenomen in het pakket.

Gebruik de opdracht dotnet pack in plaats van de NuGet.exe versie nuget pack.

Klantwebresources toevoegen aan het buildproces

Het integreren van clientwebassets in de build-pijplijn is niettrivieel. Zie Clientwebassets bouwen voor uw Razor Class Library voor meer informatie.

Statische assets uitsluiten

Als u statische assets wilt uitsluiten, voegt u het gewenste uitsluitingspad toe aan de $(DefaultItemExcludes) eigenschapsgroep in het projectbestand. Afzonderlijke vermeldingen met een puntkomma (;).

In het volgende voorbeeld wordt de lib.css stylesheet in de map wwwroot niet beschouwd als een statische asset en is deze niet opgenomen in de gepubliceerde RCL.

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

Typescript-integratie

TypeScript-bestanden opnemen in een RCL:

• Voeg het Microsoft.TypeScript.MSBuild NuGet-pakket toe aan het project.

  Notitie

  Zie de artikelen onder Installeren en beheren van pakketten in Pakketverbruikworkflow (NuGet-documentatie)voor hulp bij het toevoegen van pakketten aan .NET-apps. Bevestig de juiste pakketversies op NuGet.org.

• Plaats de TypeScript-bestanden (.ts) buiten de map wwwroot. Plaats de bestanden bijvoorbeeld in een Client map.

• Voeg de volgende markeringen toe aan het projectbestand:

  • Configureer de Build-uitvoer van TypeScript voor de map wwwroot met de eigenschap TypescriptOutDir.
  • Neem het TypeScript-doel op als een afhankelijkheid van het PrepareForBuildDependsOn doel.
  • Verwijder de uitvoer in de wwwroot folder.

<Project Sdk="Microsoft.NET.Sdk.Razor">
  <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>

Inhoud gebruiken van een RCL waarnaar wordt verwezen

De bestanden die zijn opgenomen in de map wwwroot van de RCL worden onder het voorvoegsel _content/{PACKAGE ID}/toegankelijk gemaakt voor de RCL of de gebruikende app. Een bibliotheek met een assemblynaam van Razor.Class.Lib en zonder een <PackageId> die is opgegeven in het projectbestand, resulteert bijvoorbeeld in een pad naar statische inhoud op _content/Razor.Class.Lib/. Wanneer u een NuGet-pakket maakt en de assemblynaam niet hetzelfde is als de pakket-id (<PackageId> in het projectbestand van de bibliotheek), gebruikt u de pakket-id zoals opgegeven in het projectbestand voor {PACKAGE ID}.

De verbruikende app verwijst naar statische assets die door de bibliotheek worden geleverd met <script>, <style>, <img>en andere HTML-tags. De verbruikende app moet ondersteuning voor statische bestanden hebben ingeschakeld in:

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();

Wanneer u de verbruikende app uitvoert vanuit build-uitvoer (dotnet run), worden statische webassets standaard ingeschakeld in de ontwikkelomgeving. Als u assets in andere omgevingen wilt ondersteunen wanneer deze worden uitgevoerd vanuit builduitvoer, roept u UseStaticWebAssets aan op de hostbouwer in 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();

Het aanroepen van UseStaticWebAssets is niet vereist bij het uitvoeren van een app vanuit gepubliceerde uitvoer (dotnet publish).

Ontwikkelingsstroom voor meerdere projecten

Wanneer de verbruikende app wordt uitgevoerd:

• De assets in de RCL blijven in hun oorspronkelijke mappen staan. De assets worden niet verplaatst naar de verbruikende app.
• Elke wijziging in de wwwroot map van de RCL wordt weerspiegeld in de verbruikende app nadat de RCL opnieuw is opgebouwd en zonder de verbruikende app opnieuw te bouwen.

Wanneer de RCL is gebouwd, wordt er een manifest geproduceerd waarin de statische webassetlocaties worden beschreven. De verbruikende app leest het manifest tijdens runtime om de assets te gebruiken uit projecten en pakketten waarnaar wordt verwezen. Wanneer een nieuwe asset wordt toegevoegd aan een RCL, moet de RCL opnieuw worden opgebouwd om het manifest bij te werken voordat een verbruikende app toegang heeft tot de nieuwe asset.

Uitgeven

Wanneer de app wordt gepubliceerd, worden de bijbehorende assets van alle projecten en pakketten waarnaar wordt verwezen, gekopieerd naar de wwwroot map van de gepubliceerde app onder _content/{PACKAGE ID}/. Wanneer u een NuGet-pakket maakt en de assemblynaam niet hetzelfde is als de pakket-id (<PackageId> in het projectbestand van de bibliotheek), gebruikt u de pakket-id zoals opgegeven in het projectbestand voor {PACKAGE ID} bij het controleren van de map wwwroot voor de gepubliceerde assets.

Aanvullende informatiebronnen

• Voorbeeldcode weergeven of downloaden (hoe te downloaden)

• ASP.NET Core Razor-onderdelen uit een Razor klassebibliotheek (RCL) gebruiken

• ASP.NET Core Blazor CSS-isolatie