Delen via

De Angular-projectsjabloon gebruiken met ASP.NET Core

  • Artikel

Notitie

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie de .NET- en .NET Core-ondersteuningsbeleidvoor meer informatie. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikelvoor de huidige release.

Visual Studio biedt projectsjablonen voor het maken van apps met één pagina (SPA's) op basis van JavaScript-frameworks zoals Angular-, Reacten Vue- met een ASP.NET Core-back-end. Deze sjablonen:

  • Maak een Visual Studio-oplossing met een front-endproject en een back-endproject.
  • Gebruik het Visual Studio-projecttype voor JavaScript en TypeScript (.esproj) voor de front-end.
  • Gebruik een ASP.NET Core-project voor de back-end.

Projecten die zijn gemaakt met behulp van de Visual Studio-sjablonen kunnen worden uitgevoerd vanaf de opdrachtregel in Windows, Linux en macOS. Als u de app wilt uitvoeren, gebruikt u dotnet run --launch-profile https om het serverproject uit te voeren. Als u het serverproject uitvoert, wordt de front-end JavaScript-ontwikkelserver automatisch gestart. Het https startprofiel is momenteel vereist.

Visual Studio-zelfstudie

Als u aan de slag wilt met een Angular-project, volgt u de Een ASP.NET Core-app maken met Angular handleiding in de documentatie van Visual Studio.

Zie JavaScript en TypeScript in Visual Studio voor meer informatie

ASP.NET Core SPA-sjablonen

Visual Studio bevat sjablonen voor het bouwen van ASP.NET Core-apps met een JavaScript- of TypeScript-front-end. Deze sjablonen zijn beschikbaar in Visual Studio 2022 versie 17.8 of hoger met de ASP.NET en webontwikkeling workload geïnstalleerd.

De Visual Studio-sjablonen voor het bouwen van ASP.NET Core-apps met een JavaScript- of TypeScript-front-end bieden de volgende voordelen:

  • Schone projectscheiding voor de front-end en back-end.
  • Blijf up-to-date met de nieuwste front-endframeworkversies.
  • Integreer met de nieuwste front-end commandoregelhulpmiddelen van frameworks, zoals Vite.
  • Sjablonen voor zowel JavaScript & TypeScript (alleen TypeScript voor Angular).
  • Uitgebreide bewerkingservaring voor JavaScript- en TypeScript-code.
  • Integreer JavaScript-buildhulpprogramma's met de .NET-build.
  • gebruikersinterface voor npm-afhankelijkheidsbeheer.
  • Compatibel met foutopsporing en startconfiguratie van Visual Studio Code.
  • Voer frontend-eenheidstests uit met Test Explorer met behulp van JavaScript-testframeworks.

Verouderde ASP.NET Core SPA-sjablonen

Eerdere versies van de .NET SDK bevatten sjablonen die nu als verouderd worden beschouwd voor het bouwen van SPA-apps met ASP.NET Core. Zie de ASP.NET Core 7.0-versie van het SPA-overzicht en de artikelen over Angular en React voor documentatie over deze oudere sjablonen.

De ASP.NET Core met Angular-projectsjabloon biedt een handig startpunt voor ASP.NET Core-apps met behulp van Angular en de Angular CLI om een uitgebreide gebruikersinterface (UI) aan de clientzijde te implementeren.

De projectsjabloon is gelijk aan het maken van zowel een ASP.NET Core-project als een web-API en een Angular CLI-project om te fungeren als een gebruikersinterface. Deze projectcombinatie biedt het gemak van het hosten van beide projecten in één ASP.NET Core-project dat als één eenheid kan worden gebouwd en gepubliceerd.

De projectsjabloon is niet bedoeld voor server-side rendering (SSR).

Een nieuwe app maken

Maak een nieuw project vanaf een opdrachtprompt met behulp van de opdracht dotnet new angular in een lege map. Met de volgende opdrachten maakt u de app bijvoorbeeld in een my-new-app map en schakelt u over naar die map:

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

Voer de app uit vanuit Visual Studio of de .NET CLI:

Open het gegenereerde .csproj-bestand en voer de app daar normaal uit.

Het buildproces herstelt npm-afhankelijkheden van de eerste uitvoering, wat enkele minuten kan duren. Volgende builds zijn veel sneller.

Met de projectsjabloon maakt u een ASP.NET Core-app en een Angular-app. De ASP.NET Core-app is bedoeld om te worden gebruikt voor gegevenstoegang, autorisatie en andere problemen aan de serverzijde. De Angular-app, die zich in de submap ClientApp bevindt, is bedoeld om te worden gebruikt voor alle problemen met de gebruikersinterface.

Pagina's, afbeeldingen, stijlen en modules toevoegen

De ClientApp map bevat een standaard Angular CLI-app. Zie de officiële documentatie van Angular voor meer informatie.

Er zijn kleine verschillen tussen de Angular-app die door deze sjabloon is gemaakt en de app die is gemaakt door Angular CLI zelf (via ng new); de mogelijkheden van de app zijn echter ongewijzigd. De app die door de sjabloon is gemaakt, bevat een Bootstrap-gebaseerde indeling en eenbasisrouteringsvoorbeeld.

Ng-opdrachten uitvoeren

Ga in een opdrachtprompt naar de submap ClientApp:

cd ClientApp

Als u het hulpprogramma ng globaal hebt geïnstalleerd, kunt u een van de bijbehorende opdrachten uitvoeren. U kunt bijvoorbeeld ng lint, ng testof een van de andere Angular CLI-opdrachtenuitvoeren. Het is echter niet nodig om ng serve uit te voeren, omdat uw ASP.NET Core-app te maken heeft met zowel server- als clientonderdelen van uw app. Intern gebruikt het ng serve in de ontwikkeling.

Als u het hulpprogramma ng niet hebt geïnstalleerd, voert u in plaats daarvan npm run ng uit. U kunt bijvoorbeeld npm run ng lint of npm run ng testuitvoeren.

NPM-pakketten installeren

Als u npm-pakketten van derden wilt installeren, gebruikt u een opdrachtprompt in de submap ClientApp. Bijvoorbeeld:

cd ClientApp
npm install <package_name>

Publiceren en implementeren

In ontwikkeling wordt de app uitgevoerd in een modus die is geoptimaliseerd voor het gemak van ontwikkelaars. JavaScript-bundels bevatten bijvoorbeeld bronkaarten (zodat u bij foutopsporing de oorspronkelijke TypeScript-code kunt zien). De app controleert op wijzigingen in het TypeScript-, HTML- en CSS-bestand op schijf en wordt automatisch opnieuw gecompileert en opnieuw geladen wanneer deze bestanden worden gewijzigd.

In productie moet u een versie van uw app aanbieden die is geoptimaliseerd voor optimale prestaties. Dit wordt automatisch geconfigureerd. Wanneer u publiceert, genereert de buildconfiguratie een verkleinde, vooraf-gecompileerde build (AoT) van uw clientzijde-code. In tegenstelling tot de ontwikkelingsbuild hoeft de productie-build niet Node.js te worden geïnstalleerd op de server (tenzij u server-side rendering (SSR) hebt ingeschakeld).

U kunt standaard-ASP.NET Core-hosting- en implementatiemethodengebruiken.

'ng serve' onafhankelijk uitvoeren

Het project is geconfigureerd om een eigen exemplaar van de Angular CLI-server op de achtergrond te starten wanneer de ASP.NET Core-app wordt gestart in de ontwikkelmodus. Dit is handig omdat u geen afzonderlijke server handmatig hoeft uit te voeren.

Er is een nadeel van deze standaardinstelling. Telkens wanneer u uw C#-code wijzigt en uw ASP.NET Core-app opnieuw moet worden opgestart, wordt de Angular CLI-server opnieuw opgestart. Er is ongeveer 10 seconden nodig om opnieuw op te starten. Als u regelmatig C#-codebewerkingen uitvoert en niet wilt wachten tot Angular CLI opnieuw wordt opgestart, voert u de Angular CLI-server extern uit, onafhankelijk van het ASP.NET Core-proces.

Als u de Angular CLI-server extern wilt uitvoeren, schakelt u over naar de submap ClientApp in een opdrachtprompt en start u de Angular CLI-ontwikkelserver:

cd ClientApp
npm start

Wanneer u uw ASP.NET Core-app start, wordt er geen Angular CLI-server gestart. Het exemplaar dat u handmatig hebt gestart, wordt in plaats daarvan gebruikt. Hierdoor kan het sneller worden gestart en opnieuw opgestart. Er wordt niet langer gewacht totdat Angular CLI elke keer uw client-app opnieuw bouwt.

Wanneer de proxy wordt gestart, worden de doel-URL en poort afgeleid van de omgevingsvariabelen die zijn ingesteld door .NET, ASPNETCORE_URLS en ASPNETCORE_HTTPS_PORTS. Als u de URL's of HTTPS-poort wilt instellen, gebruikt u een van de omgevingsvariabelen of wijzigt u de waarde in proxy.conf.json.

Proxy-middleware configureren voor SignalR

Zie http-proxy-middlewarevoor meer informatie.

Aanvullende informatiebronnen

De bijgewerkte Angular-projectsjabloon biedt een handig startpunt voor ASP.NET Core-apps met behulp van Angular en de Angular CLI om een uitgebreide gebruikersinterface (UI) aan de clientzijde te implementeren.

De sjabloon is gelijk aan het maken van een ASP.NET Core-project om te fungeren als een API-back-end en een Angular CLI-project om te fungeren als een gebruikersinterface. De sjabloon biedt het gemak van het hosten van beide projecttypen in één app-project. Daarom kan het app-project worden gebouwd en gepubliceerd als één eenheid.

Een nieuwe app maken

Maak een nieuw project vanaf een opdrachtprompt met behulp van de opdracht dotnet new angular in een lege map. Met de volgende opdrachten maakt u de app bijvoorbeeld in een my-new-app map en schakelt u over naar die map:

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

Voer de app uit vanuit Visual Studio of de .NET CLI:

Open het gegenereerde .csproj-bestand en voer de app daar normaal uit.

Het buildproces herstelt npm-afhankelijkheden van de eerste uitvoering, wat enkele minuten kan duren. Volgende builds zijn veel sneller.

Met de projectsjabloon maakt u een ASP.NET Core-app en een Angular-app. De ASP.NET Core-app is bedoeld om te worden gebruikt voor gegevenstoegang, autorisatie en andere problemen aan de serverzijde. De Angular-app, die zich in de submap ClientApp bevindt, is bedoeld om te worden gebruikt voor alle problemen met de gebruikersinterface.

Pagina's, afbeeldingen, stijlen en modules toevoegen

De ClientApp map bevat een standaard Angular CLI-app. Zie de officiële documentatie van Angular voor meer informatie.

Er zijn kleine verschillen tussen de Angular-app die door deze sjabloon is gemaakt en de app die is gemaakt door Angular CLI zelf (via ng new); de mogelijkheden van de app zijn echter ongewijzigd. De app die door de sjabloon is gemaakt, bevat een Bootstrap-indeling-indeling en een eenvoudig routeringsvoorbeeld.

Ng-opdrachten uitvoeren

Ga in een opdrachtprompt naar de submap ClientApp:

cd ClientApp

Als u het hulpprogramma ng globaal hebt geïnstalleerd, kunt u een van de bijbehorende opdrachten uitvoeren. U kunt bijvoorbeeld ng lint, ng testof een van de andere Angular CLI-opdrachtenuitvoeren. Het is echter niet nodig om ng serve uit te voeren, omdat uw ASP.NET Core-app te maken heeft met zowel server- als clientonderdelen van uw app. Intern wordt ng serve gebruikt tijdens de ontwikkeling.

Als u het hulpprogramma ng niet hebt geïnstalleerd, voert u in plaats daarvan npm run ng uit. U kunt bijvoorbeeld npm run ng lint of npm run ng testuitvoeren.

NPM-pakketten installeren

Als u npm-pakketten van derden wilt installeren, gebruikt u een opdrachtprompt in de submap ClientApp. Bijvoorbeeld:

cd ClientApp
npm install --save <package_name>

Publiceren en implementeren

In ontwikkeling wordt de app uitgevoerd in een modus die is geoptimaliseerd voor het gemak van ontwikkelaars. JavaScript-bundels bevatten bijvoorbeeld bronkaarten (zodat u bij foutopsporing de oorspronkelijke TypeScript-code kunt zien). De app controleert op wijzigingen in het TypeScript-, HTML- en CSS-bestand op schijf en wordt automatisch opnieuw gecompileert en opnieuw geladen wanneer deze bestanden worden gewijzigd.

In productie biedt u een versie van uw app aan die geoptimaliseerd is voor prestaties. Dit wordt automatisch geconfigureerd. Wanneer u publiceert, verzendt de buildconfiguratie een minified, vooraf gecompileerde build (AoT) van uw clientcode. In tegenstelling tot de ontwikkelingsbuild hoeft de productie-build niet Node.js te worden geïnstalleerd op de server (tenzij u server-side rendering (SSR) hebt ingeschakeld).

U kunt standaard-ASP.NET Core-hosting- en implementatiemethodengebruiken.

Voer "ng serve" zelfstandig uit

Het project is geconfigureerd om een eigen exemplaar van de Angular CLI-server op de achtergrond te starten wanneer de ASP.NET Core-app wordt gestart in de ontwikkelmodus. Dit is handig omdat u geen afzonderlijke server handmatig hoeft uit te voeren.

Er is een nadeel van deze standaardinstelling. Telkens wanneer u uw C#-code wijzigt en uw ASP.NET Core-app opnieuw moet worden opgestart, wordt de Angular CLI-server opnieuw opgestart. Er is ongeveer 10 seconden nodig om opnieuw op te starten. Als u regelmatig C#-codebewerkingen uitvoert en niet wilt wachten tot Angular CLI opnieuw wordt opgestart, voert u de Angular CLI-server extern uit, onafhankelijk van het ASP.NET Core-proces. Ga hiervoor als volgt te werk:

  1. Ga in een opdrachtprompt naar de submap ClientApp en start de Angular CLI-ontwikkelserver:

    cd ClientApp
npm start

    Belangrijk

    Gebruik npm start om de Angular CLI-ontwikkelserver te starten, niet ng serve, zodat de configuratie in package.json wordt gerespecteerd. Als u extra parameters wilt doorgeven aan de Angular CLI-server, voegt u deze toe aan de relevante scripts regel in uw package.json-bestand.

  2. Wijzig uw ASP.NET Core-app om het externe Angular CLI-exemplaar te gebruiken in plaats van een eigen exemplaar te starten. Vervang in uw Startup-klasse de spa.UseAngularCliServer aanroep door het volgende:

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

Wanneer u uw ASP.NET Core-app start, wordt er geen Angular CLI-server gestart. Het exemplaar dat u handmatig hebt gestart, wordt in plaats daarvan gebruikt. Hierdoor kan het sneller worden gestart en opnieuw opgestart. Er wordt niet langer gewacht totdat Angular CLI elke keer uw client-app opnieuw bouwt.

Wanneer de proxy wordt gestart, worden de doel-URL en poort afgeleid van de omgevingsvariabelen die zijn ingesteld door .NET, ASPNETCORE_URLS en ASPNETCORE_HTTPS_PORTS. Als u de URL's of HTTPS-poort wilt instellen, gebruikt u een van de omgevingsvariabelen of wijzigt u de waarde in proxy.conf.json.

Gegevens van .NET-code doorgeven aan TypeScript-code

Tijdens SSR wilt u mogelijk gegevens per aanvraag doorgeven vanuit uw ASP.NET Core-app in uw Angular-app. U kunt bijvoorbeeld cookie gegevens doorgeven of iets lezen uit een database. U doet dit door uw Startup-klasse te bewerken. Stel in de callback voor UseSpaPrerenderingeen waarde in voor options.SupplyData, zoals:

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

Met de SupplyData callback kunt u willekeurige, per aanvraag, JSON-serialiseerbare gegevens doorgeven (bijvoorbeeld tekenreeksen, booleaanse waarden of getallen). Uw main.server.ts code ontvangt deze als params.data. In het voorgaande codevoorbeeld wordt bijvoorbeeld een booleaanse waarde als params.data.isHttpsRequest doorgegeven aan de createServerRenderer callback. U kunt dit doorgeven aan andere onderdelen van uw app op elke manier die wordt ondersteund door Angular. Zie bijvoorbeeld hoe main.server.ts de BASE_URL waarde doorgeeft aan een onderdeel waarvan de constructor is gedeclareerd om deze te ontvangen.

Nadelen van SSR

Niet alle apps profiteren van SSR. Het belangrijkste voordeel is de waargenomen prestatie. Bezoekers die uw app bereiken via een trage netwerkverbinding of op trage mobiele apparaten, zien de eerste gebruikersinterface snel, zelfs als het even duurt om de JavaScript-bundels op te halen of te parseren. Veel SPA's worden echter voornamelijk gebruikt via snelle, interne bedrijfsnetwerken op snelle computers waar de app vrijwel onmiddellijk wordt weergegeven.

Tegelijkertijd zijn er aanzienlijke nadelen voor het inschakelen van SSR. Het voegt complexiteit toe aan uw ontwikkelingsproces. Uw code moet worden uitgevoerd in twee verschillende omgevingen: clientzijde en serverzijde (in een Node.js omgeving die wordt aangeroepen vanuit ASP.NET Core). Hier volgen enkele dingen om rekening mee te houden:

  • SSR vereist een Node.js installatie op uw productieservers. Dit is automatisch het geval voor sommige implementatiescenario's, zoals Azure App Services, maar niet voor andere, zoals Azure Service Fabric.
  • Als u de BuildServerSideRenderer buildvlag inschakelt, wordt uw node_modules directory gepubliceerd. Deze map bevat meer dan 20.000 bestanden, waardoor de implementatietijd toeneemt.
  • Als u uw code wilt uitvoeren in een Node.js-omgeving, kan deze niet afhankelijk zijn van het bestaan van browserspecifieke JavaScript-API's, zoals window of localStorage. Als uw code (of een bibliotheek van derden waarnaar u verwijst) deze API's probeert te gebruiken, krijgt u een foutmelding tijdens SSR. Gebruik bijvoorbeeld geen jQuery omdat deze op veel plaatsen verwijst naar browserspecifieke API's. Als u fouten wilt voorkomen, moet u SSR vermijden of browserspecifieke API's of bibliotheken voorkomen. U kunt alle aanroepen naar dergelijke API's verpakken in controles om ervoor te zorgen dat ze niet worden aangeroepen tijdens SSR. Gebruik bijvoorbeeld een controle zoals het volgende in JavaScript- of TypeScript-code:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Proxy-middleware configureren voor SignalR

Zie http-proxy-middlewarevoor meer informatie.

Aanvullende informatiebronnen