Erstellen einer wiederverwendbaren Benutzeroberfläche mithilfe eines Razor-Klassenbibliotheksprojekts in ASP.NET Core

Von Rick Anderson

Ansichten, Seiten, Controller, Seitenmodelle, Razor-Komponenten, Anzeigekomponenten und Datenmodelle im Zusammenhang mit Razor können in einer Razor-Klassenbibliothek (Razor Class Library, RCL) zusammengefasst werden. Die RCL kann verpackt und wiederverwendet werden. Sie kann in Anwendungen eingebunden werden, wodurch sich die in der RCL enthaltenen Ansichten und Seiten überschreiben lassen. Wenn eine Ansicht, Teilansicht oder Razor-Seite sowohl in der Web-App als auch in der RCL enthalten ist, hat das Razor-Markup (die .cshtml-Datei) in der Web-App Vorrang.

Weitere Informationen zum Integrieren von npm und webpack in den Buildprozess für eine RCL finden Sie unter Erstellen von Clientwebressourcen für Ihre Razor-Klassenbibliothek.

Erstellen einer Klassenbibliothek, die eine Razor-Benutzeroberfläche enthält

Visual Studio

• Klicken Sie in Visual Studio auf Neues Projekt erstellen.
• Wählen Sie Razor-Klassenbibliothek>Weiter aus.
• Benennen Sie die Bibliothek (z. B. „RazorClassLib“), und klicken Sie auf >Erstellen. Stellen Sie sicher, dass der Bibliotheksname nicht auf .Views endet, um zu verhindern, dass es zu einem Dateinamenkonflikt mit der generierten Ansichtsbibliothek kommt.
• Wählen Sie Supportseiten und Ansichten aus, wenn Sie die Bibliothek benötigen, um Seiten und/oder Ansichten zu enthalten. Standardmäßig werden nur Razor-Komponenten unterstützt. Klicken Sie auf Erstellen.

Die Vorlage der Razor-Klassenbibliothek gilt standardmäßig für die Razor-Komponentenentwicklung. Mit der Option Support pages and views (Seiten und Ansichten unterstützen) werden Seiten und Ansichten unterstützt. Weitere Informationen zum Support für RCLs in Blazor finden Sie unter Nutzen von ASP.NET Core Razor-Komponenten über eine Razor-Klassenbibliothek (RCL).

.NET CLI

Führen Sie dotnet new razorclasslib über die Befehlszeile aus. Zum Beispiel:

dotnet new razorclasslib -o RazorUIClassLib

Die Vorlage der Razor-Klassenbibliothek gilt standardmäßig für die Razor-Komponentenentwicklung. Übergeben Sie die Option --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views), damit Seiten und Ansichten unterstützt werden.

Weitere Informationen finden Sie unter dotnet new. Stellen Sie sicher, dass der Bibliotheksname nicht auf .Views endet, um zu verhindern, dass es zu einem Dateinamenkonflikt mit der generierten Ansichtsbibliothek kommt.

Fügen Sie der RCL Razor-Dateien zu.

Die ASP.NET Core-Vorlagen gehen davon aus, dass die RCL-Inhalte sich im Ordner Areas befinden. Im Abschnitt RCL-Seitenlayout unten wird gezeigt, wie Sie eine RCL erstellen, die Inhalte aus ~/Pages statt aus ~/Areas/Pages verfügbar macht.

Verweisen auf RCL-Inhalte

Folgende Komponenten können auf die RCL verweisen:

• NuGet-Pakete. Weitere Informationen finden Sie unter Creating NuGet packages (Erstellen von NuGet-Paketen), dotnet add package und Erstellen und Veröffentlichen eines NuGet-Pakets.
• {ProjectName}.csproj. Weitere Informationen finden Sie unter dotnet add reference.

Überschreiben von Ansichten, Teilansichten und Seiten

Wenn eine Ansicht, Teilansicht oder Razor Page sowohl in der Web-App als auch in der RCL enthalten ist, hat das Razor-Markup (die .cshtml-Datei) in der Web-App Vorrang. Wenn Sie beispielsweise WebApp1/Areas/MyFeature/Pages/Page1.cshtml zu WebApp1 hinzufügen, hat Page1 in WebApp1 Vorrang vor Page1 in der RCL.

Benennen Sie im Beispieldownload WebApp1/Areas/MyFeature2 in WebApp1/Areas/MyFeature um, um die Rangfolge zu testen.

Kopieren Sie die Teilansicht RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml in WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Aktualisieren Sie das Markup, um den neuen Speicherort anzugeben. Erstellen Sie die App, und führen Sie sie aus, um sicherzustellen, dass die Version mit der Teilansicht der App verwendet wird.

Wenn die RCL Razor Pages verwendet, aktivieren Sie die Razor Pages-Dienste und -Endpunkte in der Hosting-App:

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

RCL-Seitenlayout

Erstellen Sie ein RCL-Projekt mit der folgenden Dateistruktur, um auf RCL-Inhalte so zu verweisen, als seien diese im Ordner Pages der Web-App abgelegt:

• RazorUIClassLib/Pages
• RazorUIClassLib/Pages/Shared

Nehmen Sie an, dass RazorUIClassLib/Pages/Shared zwei Teildateien enthält: _Header.cshtml und _Footer.cshtml. Die <partial>-Tags könnten dann in der Datei _Layout.cshtml hinzugefügt werden:

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

Fügen Sie die Datei _ViewStart.cshtml zum Ordner Pages des RCL-Projekts hinzu, um die Datei _Layout.cshtml über die Host-Web-App zu verwenden:

@{
    Layout = "_Layout";
}

Erstellen einer RCL mit statischen Objekten

