Verwenden der Angular-Projektvorlage mit ASP.NET CoreUse the Angular project template with ASP.NET Core

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.The updated Angular project template provides a convenient starting point for ASP.NET Core apps using Angular and the Angular CLI to implement a rich, client-side user interface (UI).

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.The template is equivalent to creating an ASP.NET Core project to act as an API backend and an Angular CLI project to act as a UI. Die Vorlage bietet den Vorteil, dass beide Projekte in einem App-Projekt gehostet werden können.The template offers the convenience of hosting both project types in a single app project. Folglich kann das App-Projekt als eine einzelne Einheit erstellt und veröffentlicht werden.Consequently, the app project can be built and published as a single unit.

Erstellen einer neuen AppCreate a new app

Wenn ASP.NET Core 2.1 auf Ihrem Computer installiert ist, müssen Sie die Vorlage für Angular-Projekte nicht installieren.If you have ASP.NET Core 2.1 installed, there's no need to install the Angular project template.

Erstellen Sie über eine Eingabeaufforderung mit dem Befehl dotnet new angular in einem leeren Verzeichnis ein neues Projekt.Create a new project from a command prompt using the command dotnet new angular in an empty directory. Mit den folgenden Befehlen wird die App beispielsweise im Verzeichnis my-new-app erstellt und zu diesem Verzeichnis gewechselt:For example, the following commands create the app in a my-new-app directory and switch to that directory:

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:Run the app from either Visual Studio or the .NET Core CLI:

Öffnen Sie die generierte CSPROJ-Datei, und führen Sie die App von dort wie gewohnt aus.Open the generated .csproj file, and run the app as normal from there.

Während der Erstellung werden bei der ersten Ausführung npm-Abhängigkeiten wiederhergestellt. Dies kann einige Minuten dauern.The build process restores npm dependencies on the first run, which can take several minutes. Nachfolgende Builds sind wesentlich schneller.Subsequent builds are much faster.

Mit der Projektvorlage werden eine ASP.NET Core-App und eine Angular-App erstellt.The project template creates an ASP.NET Core app and an Angular app. Die ASP.NET Core-App ist zur Verwendung für den Datenzugriff, die Autorisierung und weitere serverseitige Belange vorgesehen.The ASP.NET Core app is intended to be used for data access, authorization, and other server-side concerns. Die Angular-App, die sich im Unterverzeichnis ClientApp befindet, ist für sämtliche Belange der Benutzerschnittstelle vorgesehen.The Angular app, residing in the ClientApp subdirectory, is intended to be used for all UI concerns.

Hinzufügen von Seiten, Images, Formatvorlagen, Modulen usw.Add pages, images, styles, modules, etc.

Das Verzeichnis ClientApp enthält eine standardmäßige Angular-CLI-App.The ClientApp directory contains a standard Angular CLI app. Weitere Informationen finden Sie in der offiziellen Angular-Dokumentation.See the official Angular documentation for more information.

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.There are slight differences between the Angular app created by this template and the one created by Angular CLI itself (via ng new); however, the app's capabilities are unchanged. Die mit der Vorlage erstellte App enthält ein auf Bootstrap basiertes Layout und ein Beispiel für grundlegendes Routing.The app created by the template contains a Bootstrap-based layout and a basic routing example.

Ausführen von ng-BefehlenRun ng commands

Wechseln Sie über eine Eingabeaufforderung zum Unterverzeichnis ClientApp:In a command prompt, switch to the ClientApp subdirectory:

cd ClientApp

Wenn das ng-Tool global installiert ist, können Sie seine Befehle ausführen.If you have the ng tool installed globally, you can run any of its commands. Sie können z.B. ng lint, ng test oder einen beliebigen anderen Angular-CLI-Befehl ausführen.For example, you can run ng lint, ng test, or any of the other Angular CLI commands. Allerdings muss ng serve nicht ausgeführt werden, da Ihre ASP.NET Core-App den serverseitigen und den clientseitigen Teil Ihrer App bedient.There's no need to run ng serve though, because your ASP.NET Core app deals with serving both server-side and client-side parts of your app. Intern verwendet sie ng serve bei der Entwicklung.Internally, it uses ng serve in development.

Wenn Sie das ng-Tool nicht installiert haben, führen Sie stattdessen npm run ng aus.If you don't have the ng tool installed, run npm run ng instead. Sie können beispielsweise npm run ng lint``npm run ng test ausführen.For example, you can run npm run ng lint or npm run ng test.

NPM-Pakete installierenInstall npm packages

