Verwenden von React 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

Befolgen Sie zunächst das Tutorial Erstellen einer ASP.NET Core-App mit React 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 ASP.NET Core mit React stellt einen geeigneten Anfangspunkt für ASP.NET Core-Apps dar, die React und CRA (Create-React-App) 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 CRA-React-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. Für SSR mit React und Node.js sollten Sie Next.js oder Razzle in Erwägung ziehen.

Erstellen einer neuen App

Erstellen Sie über eine Eingabeaufforderung mit dem Befehl dotnet new react 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 react -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 React-App erstellt. Die ASP.NET Core-App ist für die Verwendung für den Datenzugriff, die Autorisierung und weitere serverseitige Belange vorgesehen. Die React-App, die sich im Unterverzeichnis ClientApp befindet, ist für sämtliche Belange der Benutzeroberfläche vorgesehen.

Hinzufügen von Seiten, Images, Formatvorlagen, Modulen usw.

Das Verzeichnis ClientApp ist eine CRA-React-Standard-App. Weitere Informationen finden Sie in der offiziellen CRA-Dokumentation.

Zwischen der React-App, die mit dieser Vorlage erstellt wurde, und der App, die von CRA selbst erstellt wurde, gibt es jedoch leichte Unterschiede; 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.

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 Quellcode anzeigen können). Die App überwacht JavaScript-, 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, transpilierten Build Ihres clientseitigen Codes aus. Im Gegensatz zum Entwicklungsbuild muss Node.js beim Produktionsbuild nicht auf dem Server installiert sein.

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

Unabhängiges Ausführen des CRA-Servers

Das Projekt ist so konfiguriert, dass die eigene Instanz des CRA-Entwicklungsservers 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 CRA-Server neu gestartet. Es dauert einige Sekunden, bis der Sicherungsvorgang gestartet wird. Wenn Sie Ihren C#-Code häufig bearbeiten und nicht warten möchten, bis der CRA-Server neu gestartet wurde, können Sie den CRA-Server extern ausführen, unabhängig vom ASP.NET Core-Prozess.

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

cd ClientApp
npm start

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

Konfigurieren von Proxy-Middleware für SignalR

Weitere Informationen finden Sie unter http-proxy-middleware.

Zusätzliche Ressourcen

Die aktualisierte React-Projektvorlage stellt einen geeigneten Anfangspunkt für ASP.NET Core-Apps dar, die React und CRA-Konventionen (create-react-app) für die Implementierung einer umfangreichen, clientseitigen Benutzerschnittstelle (User Interface, UI) verwenden.

Mit der Vorlage können ein ASP.NET Core-Projekt, das als API-Back-End fungieren soll, und ein CRA React-Projekt, das als Benutzeroberfläche fungieren soll, erstellt werden. Sie bietet jedoch den Komfort, dass beide Projekte in einem einzigen App-Projekt gehostet werden, das als eine Einheit erstellt und veröffentlicht werden kann.

Die React-Projektvorlage ist nicht für serverseitiges Rendering (SSR) vorgesehen. Für SSR mit React und Node.js sollten Sie Next.js oder Razzle in Erwägung ziehen.

Erstellen einer neuen App

Erstellen Sie über eine Eingabeaufforderung mit dem Befehl dotnet new react 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 react -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 React-App erstellt. Die ASP.NET Core-App ist für die Verwendung für den Datenzugriff, die Autorisierung und weitere serverseitige Belange vorgesehen. Die React-App, die sich im Unterverzeichnis ClientApp befindet, ist für sämtliche Belange der Benutzeroberfläche vorgesehen.

Hinzufügen von Seiten, Images, Formatvorlagen, Modulen usw.

Das Verzeichnis ClientApp ist eine CRA-React-Standard-App. Weitere Informationen finden Sie in der offiziellen CRA-Dokumentation.

Zwischen der React-App, die mit dieser Vorlage erstellt wurde, und der App, die von CRA selbst erstellt wurde, gibt es jedoch leichte Unterschiede; 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.

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 Quellcode anzeigen können). Die App überwacht JavaScript-, 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, transpilierten Build Ihres clientseitigen Codes aus. Im Gegensatz zum Entwicklungsbuild muss Node.js beim Produktionsbuild nicht auf dem Server installiert sein.

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

Unabhängiges Ausführen des CRA-Servers

Das Projekt ist so konfiguriert, dass die eigene Instanz des CRA-Entwicklungsservers 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 CRA-Server neu gestartet. Es dauert einige Sekunden, bis der Sicherungsvorgang gestartet wird. Wenn Sie Ihren C#-Code häufig bearbeiten und nicht warten möchten, bis der CRA-Server neu gestartet wurde, können Sie den CRA-Server extern ausführen, unabhängig vom ASP.NET Core-Prozess. Gehen Sie hierzu wie folgt vor:

  1. Fügen Sie dem Unterverzeichnis .env eine ClientApp-Datei mit der folgenden Einstellung hinzu:

    BROWSER=none

    Dadurch wird verhindert, dass der Webbrowser geöffnet wird, wenn der CRA-Server extern gestartet wird.

  2. Wechseln Sie in einer Eingabeaufforderung zu dem Unterverzeichnis ClientApp, und starten Sie den CRA-Bereitstellungsserver:

    cd ClientApp
npm start

  3. Ändern Sie Ihre ASP.NET Core-App so, dass die externe CRA-Serverinstanz verwendet wird, statt eine eigene Instanz zu starten. Ersetzen Sie den spa.UseReactDevelopmentServer-Aufruf in Ihrer Startklasse durch Folgendes:

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

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

Wichtig

„Serverseitiges Rendering“ ist kein unterstütztes Feature dieser Vorlage. Unser Ziel hinsichtlich dieser Vorlage ist es, die Parität mit „create-react-app“ zu erfüllen. Daher werden Szenarios und Features, die nicht in einem „create-react-app“-Projekt (wie SSR) enthalten sind, nicht unterstützt und stehen als Übung für die Benutzer zur Verfügung.

Konfigurieren von Proxy-Middleware für SignalR

Weitere Informationen finden Sie unter http-proxy-middleware.

Zusätzliche Ressourcen