Eine RCL kann statische Begleitobjekte erfordern, auf die entweder in der RCL oder in der App, die die RCL verwendet, verwiesen werden kann. ASP.NET Core ermöglicht das Erstellen von RCLs mit statischen Objekten, die verwendenden Apps zur Verfügung stehen.

Wenn Sie Begleitobjekte zu einer RCL hinzufügen möchten, müssen Sie einen Ordner namens wwwroot in der Klassenbibliothek erstellen und alle erforderlichen Dateien in diesem Ordner ablegen.

Beim Packen einer RCL werden alle Begleitobjekte im Ordner wwwroot automatisch in das Paket gepackt.

Verwenden Sie den dotnet pack-Befehl anstelle der NuGet.exe-Version nuget pack.

Hinzufügen von Clientwebressourcen zum Buildprozess

Das Integrieren von Clientwebressourcen in die Buildpipeline ist nicht trivial. Weitere Informationen finden Sie unter Erstellen von Clientwebressourcen für Ihre Razor-Klassenbibliothek.

Ausschließen statischer Objekte

Fügen Sie den gewünschten Ausschlusspfad zur Eigenschaftengruppe $(DefaultItemExcludes) in der Projektdatei hinzu, um statische Objekte auszuschließen. Trennen Sie Einträge durch ein Semikolon (;).

Im folgenden Beispiel wird das Stylesheet lib.css im Ordner wwwroot nicht als statisches Objekt angesehen und nicht in die veröffentlichte RCL aufgenommen:

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

TypeScript-Integration

Gehen Sie wie folgt vor, um TypeScript-Dateien in eine RCL aufzunehmen:

1. Verweisen Sie im Projekt auf das NuGet-Paket Microsoft.TypeScript.MSBuild.

   Hinweis

   Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

2. Speichern Sie die TypeScript-Dateien (.ts) außerhalb des Ordners wwwroot. Legen Sie sie zum Beispiel im Ordner Client ab.

3. Konfigurieren Sie die TypeScript-Buildausgabe für den Ordner wwwroot. Legen Sie die TypescriptOutDir-Eigenschaft in einer Eigenschaftengruppe (PropertyGroup) wie folgt in der Projektdatei fest:

   <TypescriptOutDir>wwwroot</TypescriptOutDir>
   

4. Fügen Sie das TypeScript-Ziel als Abhängigkeit des Ziels PrepareForBuildDependsOn hinzu, indem Sie das folgende Ziel in einer Eigenschaftengruppe (PropertyGroup) in der Projektdatei hinzufügen:

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

Inhalte aus einer RCL, auf die verwiesen wird, verwenden

Die Dateien im Ordner wwwroot der RCL werden entweder für die RCL oder für die verwendende App unter dem Präfix _content/{PACKAGE ID}/ verfügbar gemacht. Beispielsweise führt eine Bibliothek mit dem Assemblynamen Razor.Class.Lib, bei der <PackageId> nicht in der Projektdatei angegeben wird, zu einem Pfad zu statischem Inhalt unter _content/Razor.Class.Lib/. Wenn Sie ein NuGet-Paket erstellen und der Assemblyname nicht mit der Paket-ID identisch ist (<PackageId> in der Projektdatei der Bibliothek), verwenden Sie die in der Projektdatei für {PACKAGE ID} angegebene Paket-ID.

Die verwendende App verweist auf statische Objekte, die von der Bibliothek bereitgestellt werden, mit <script>, <style>, <img> und anderen HTML-Tags. Bei der verarbeitenden App muss statischer Dateisupport aktiviert sein:

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

Beim Ausführen der verwendenden App in der Buildausgabe (dotnet run) sind statische Webobjekte in der Entwicklungsumgebung standardmäßig aktiviert. Wenn beim Ausführen in der Buildausgabe Objekte in anderen Umgebungen unterstützt werden sollen, rufen Sie UseStaticWebAssets im Host-Generator in Program.cs auf:

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

UseStaticWebAssets muss nicht aufgerufen werden, wenn eine App in der veröffentlichten Ausgabe ausgeführt wird (dotnet publish).

Entwicklungsablauf bei mehreren Projekten

Wenn die verwendende App ausgeführt wird:

• bleiben die Objekte in der RCL in ihren ursprünglichen Ordnern. werden die Objekte nicht in die verwendende App verschoben.
• Änderungen im Ordner wwwroot der RCL werden in der verwendenden App abgebildet, sobald die RCL neu erstellt wurde, ohne dass die verwendende App neu erstellt werden muss.

Wenn die RCL erstellt wird, wird ein Manifest erstellt, in dem die Speicherorte der statischen Webobjekte stehen. Die verwendende App liest das Manifest zur Laufzeit, um die Objekte aus den Projekten und Paketen, auf die verwiesen wird, zu verwenden. Wenn ein neues Objekt zu einer RCL hinzugefügt wird, muss die RCL neu erstellt werden, um das Manifest zu aktualisieren, damit verwendende Apps auf das neue Objekt zugreifen können.

Veröffentlichen

Wenn die App veröffentlicht wird, werden die Begleitobjekte aus allen Projekten und Paketen, auf die verwiesen wird, in den Ordner wwwroot der veröffentlichten App unter _content/{PACKAGE ID}/ kopiert. Wenn Sie ein NuGet-Paket erstellen und der Assemblyname nicht mit der Paket-ID identisch ist (<PackageId> in der Projektdatei der Bibliothek), verwenden Sie die in der Projektdatei für {PACKAGE ID} angegebene Paket-ID, wenn Sie den Ordner wwwroot für die veröffentlichten Ressourcen untersuchen.

Zusätzliche Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

• Nutzen von ASP.NET Core Razor-Komponenten über eine Razor-Klassenbibliothek (RCL)

• Blazor CSS-Isolation in ASP.NET Core