Verwenden der Angular-Projektvorlage mit ASP.NET Core

  • Artikel

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

Visual Studio bietet Projektvorlagen zum Erstellen von Einzelseiten-Apps (SPAs) basierend auf JavaScript-Frameworks wie Angular, React und Vue mit einem ASP.NET Core-Back-End. Diese Vorlagen:

  • Erstellen eine Visual Studio-Projektmappe mit einem Front-End-Projekt und einem Back-End-Projekt.
  • Verwenden den Visual Studio-Projekttyp für JavaScript und TypeScript (.esproj) für das Front-End.
  • Verwenden ein ASP.NET Core-Projekt für das Back-End.

Projekte, die mit den Visual Studio-Vorlagen erstellt werden, können über die Befehlszeile unter Windows, Linux und macOS ausgeführt werden. Verwenden Sie den Befehl dotnet run --launch-profile https, um das Serverprojekt mit der App auszuführen. Das Ausführen des Serverprojekts startet automatisch den Front-End-Entwicklungsserver für JavaScript. Das https-Startprofil ist derzeit erforderlich.

Visual Studio-Tutorial

Um mit einem Angular-Projekt zu beginnen, folgen Sie dem Tutorial Erstellen einer ASP.NET Core-App mit Angular in der Visual Studio-Dokumentation.

Weitere Informationen finden Sie unter JavaScript und TypeScript in Visual Studio.

ASP.NET Core-SPA-Vorlagen

Visual Studio enthält Vorlagen zum Erstellen ASP.NET Core-Apps mit einem JavaScript- oder TypeScript-Front-End. Diese Vorlagen sind in Visual Studio 2022, Version 17.8 oder höher mit installierter Workload für ASP.NET und Webentwicklung verfügbar.

Die Visual Studio-Vorlagen zum Erstellen ASP.NET Core-Apps mit einem JavaScript- oder TypeScript-Front-End bieten die folgenden Vorteile:

  • Saubere Projekttrennung für das Front-End und das Back-End.
  • Aktuelle Informationen zu den neuesten Front-End-Framework-Versionen.
  • Integration in das neueste Befehlszeilentool für Front-End-Framework, z. B. Vite.
  • Vorlagen für JavaScript und TypeScript (nur TypeScript für Angular).
  • Umfassende JavaScript- und TypeScript-Codebearbeitung.
  • Integration von JavaScript-Buildtools in den .NET-Build.
  • Benutzeroberfläche für npm-Abhängigkeitsverwaltung.
  • Kompatibel mit Visual Studio Code-Debugging- und Startkonfiguration.
  • Ausführen von Front-End-Komponententests im Test-Explorer mithilfe von JavaScript-Testframeworks.

ASP.NET Core-SPA-Vorlagen

Frühere Versionen des .NET SDK enthielten die inzwischen Legacy-Vorlagen zum Erstellen von SPA-Apps mit ASP.NET Core. Eine Dokumentation zu diesen älteren Vorlagen finden Sie in der ASP.NET Core 7.0-Version der SPA-Übersicht sowie in den Angular- und React-Artikeln.

Die aktualisierte Projektvorlage von Angular mit ASP.NET Core stellt einen geeigneten Anfangspunkt für ASP.NET Core-Apps dar, die Angular und die Angular-CLI für die Implementierung einer umfangreichen, clientseitigen Benutzerschnittstelle (User Interface, UI) verwenden.

Mit der Projektvorlage können Sie sowohl ein ASP.NET Core-Projekt, das als Web-API fungieren soll, als auch ein Angular-CLI-Projekt erstellen, das als Benutzerschnittstelle fungieren soll. Diese Projektkombination bietet die Möglichkeit, beide Projekte in einem einzelnen ASP.NET Core-Projekt zu hosten, das als einzelne Einheit erstellt und veröffentlicht werden kann.

Die Projektvorlage ist nicht für serverseitiges Rendering (SSR) vorgesehen.

Erstellen einer neuen App

Erstellen Sie über eine Eingabeaufforderung mit dem Befehl dotnet new angular in einem leeren Verzeichnis ein neues Projekt. Mit den folgenden Befehlen wird die App beispielsweise im Verzeichnis my-new-app erstellt und zu diesem Verzeichnis gewechselt:

dotnet new angular -o my-new-app
cd my-new-app

Führen Sie die App über Visual Studio oder die .NET Core CLI aus:

Öffnen Sie die generierte .csproj-Datei, und führen Sie die App von dort wie gewohnt aus.

Während der Erstellung werden bei der ersten Ausführung npm-Abhängigkeiten wiederhergestellt. Dies kann einige Minuten dauern. Nachfolgende Builds sind wesentlich schneller.

Mit der Projektvorlage werden eine ASP.NET Core-App und eine Angular-App erstellt. Die ASP.NET Core-App ist zur Verwendung für den Datenzugriff, die Autorisierung und weitere serverseitige Belange vorgesehen. Die Angular-App, die sich im Unterverzeichnis ClientApp befindet, ist für sämtliche Belange der Benutzerschnittstelle vorgesehen.

Hinzufügen von Seiten, Images, Formatvorlagen und Modulen

Das Verzeichnis ClientApp enthält eine standardmäßige Angular-CLI-App. Weitere Informationen finden Sie in der offiziellen Angular-Dokumentation.

Die Angular-App, die mit dieser Vorlage erstellt wurde, und die App, die von der Angular-CLI selbst (über ng new) erstellt wurde, unterscheiden sich geringfügig. Die Funktionen der App sind jedoch unverändert. Die mit der Vorlage erstellte App enthält ein auf Bootstrap basiertes Layout und ein Beispiel für grundlegendes Routing.

Ausführen von ng-Befehlen

Wechseln Sie über eine Eingabeaufforderung zum Unterverzeichnis ClientApp:

cd ClientApp

Wenn das ng-Tool global installiert ist, können Sie seine Befehle ausführen. Sie können z.B. ng lint, ng test oder einen beliebigen anderen Angular-CLI-Befehl ausführen. Allerdings muss ng serve nicht ausgeführt werden, da Ihre ASP.NET Core-App den serverseitigen und den clientseitigen Teil Ihrer App bedient. Intern verwendet sie ng serve bei der Entwicklung.

Wenn Sie das ng-Tool nicht installiert haben, führen Sie stattdessen npm run ng aus. Sie können beispielsweise npm run ng lintnpm run ng test ausführen.

NPM-Pakete installieren

Verwenden Sie für die Installation von npm-Paketen von Drittanbietern eine Eingabeaufforderung im Unterverzeichnis ClientApp. Zum Beispiel:

cd ClientApp
npm install <package_name>

Veröffentlichen und Bereitstellen

Bei der Entwicklung wird die App in einem für Entwickler optimierten Modus ausgeführt. JavaScript-Pakete enthalten beispielsweise Quellzuordnungen (damit Sie beim Debuggen Ihren ursprünglichen TypeScript-Code anzeigen können). Die App überwacht TypeScript-, HTML- und CSS-Dateiänderungen auf dem Datenträger und führt bei Feststellung dieser Dateiänderungen automatisch eine Neukompilierung und ein erneutes Laden durch.

Stellen Sie bei der Produktion eine für Leistung optimierte Version Ihrer App bereit. Dies erfolgt gemäß der Konfiguration automatisch. Beim Veröffentlichen gibt die Buildkonfiguration einen verkleinerten, Ahead-of-Time-kompilierten Build (AOT-Build) Ihres clientseitigen Codes aus. Im Gegensatz zum Entwicklungsbuild muss Node.js beim Produktionsbuild nicht auf dem Server installiert sein (sofern Sie das serverseitige Rendern nicht aktiviert haben).

Sie können ASP.NET Core-Standardhosting- und -bereitstellungsmethoden verwenden.

Unabhängiges Ausführen von „ng serve“

Das Projekt ist so konfiguriert, dass die eigene Instanz des Angular-CLI-Servers im Hintergrund gestartet wird, wenn die ASP.NET Core-App im Entwicklungsmodus gestartet wird. Dies ist nützlich, da es bedeutet, dass Sie keinen separaten Server manuell ausführen müssen.