Verwenden Sie für die Installation von npm-Paketen von Drittanbietern eine Eingabeaufforderung im Unterverzeichnis ClientApp.To install third-party npm packages, use a command prompt in the ClientApp subdirectory. Zum Beispiel:For example:

cd ClientApp
npm install --save <package_name>

Veröffentlichen und BereitstellenPublish and deploy

Bei der Entwicklung wird die App in einem für Entwickler optimierten Modus ausgeführt.In development, the app runs in a mode optimized for developer convenience. JavaScript-Pakete enthalten beispielsweise Quellzuordnungen (damit Sie beim Debuggen Ihren ursprünglichen TypeScript-Code anzeigen können).For example, JavaScript bundles include source maps (so that when debugging, you can see your original TypeScript code). 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.The app watches for TypeScript, HTML, and CSS file changes on disk and automatically recompiles and reloads when it sees those files change.

Stellen Sie bei der Produktion eine für Leistung optimierte Version Ihrer App bereit.In production, serve a version of your app that's optimized for performance. Dies erfolgt gemäß der Konfiguration automatisch.This is configured to happen automatically. Beim Veröffentlichen gibt die Buildkonfiguration einen verkleinerten, Ahead-of-Time-kompilierten Build (AOT-Build) Ihres clientseitigen Codes aus.When you publish, the build configuration emits a minified, ahead-of-time (AoT) compiled build of your client-side code. Im Gegensatz zum Entwicklungsbuild muss Node.js beim Produktionsbuild nicht auf dem Server installiert sein (sofern Sie das serverseitige Rendern nicht aktiviert haben).Unlike the development build, the production build doesn't require Node.js to be installed on the server (unless you have enabled server-side rendering (SSR)).

Sie können ASP.NET Core-Standardhosting- und -bereitstellungsmethoden verwenden.You can use standard ASP.NET Core hosting and deployment methods.

Unabhängiges Ausführen von „ng serve“Run "ng serve" independently

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.The project is configured to start its own instance of the Angular CLI server in the background when the ASP.NET Core app starts in development mode. Dies ist nützlich, da es bedeutet, dass Sie keinen separaten Server manuell ausführen müssen.This is convenient because you don't have to run a separate server manually.

Bei diesem Standardsetup gibt es einen Nachteil.There's a drawback to this default setup. 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.Each time you modify your C# code and your ASP.NET Core app needs to restart, the Angular CLI server restarts. Die Sicherung wird nach ca. 10 Sekunden gestartet.Around 10 seconds is required to start back up. 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.If you're making frequent C# code edits and don't want to wait for Angular CLI to restart, run the Angular CLI server externally, independently of the ASP.NET Core process. Gehen Sie hierzu wie folgt vor:To do so:

  1. Wechseln Sie in einer Eingabeaufforderung zu dem Unterverzeichnis ClientApp, und starten Sie den Angular-CLI-Entwicklungsserver:In a command prompt, switch to the ClientApp subdirectory, and launch the Angular CLI development server:

    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.Use npm start to launch the Angular CLI development server, not ng serve, so that the configuration in package.json is respected. 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.To pass additional parameters to the Angular CLI server, add them to the relevant scripts line in your package.json file.

  2. Ändern Sie Ihre ASP.NET Core-App so, dass die externe Angular-CLI-Instanz verwendet wird, anstatt eine eigene Instanz zu starten.Modify your ASP.NET Core app to use the external Angular CLI instance instead of launching one of its own. Ersetzen Sie den spa.UseAngularCliServer-Aufruf in Ihrer Startklasse durch Folgendes:In your Startup class, replace the spa.UseAngularCliServer invocation with the following:

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

Wenn Sie Ihre ASP.NET Core-App starten, wird kein Angular-CLI-Server gestartet.When you start your ASP.NET Core app, it won't launch an Angular CLI server. Stattdessen wird die Instanz verwendet, die Sie manuell gestartet haben.The instance you started manually is used instead. Dadurch kann sie schneller gestartet und neu gestartet werden.This enables it to start and restart faster. Sie müssen also nicht mehr jedes Mal warten, bis Angular-CLI Ihre Client-App neu erstellt hat.It's no longer waiting for Angular CLI to rebuild your client app each time.

Übergeben von Daten aus .NET Code in TypeScript-CodePass data from .NET code into TypeScript code

