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

  • Artikel

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

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

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:

Ü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

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 Razor-Klassenbibliothek finden Sie unter Erstellen von Clientwebressourcen für Ihre Razor-Klassenbibliothek.

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

  • 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.
  • Klicken Sie auf Support pages and views (Seiten und Ansichten unterstützen), wenn Ansichten unterstützt werden sollen. Standardmäßig werden nur Razor-Seiten unterstützt. Wählen Sie Erstellen aus.

Die Vorlage der Razor-Klassenbibliothek (RCL) 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.

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:

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

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

Hinweis: .NET 6 erfordert nur den Aufruf builder.WebHost.UseWebRoot("wwwroot").UseStaticWebAssets. Weitere Informationen finden Sie in diesem GitHub-Issue.

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

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.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

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

  • Wählen Sie in Visual Studio Neues Projekt erstellen aus.
  • Wählen Sie Razor-Klassenbibliothek>Weiter aus.
  • Benennen Sie die Bibliothek (z. B. „RazorClassLib“) und klicken Sie auf >Erstellen>Weiter. 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 das Zielframework aus. Aktivieren Sie ☑ Seiten und Ansichten unterstützen, um Ansichten zu unterstützen. Standardmäßig werden nur Razor-Komponenten unterstützt. Wählen Sie Erstellen aus.

Die Vorlage der Razor-Klassenbibliothek (Razor Class Library, RCL) 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.

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

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

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.

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 ResolveCurrentProjectStaticWebAssets hinzu, indem Sie das folgende Ziel in einer Eigenschaftengruppe (PropertyGroup) in der Projektdatei hinzufügen:

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

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 verwendenden App muss static file support (Unterstützung von statischen Dateien) in Startup.Configure aktiviert sein:

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

    app.UseStaticFiles();

    ...
}

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:

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

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

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.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

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

  • Klicken Sie in Visual Studio im Menü Datei auf Neu>Projekt.
  • Wählen Sie ASP.NET Core-Webanwendung aus.
  • Geben Sie der Bibliothek einen Namen (z.B. „RazorClassLib“) und klicken Sie anschließend auf >OK. Stellen Sie sicher, dass der Bibliotheksname nicht auf .Views endet, um zu verhindern, dass es zu einem Dateinamenkonflikt mit der generierten Ansichtsbibliothek kommt.
  • Überprüfen Sie, ob ASP.NET Core 2.1 oder höher ausgewählt ist.
  • Wählen Sie Razor Klassenbibliothek>OK aus.

Eine RCL verfügt über die folgende Projektdatei:

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

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

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


</Project>

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

Exemplarische Vorgehensweise: Erstellen eines RCL-Projekts und dessen Verwendung in einem Razor Pages-Projekt

Sie können das vollständige Projekt herunterladen und testen, anstatt es zu erstellen. Der Beispieldownload enthält zusätzlichen Code sowie Links, die das Testen des Projekts erleichtern. In diesem GitHub-Issue können Sie in Form von Kommentaren Feedback zu Unterschieden zwischen Beispieldownloads und ausführlichen Anleitungen geben.

Testen der heruntergeladenen App

Wenn Sie die vollständige App nicht heruntergeladen haben und das Beispielprojekt selbst erstellen möchten, können Sie mit dem nächsten Abschnitt fortfahren.

Öffnen Sie die .sln-Datei in Visual Studio. Führen Sie die App aus.

Folgen Sie den Anweisungen in Testen des WebApp1-Projekts.

Erstellen einer RCL

In diesem Abschnitt wird eine RCL erstellt. Dabei werden der RCL Razor-Dateien hinzugefügt.

Erstellen Sie das RCL-Projekt:

  • Klicken Sie in Visual Studio im Menü Datei auf Neu>Projekt.
  • Wählen Sie ASP.NET Core-Webanwendung aus.
  • Geben Sie der App den Namen RazorUIClassLib>OK
  • Überprüfen Sie, ob ASP.NET Core 2.1 oder höher ausgewählt ist.
  • Wählen Sie Razor Klassenbibliothek>OK aus.
  • Fügen Sie die Datei RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml für eine Razor-Teilansicht hinzu.

Hinzufügen von Razor-Dateien und -Ordnern zum Projekt

  • Ersetzen Sie das Markup in RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml durch den folgenden Code:

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

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

  • Ersetzen Sie das Markup in RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml durch den folgenden Code:

    @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 ist erforderlich, um die Teilansicht <partial name="_Message" /> verwenden zu können. Wenn Sie nicht die @addTagHelper-Anweisung einbinden möchten, können Sie die Datei _ViewImports.cshtml hinzufügen. Beispiel:

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

    Weitere Informationen zu _ViewImports.cshtml finden Sie unter Importieren gemeinsam verwendeter Anweisungen.

  • Erstellen Sie die Klassenbibliothek, um sicherzustellen, dass keine Compilerfehler vorliegen:

    dotnet build RazorUIClassLib

Die Buildausgabe enthält RazorUIClassLib.dll und RazorUIClassLib.Views.dll. RazorUIClassLib.Views.dll enthält den kompilierten Razor-Inhalt.

Verwenden der Razor-Benutzeroberflächenbibliothek über ein Razor Pages-Projekt

Erstellen Sie die Razor Pages-Web-App:

  • Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe und anschließend auf >Hinzufügen>Neues Projekt.

  • Wählen Sie ASP.NET Core-Webanwendung aus.

  • Legen Sie als Namen für die App WebApp1 fest.

  • Überprüfen Sie, ob ASP.NET Core 2.1 oder höher ausgewählt ist.

  • Klicken Sie auf Webanwendung>OK.

  • Klicken Sie im Projektmappen-Explorer zuerst mit der rechten Maustaste auf WebApp1 und anschließend auf Als Startprojekt festlegen.

  • Klicken Sie im Projektmappen-Explorer zuerst mit der rechten Maustaste auf WebApp1 und anschließend auf Buildabhängigkeiten>Projektabhängigkeiten.

  • Aktivieren Sie für WebApp1 die Abhängigkeit RazorUIClassLib.

  • Klicken Sie im Projektmappen-Explorer zuerst mit der rechten Maustaste auf WebApp1 und anschließend auf Hinzufügen>Verweis.

  • Aktivieren Sie im Dialogfeld Verweis-Manager das Kontrollkästchen neben RazorUIClassLib, und klicken Sie anschließend auf OK.

Führen Sie die App aus.

Testen des WebApp1-Projekts

Wechseln Sie zu /MyFeature/Page1, um zu überprüfen, ob die Klassenbibliothek der Razor-Benutzeroberfläche verwendet wird.

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

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>

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.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

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

  • 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.
  • Klicken Sie auf Support pages and views (Seiten und Ansichten unterstützen), wenn Ansichten unterstützt werden sollen. Standardmäßig werden nur Razor-Seiten unterstützt. Wählen Sie Erstellen aus.

Die Vorlage der Razor-Klassenbibliothek (Razor Class Library, RCL) 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.

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:

Ü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:

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

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.

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 ResolveCurrentProjectStaticWebAssets hinzu, indem Sie das folgende Ziel in einer Eigenschaftengruppe (PropertyGroup) in der Projektdatei hinzufügen:

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

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 verwendenden App muss static file support (Unterstützung von statischen Dateien) in Startup.Configure aktiviert sein:

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

    app.UseStaticFiles();

    ...
}

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:

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

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