Bei diesem Standardsetup gibt es einen Nachteil. Jedes Mal, wenn Sie Ihren C#-Code ändern und Ihre ASP.NET Core-App neu gestartet werden muss, wird auch der Angular-CLI-Server neu gestartet. Die Sicherung wird nach ca. 10 Sekunden gestartet. Wenn Sie Ihren C#-Code häufig bearbeiten und nicht warten möchten, bis der Angular-CLI-Server neu gestartet wurde, können Sie den Angular-CLI-Server unabhängig vom ASP.NET Core-Prozess extern ausführen.

Um den Angular CLI-Server extern auszuführen, wechseln Sie an einer Eingabeaufforderung zum ClientApp-Unterverzeichnis, und starten Sie den Angular CLI-Entwicklungsserver:

cd ClientApp
npm start

Wenn Sie Ihre ASP.NET Core-App starten, wird kein Angular-CLI-Server gestartet. Stattdessen wird die Instanz verwendet, die Sie manuell gestartet haben. Dadurch kann sie schneller gestartet und neu gestartet werden. Sie müssen also nicht mehr jedes Mal warten, bis Angular-CLI Ihre Client-App neu erstellt hat.

Wenn der Proxy gestartet wird, werden die Ziel-URL und der Port aus den von .NET festgelegten Umgebungsvariablen ASPNETCORE_URLS und ASPNETCORE_HTTPS_PORTS abgeleitet. Um die URLs oder den HTTPS-Port festzulegen, verwenden Sie eine der Umgebungsvariablen, oder ändern Sie den Wert in proxy.conf.json.

Konfigurieren von Proxy-Middleware für SignalR

Weitere Informationen finden Sie unter http-proxy-middleware.

Zusätzliche Ressourcen

Die aktualisierte Angular-Projektvorlage stellt einen geeigneten Anfangspunkt für ASP.NET Core-Apps dar, die Angular und die Angular-CLI für die Implementierung einer umfangreichen, clientseitigen Benutzerschnittstelle (User Interface, UI) verwenden.

Mit der Vorlage können Sie ein ASP.NET Core-Projekt, das als API-Back-End fungieren soll, sowie ein Angular-CLI-Projekt erstellen, das als Benutzerschnittstelle fungieren soll. Die Vorlage bietet den Vorteil, dass beide Projekte in einem App-Projekt gehostet werden können. Folglich kann das App-Projekt als eine einzelne Einheit erstellt und veröffentlicht werden.

Erstellen einer neuen App

Erstellen Sie über eine Eingabeaufforderung mit dem Befehl dotnet new angular in einem leeren Verzeichnis ein neues Projekt. Mit den folgenden Befehlen wird die App beispielsweise im Verzeichnis my-new-app erstellt und zu diesem Verzeichnis gewechselt:

dotnet new angular -o my-new-app
cd my-new-app

Führen Sie die App über Visual Studio oder die .NET Core CLI aus:

Öffnen Sie die generierte .csproj-Datei, und führen Sie die App von dort wie gewohnt aus.

Während der Erstellung werden bei der ersten Ausführung npm-Abhängigkeiten wiederhergestellt. Dies kann einige Minuten dauern. Nachfolgende Builds sind wesentlich schneller.

Mit der Projektvorlage werden eine ASP.NET Core-App und eine Angular-App erstellt. Die ASP.NET Core-App ist zur Verwendung für den Datenzugriff, die Autorisierung und weitere serverseitige Belange vorgesehen. Die Angular-App, die sich im Unterverzeichnis ClientApp befindet, ist für sämtliche Belange der Benutzerschnittstelle vorgesehen.

Hinzufügen von Seiten, Images, Formatvorlagen und Modulen

Das Verzeichnis ClientApp enthält eine standardmäßige Angular-CLI-App. Weitere Informationen finden Sie in der offiziellen Angular-Dokumentation.

Die Angular-App, die mit dieser Vorlage erstellt wurde, und die App, die von der Angular-CLI selbst (über ng new) erstellt wurde, unterscheiden sich geringfügig. Die Funktionen der App sind jedoch unverändert. Die mit der Vorlage erstellte App enthält ein auf Bootstrap basiertes Layout und ein Beispiel für grundlegendes Routing.

Ausführen von ng-Befehlen

Wechseln Sie über eine Eingabeaufforderung zum Unterverzeichnis ClientApp:

cd ClientApp