Während des SSR empfiehlt es sich, per Anforderung Daten aus der ASP.NET Core-App an die Angular-App zu übergeben.During SSR, you might want to pass per-request data from your ASP.NET Core app into your Angular app. Beispielsweise könnten Sie Cookieinformationen übergeben oder etwas aus einer Datenbank lesen.For example, you could pass cookie information or something read from a database. Bearbeiten Sie hierzu die Startup-Klasse.To do this, edit your Startup class. Im Rückruf für UseSpaPrerendering legen Sie einen Wert für options.SupplyData fest, z.B.:In the callback for UseSpaPrerendering, set a value for options.SupplyData such as the following:

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 ermöglicht Ihnen, beliebige JSON-serialisierbare Daten per Anforderung zu übergeben (z.B. Zeichenfolgen, boolesche Werte oder Zahlen).The SupplyData callback lets you pass arbitrary, per-request, JSON-serializable data (for example, strings, booleans, or numbers). Der main.server.ts-Code erhält diese als params.data.Your main.server.ts code receives this as params.data. Im vorangehenden Codebeispiel wird z.B. ein boolescher Wert als params.data.isHttpsRequest an den createServerRenderer-Rückruf übergeben.For example, the preceding code sample passes a boolean value as params.data.isHttpsRequest into the createServerRenderer callback. Sie können dies auf eine beliebige Art und Weise, die von Angular unterstützt wird, an andere Teile Ihrer App übergeben.You can pass this to other parts of your app in any way supported by Angular. Sehen Sie beispielsweise, wie main.server.ts den BASE_URL-Wert an eine beliebige Komponente übergibt, deren Konstruktor für den Empfang deklariert wurde.For example, see how main.server.ts passes the BASE_URL value to any component whose constructor is declared to receive it.

Nachteile von SSRDrawbacks of SSR

Nicht alle Apps profitieren von SSR.Not all apps benefit from SSR. Der Hauptvorteil ist die wahrgenommene Leistung.The primary benefit is perceived performance. 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.Visitors reaching your app over a slow network connection or on slow mobile devices see the initial UI quickly, even if it takes a while to fetch or parse the JavaScript bundles. Allerdings werden viele SPAs hauptsächlich über schnelle, interne Unternehmensnetzwerke auf schnellen Computern verwendet, auf denen die App nahezu umgehend angezeigt wird.However, many SPAs are mainly used over fast, internal company networks on fast computers where the app appears almost instantly.

Gleichzeitig hat die Aktivierung von SSR zahlreiche Nachteile.At the same time, there are significant drawbacks to enabling SSR. Sie erhöht die Komplexität des Entwicklungsprozesses.It adds complexity to your development process. Der Code muss in zwei verschiedenen Umgebungen ausgeführt werden: clientseitig und serverseitig (über ASP.NET Core in einer Node.js-Umgebung aufgerufen).Your code must run in two different environments: client-side and server-side (in a Node.js environment invoked from ASP.NET Core). Nachfolgend sind einige Dinge aufgeführt, die Sie berücksichtigen sollten:Here are some things to bear in mind:

  • Das SSR erfordert eine Node.js-Installation auf Produktionsservern.SSR requires a Node.js installation on your production servers. 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.This is automatically the case for some deployment scenarios, such as Azure App Services, but not for others, such as Azure Service Fabric.

  • Bei Aktivierung des BuildServerSideRenderer-Buildflags veröffentlicht das node_modules-Verzeichnis.Enabling the BuildServerSideRenderer build flag causes your node_modules directory to publish. Dieser Ordner enthält mehr als 20.000 Dateien, was die Bereitstellungszeit erhöht.This folder contains 20,000+ files, which increases deployment time.

  • 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.To run your code in a Node.js environment, it can't rely on the existence of browser-specific JavaScript APIs such as window or localStorage. 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.If your code (or some third-party library you reference) tries to use these APIs, you'll get an error during SSR. Verwenden Sie beispielsweise jQuery nicht, da es häufig auf Browser-spezifische APIs verweist.For example, don't use jQuery because it references browser-specific APIs in many places. Um Fehler auszuschließen, müssen Sie das SSR vermeiden oder aber Browser-spezifische APIs oder Bibliotheken vermeiden.To prevent errors, you must either avoid SSR or avoid browser-specific APIs or libraries. Sie können alle Aufrufe dieser APIs in Überprüfungen einschließen, um sicherzustellen, dass sie nicht während des SSR aufgerufen werden.You can wrap any calls to such APIs in checks to ensure they aren't invoked during SSR. Verwenden Sie z.B. eine Überprüfung wie die im folgenden JavaScript- oder TypeScript-Code enthaltene:For example, use a check such as the following in JavaScript or TypeScript code:

    if (typeof window !== 'undefined') {
        // Call browser-specific APIs here
    }
    

Zusätzliche RessourcenAdditional resources