Wenn das ng-Tool global installiert ist, können Sie seine Befehle ausführen. Sie können z.B. ng lint, ng test oder einen beliebigen anderen Angular-CLI-Befehl ausführen. Allerdings muss ng serve nicht ausgeführt werden, da Ihre ASP.NET Core-App den serverseitigen und den clientseitigen Teil Ihrer App bedient. Intern verwendet sie ng serve bei der Entwicklung.

Wenn Sie das ng-Tool nicht installiert haben, führen Sie stattdessen npm run ng aus. Sie können beispielsweise npm run ng lintnpm run ng test ausführen.

NPM-Pakete installieren

Verwenden Sie für die Installation von npm-Paketen von Drittanbietern eine Eingabeaufforderung im Unterverzeichnis ClientApp. Zum Beispiel:

cd ClientApp
npm install --save <package_name>

Veröffentlichen und Bereitstellen

Bei der Entwicklung wird die App in einem für Entwickler optimierten Modus ausgeführt. JavaScript-Pakete enthalten beispielsweise Quellzuordnungen (damit Sie beim Debuggen Ihren ursprünglichen TypeScript-Code anzeigen können). Die App überwacht TypeScript-, HTML- und CSS-Dateiänderungen auf dem Datenträger und führt bei Feststellung dieser Dateiänderungen automatisch eine Neukompilierung und ein erneutes Laden durch.

Stellen Sie bei der Produktion eine für Leistung optimierte Version Ihrer App bereit. Dies erfolgt gemäß der Konfiguration automatisch. Beim Veröffentlichen gibt die Buildkonfiguration einen verkleinerten, Ahead-of-Time-kompilierten Build (AOT-Build) Ihres clientseitigen Codes aus. Im Gegensatz zum Entwicklungsbuild muss Node.js beim Produktionsbuild nicht auf dem Server installiert sein (sofern Sie das serverseitige Rendern nicht aktiviert haben).

Sie können ASP.NET Core-Standardhosting- und -bereitstellungsmethoden verwenden.

Unabhängiges Ausführen von „ng serve“

Das Projekt ist so konfiguriert, dass die eigene Instanz des Angular-CLI-Servers im Hintergrund gestartet wird, wenn die ASP.NET Core-App im Entwicklungsmodus gestartet wird. Dies ist nützlich, da es bedeutet, dass Sie keinen separaten Server manuell ausführen müssen.

Bei diesem Standardsetup gibt es einen Nachteil. Jedes Mal, wenn Sie Ihren C#-Code ändern und Ihre ASP.NET Core-App neu gestartet werden muss, wird auch der Angular-CLI-Server neu gestartet. Die Sicherung wird nach ca. 10 Sekunden gestartet. Wenn Sie Ihren C#-Code häufig bearbeiten und nicht warten möchten, bis der Angular-CLI-Server neu gestartet wurde, können Sie den Angular-CLI-Server unabhängig vom ASP.NET Core-Prozess extern ausführen. Gehen Sie hierzu wie folgt vor:

  1. Wechseln Sie in einer Eingabeaufforderung zu dem Unterverzeichnis ClientApp, und starten Sie den Angular-CLI-Entwicklungsserver:

    cd ClientApp
npm start

    Wichtig

    Starten Sie den Angular-CLI-Entwicklungsserver mit npm start und nicht mit ng serve, damit die Konfiguration in package.json gewahrt wird. Um zusätzliche Parameter an den Angular-CLI-Server zu übergeben, fügen Sie diese der entsprechenden scripts-Zeile in der Datei package.json hinzu.

  2. Ändern Sie Ihre ASP.NET Core-App so, dass die externe Angular-CLI-Instanz verwendet wird, anstatt eine eigene Instanz zu starten. Ersetzen Sie den spa.UseAngularCliServer-Aufruf in Ihrer Startklasse durch Folgendes:

    spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");

Wenn Sie Ihre ASP.NET Core-App starten, wird kein Angular-CLI-Server gestartet. Stattdessen wird die Instanz verwendet, die Sie manuell gestartet haben. Dadurch kann sie schneller gestartet und neu gestartet werden. Sie müssen also nicht mehr jedes Mal warten, bis Angular-CLI Ihre Client-App neu erstellt hat.

Wenn der Proxy gestartet wird, werden die Ziel-URL und der Port aus den von .NET festgelegten Umgebungsvariablen ASPNETCORE_URLS und ASPNETCORE_HTTPS_PORTS abgeleitet. Um die URLs oder den HTTPS-Port festzulegen, verwenden Sie eine der Umgebungsvariablen, oder ändern Sie den Wert in proxy.conf.json.

Übergeben von Daten aus .NET Code in TypeScript-Code

Während des SSR empfiehlt es sich, per Anforderung Daten aus der ASP.NET Core-App an die Angular-App zu übergeben. Beispielsweise könnten Sie cookieinformationen übergeben oder etwas aus einer Datenbank lesen. Bearbeiten Sie hierzu die Startup-Klasse. Im Rückruf für UseSpaPrerendering legen Sie einen Wert für options.SupplyData fest, z.B.:

options.SupplyData = (context, data) =>
{
    // Creates a new value called isHttpsRequest that's passed to TypeScript code
    data["isHttpsRequest"] = context.Request.IsHttps;
};

Der SupplyData Rückruf lässt Sie beliebige, anforderungsbezogene, JSON-serialisierbare Daten übergeben (z. B. Zeichenfolgen, boolesche Werte oder Zahlen). Ihr Code main.server.ts empfängt diese als params.data. Im vorangehenden Codebeispiel wird z.B. ein boolescher Wert als params.data.isHttpsRequest an den createServerRenderer-Rückruf übergeben. Sie können dies auf eine beliebige Art und Weise, die von Angular unterstützt wird, an andere Teile Ihrer App übergeben. Sehen Sie sich beispielsweise an, wie main.server.ts den Wert BASE_URL an eine beliebige Komponente übergibt, deren Konstruktor für den Empfang deklariert wurde.

Nachteile von SSR

Nicht alle Apps profitieren von SSR. Der Hauptvorteil ist die wahrgenommene Leistung. Besucher, die Ihre App über eine langsame Netzwerkverbindung oder auf langsamen mobilen Geräten erreichen, finden die ursprüngliche UI schnell, auch wenn das Abrufen und Analysieren der JavaScript-Pakete einige Zeit dauert. Allerdings werden viele SPAs hauptsächlich über schnelle, interne Unternehmensnetzwerke auf schnellen Computern verwendet, auf denen die App nahezu umgehend angezeigt wird.

Gleichzeitig hat die Aktivierung von SSR zahlreiche Nachteile. Sie erhöht die Komplexität des Entwicklungsprozesses. Der Code muss in zwei verschiedenen Umgebungen ausgeführt werden: clientseitig und serverseitig (über ASP.NET Core in einer Node.js-Umgebung aufgerufen). Nachfolgend sind einige Dinge aufgeführt, die Sie berücksichtigen sollten:

  • Das SSR erfordert eine Node.js-Installation auf Produktionsservern. Dies ist für einige Bereitstellungsszenarios, wie z.B. Azure App Services, automatisch der Fall, für andere, wie etwa Azure Service Fabric, dagegen nicht.
  • Bei Aktivierung des BuildServerSideRenderer-Buildflags veröffentlicht das node_modules-Verzeichnis. Dieser Ordner enthält mehr als 20.000 Dateien, was die Bereitstellungszeit erhöht.
  • Zum Ausführen von Code in einer Node.js-Umgebung kann nicht davon ausgegangen werden, dass Browser-spezifische JavaScript-APIs, wie z.B. window oder localStorage, vorhanden sind. Wenn Ihr Code (oder eine Bibliothek eines Drittanbieters, auf die Sie verweisen) versucht, diese APIs zu verwenden, erhalten Sie einen Fehler während des SSR. Verwenden Sie beispielsweise jQuery nicht, da es häufig auf Browser-spezifische APIs verweist. Um Fehler auszuschließen, müssen Sie das SSR vermeiden oder aber Browser-spezifische APIs oder Bibliotheken vermeiden. Sie können alle Aufrufe dieser APIs in Überprüfungen einschließen, um sicherzustellen, dass sie nicht während des SSR aufgerufen werden. Verwenden Sie z.B. eine Überprüfung wie die im folgenden JavaScript- oder TypeScript-Code enthaltene:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Konfigurieren von Proxy-Middleware für SignalR

Weitere Informationen finden Sie unter http-proxy-middleware.

Zusätzliche Ressourcen