Utiliser le modèle de projet Angular avec ASP.NET Core

  • Article

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 8 de cet article.

Visual Studio fournit des modèles de projet pour la création d’applications monopages (SPA) basées sur des infrastructures JavaScript telles que Angular, React et Vue qui ont un back-end ASP.NET Core. Ces modèles :

  • Créent une solution Visual Studio avec un projet front-end et un projet back-end.
  • Utilisent le type de projet Visual Studio pour JavaScript et TypeScript (.esproj) pour le front-end.
  • Utilisent un projet ASP.NET Core pour le back-end.

Les projets créés à l’aide des modèles Visual Studio peuvent être exécutés à partir de la ligne de commande sur Windows, Linux et macOS. Pour exécuter l’application, utilisez dotnet run --launch-profile https pour exécuter le projet de serveur. L’exécution du projet de serveur démarre automatiquement le serveur de développement JavaScript frontal. Le profil de lancement https est actuellement requis.

Tutoriel Visual Studio

Pour commencer à utiliser un projet Angular, suivez le tutoriel Créer une application ASP.NET Core avec Angular dans la documentation Visual Studio.

Pour plus d’informations, consultez JavaScript et TypeScript dans Visual Studio

Modèles SPA ASP.NET Core

Visual Studio inclut des modèles de création d’applications ASP.NET Core avec un front-end JavaScript ou TypeScript. Ces modèles sont disponibles dans Visual Studio 2022 version 17.8 ou ultérieure sur laquelle est installée la charge de travail ASP.NET et développement web.

Les modèles Visual Studio de création d’applications ASP.NET Core avec un front-end JavaScript ou TypeScript offrent les avantages suivants :

  • Nettoyer la séparation de projet du front-end et du back-end.
  • Rester à jour des dernières versions de l’infrastructure front-end.
  • Intégrer le dernier outillage de commande en ligne de l’infrastructure front-end, tels que Vite.
  • Modèles pour JavaScript et TypeScript (uniquement TypeScript pour Angular).
  • Expérience de modification de code JavaScript et TypeScript enrichie.
  • Intégrer des outils de génération JavaScript au build .NET.
  • IU de gestion des dépendances npm.
  • Compatible avec le débogage et la configuration de lancement de Visual Studio Code.
  • Exécuter des tests unitaires front-end dans l’Explorateur de tests à l’aide d’infrastructures de tests JavaScript.

Modèles SPA ASP.NET Core hérités

Les versions antérieures du kit de développement logiciel (SDK) .NET incluaient ce que sont désormais des modèles hérités de création d’applications SPA avec ASP.NET Core. Pour obtenir une documentation sur ces modèles plus anciens, consultez la version ASP.NET Core 7.0 de l’Aperçu SPA et les articles Angular et React.

Le modèle de projet ASP.NET Core avec Angular fournit un point de départ pratique pour les applications ASP.NET Core utilisant Angular et la CLI Angular pour implémenter une interface utilisateur (IU) côté client enrichie.

Le modèle de projet est équivalent à la création d’un projet ASP.NET Core en tant qu’API web et d’un projet CLI Angular en tant qu’interface utilisateur. Cette combinaison de projets offre la commodité d’héberger les deux projets dans un seul projet ASP.NET Core qui peut être généré et publié en tant qu’unité unique.

Le modèle de projet n’est pas destiné au rendu côté serveur (SSR).

Créer une application

Créez un projet à partir d’une invite de commandes à l’aide de la commande dotnet new angular dans un répertoire vide. Par exemple, les commandes suivantes créent l’application dans un répertoire my-new-app et basculent vers ce répertoire :

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

Exécutez l’application à partir de Visual Studio ou de CLI .NET Core :

Ouvrez le fichier .csproj généré, puis exécutez l’application normalement à partir de là.

Le processus de génération restaure les dépendances npm à la première exécution, ce qui peut prendre plusieurs minutes. Les générations suivantes sont beaucoup plus rapides.

Le modèle de projet crée une application ASP.NET Core et une application Angular. L’application ASP.NET Core est destinée à être utilisée pour tous les aspects liés au serveur, tels que l’accès aux données et l’autorisation. L’application Angular, qui réside dans le sous-répertoire ClientApp, est destinée à être utilisée pour tout ce qui touche l’interface utilisateur.

Ajouter des pages, des images, des styles et des modules

Le répertoire ClientApp contient une application CLI Angular standard. Pour plus d’informations, consultez la documentation Angular officielle.

Il existe de légères différences entre l’application Angular créée par ce modèle et celle créée par la CLI Angular (via ng new) ; toutefois, les fonctionnalités de l’application sont identiques. L’application créée par le modèle contient une mise en page basée sur Bootstrap et un exemple de routage de base.

Exécuter des commandes ng

Dans une invite de commandes, basculez vers le sous-répertoire ClientApp :

cd ClientApp

Si l’outil ng est installé de manière globale, vous pouvez exécuter n’importe laquelle de ses commandes. Par exemple, vous pouvez exécuter ng lint, ng test ou toute autre commande CLI Angular. Mais il est inutile d’exécuter ng serve, car votre application ASP.NET Core se charge de traiter les parties côté serveur et côté client de votre application. En interne, elle utilise ng serve dans le développement.

Si l’outil ng n’est pas installé, exécutez npm run ng à la place. Par exemple, vous pouvez exécuter npm run ng lint ou npm run ng test.

Installer les packages npm

Pour installer des packages npm tiers, utilisez une invite de commandes dans le sous-répertoire ClientApp. Par exemple :

cd ClientApp
npm install <package_name>

Publier et déployer

Pendant le développement, l’application s’exécute en mode optimisé pour des raisons pratiques. Par exemple, les bundles JavaScript incluent des mappages de sources (ce qui vous permet de voir votre code TypeScript d’origine pendant le débogage). L’application se recompile et se recharge automatiquement en cas de modification des fichiers TypeScript, HTML et CSS sur le disque.

Dans un environnement de production, fournissez une version de votre application qui est optimisée pour les performances. Ce comportement est configuré pour se produire automatiquement. Quand vous publiez, la configuration de build émet une build compilée AoT (Ahead-of-Time) réduite de votre code côté client. Contrairement à la build de développement, la build de production ne requiert pas que Node.js soit installé sur le serveur (sauf si vous avez activé le rendu côté serveur).

Vous pouvez utiliser des méthodes d’hébergement et de déploiement ASP.NET Core standard.

Exécuter « ng serve » indépendamment

Le projet est configuré pour démarrer sa propre instance du serveur CLI Angular en arrière-plan quand l’application ASP.NET Core démarre en mode de développement. Ainsi, vous n’êtes pas obligé d’exécuter un serveur distinct manuellement.

Cette configuration par défaut présente un inconvénient. Chaque fois que vous modifiez votre code C# et que votre application ASP.NET Core doit redémarrer, le serveur CLI Angular redémarre. Environ 10 secondes sont requises pour démarrer la sauvegarde. Si vous apportez des modifications fréquentes au code C# et que vous ne souhaitez pas attendre que la CLI Angular redémarre, exécutez le serveur CLI Angular en externe, indépendamment du processus ASP.NET Core.

Pour exécuter le serveur CLI Angular en externe, basculez vers le sous-répertoire ClientApp dans une invite de commandes et lancez le serveur de développement de CLI Angular :

cd ClientApp
npm start

Quand vous démarrez votre application ASP.NET Core, elle ne lance pas un serveur CLI Angular. L’instance que vous avez démarrée manuellement est utilisée à la place. Cela lui permet de démarrer et de redémarrer plus rapidement. Elle n’attend plus que votre CLI Angular regénère votre application cliente à chaque fois.

Lorsque le proxy est lancé, l’URL et le port cible sont déduits à partir des variables d’environnement définies par .NET, ASPNETCORE_URLS et ASPNETCORE_HTTPS_PORTS. Pour définir les URL ou le port HTTPS, utilisez l’une des variables d’environnement ou modifiez la valeur dans proxy.conf.json.

Configurer l’intergiciel de proxy pour SignalR

Pour plus d’informations, consultez http-proxy-middleware.

Ressources supplémentaires

Le modèle de projet Angular mis à jour fournit un point de départ pratique pour les applications ASP.NET Core utilisant Angular et la CLI Angular pour implémenter une interface utilisateur (IU) côté client enrichie.

Le modèle est équivalent à la création d’un projet ASP.NET Core en tant que back-end d’API et d’un projet CLI Angular en tant qu’interface utilisateur. Le modèle offre l’avantage d’héberger les deux types de projets dans un projet d’application unique. Par conséquent, le projet d’application peut être généré et publié sous la forme d’une unité unique.

Créer une application

Créez un projet à partir d’une invite de commandes à l’aide de la commande dotnet new angular dans un répertoire vide. Par exemple, les commandes suivantes créent l’application dans un répertoire my-new-app et basculent vers ce répertoire :

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

Exécutez l’application à partir de Visual Studio ou de CLI .NET Core :

Ouvrez le fichier .csproj généré, puis exécutez l’application normalement à partir de là.

Le processus de génération restaure les dépendances npm à la première exécution, ce qui peut prendre plusieurs minutes. Les générations suivantes sont beaucoup plus rapides.

Le modèle de projet crée une application ASP.NET Core et une application Angular. L’application ASP.NET Core est destinée à être utilisée pour tous les aspects liés au serveur, tels que l’accès aux données et l’autorisation. L’application Angular, qui réside dans le sous-répertoire ClientApp, est destinée à être utilisée pour tout ce qui touche l’interface utilisateur.

Ajouter des pages, des images, des styles et des modules

Le répertoire ClientApp contient une application CLI Angular standard. Pour plus d’informations, consultez la documentation Angular officielle.

Il existe de légères différences entre l’application Angular créée par ce modèle et celle créée par la CLI Angular (via ng new) ; toutefois, les fonctionnalités de l’application sont identiques. L’application créée par le modèle contient une mise en page basée sur Bootstrap et un exemple de routage de base.

Exécuter des commandes ng

Dans une invite de commandes, basculez vers le sous-répertoire ClientApp :

cd ClientApp

Si l’outil ng est installé de manière globale, vous pouvez exécuter n’importe laquelle de ses commandes. Par exemple, vous pouvez exécuter ng lint, ng test ou toute autre commande CLI Angular. Mais il est inutile d’exécuter ng serve, car votre application ASP.NET Core se charge de traiter les parties côté serveur et côté client de votre application. En interne, elle utilise ng serve dans le développement.

Si l’outil ng n’est pas installé, exécutez npm run ng à la place. Par exemple, vous pouvez exécuter npm run ng lint ou npm run ng test.

Installer les packages npm

Pour installer des packages npm tiers, utilisez une invite de commandes dans le sous-répertoire ClientApp. Par exemple :

cd ClientApp
npm install --save <package_name>

Publier et déployer

Pendant le développement, l’application s’exécute en mode optimisé pour des raisons pratiques. Par exemple, les bundles JavaScript incluent des mappages de sources (ce qui vous permet de voir votre code TypeScript d’origine pendant le débogage). L’application se recompile et se recharge automatiquement en cas de modification des fichiers TypeScript, HTML et CSS sur le disque.

Dans un environnement de production, fournissez une version de votre application qui est optimisée pour les performances. Ce comportement est configuré pour se produire automatiquement. Quand vous publiez, la configuration de build émet une build compilée AoT (Ahead-of-Time) réduite de votre code côté client. Contrairement à la build de développement, la build de production ne requiert pas que Node.js soit installé sur le serveur (sauf si vous avez activé le rendu côté serveur).

Vous pouvez utiliser des méthodes d’hébergement et de déploiement ASP.NET Core standard.

Exécuter « ng serve » indépendamment

Le projet est configuré pour démarrer sa propre instance du serveur CLI Angular en arrière-plan quand l’application ASP.NET Core démarre en mode de développement. Ainsi, vous n’êtes pas obligé d’exécuter un serveur distinct manuellement.

Cette configuration par défaut présente un inconvénient. Chaque fois que vous modifiez votre code C# et que votre application ASP.NET Core doit redémarrer, le serveur CLI Angular redémarre. Environ 10 secondes sont requises pour démarrer la sauvegarde. Si vous apportez des modifications fréquentes au code C# et que vous ne souhaitez pas attendre que la CLI Angular redémarre, exécutez le serveur CLI Angular en externe, indépendamment du processus ASP.NET Core. Pour cela :

  1. Dans une invite de commandes, basculez vers le sous-répertoire ClientApp et lancez le serveur de développement CLI Angular :

    cd ClientApp
npm start

    Important

    Utilisez npm start pour lancer le serveur de développement CLI Angular, et non ng serve, de sorte que la configuration dans package.json soit respectée. Pour transmettre des paramètres supplémentaires au serveur CLI Angular, ajoutez-les à la ligne scripts pertinente dans votre fichier package.json.

  2. Modifiez votre application ASP.NET Core afin qu’elle utilise l’instance CLI Angular externe au lieu de lancer une instance propre. Dans votre classe Startup, remplacez l’appel spa.UseAngularCliServer par ce qui suit :

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

Quand vous démarrez votre application ASP.NET Core, elle ne lance pas un serveur CLI Angular. L’instance que vous avez démarrée manuellement est utilisée à la place. Cela lui permet de démarrer et de redémarrer plus rapidement. Elle n’attend plus que votre CLI Angular regénère votre application cliente à chaque fois.

Lorsque le proxy est lancé, l’URL et le port cible sont déduits à partir des variables d’environnement définies par .NET, ASPNETCORE_URLS et ASPNETCORE_HTTPS_PORTS. Pour définir les URL ou le port HTTPS, utilisez l’une des variables d’environnement ou modifiez la valeur dans proxy.conf.json.

Transmettre des données à partir du code .NET dans le code TypeScript

Au cours du rendu côté serveur (SSR), vous pouvez souhaiter transmettre des données par requête à partir de votre application ASP.NET Core dans votre application Angular. Par exemple, vous pouvez transmettre des informations sur cookie ou un élément lu dans une base de données. Pour ce faire, modifiez votre classe Démarrer. Dans le rappel pour UseSpaPrerendering, définissez une valeur pour options.SupplyData telle que la suivante :

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

Le rappel SupplyData vous permet de transmettre des données sérialisables JSON, arbitraires, par requête (par exemple, chaînes, valeurs booléennes ou nombres). Votre code main.server.ts reçoit cette opération en tant que params.data. Ainsi, l’exemple de code précédent transmet une valeur booléenne en tant que params.data.isHttpsRequest dans le rappel createServerRenderer. Vous pouvez transmettre ceci à d’autres parties de votre application prises en charge par Angular. Par exemple, consultez la façon dont main.server.ts transmet la valeur BASE_URL à un composant dont le constructeur est déclaré pour le recevoir.

Inconvénients du SSR

Toutes les applications ne bénéficient pas du rendu côté serveur (SSR). Le principal avantage concerne les performances. Les visiteurs consultant votre application via une connexion réseau lente ou sur des appareils mobiles lents voient l’interface utilisateur initiale rapidement, même si l’extraction ou l’analyse des bundles JavaScript prend du temps. Toutefois, de nombreuses applications monopage sont principalement utilisées via des réseaux d’entreprise internes rapides sur des ordinateurs rapides où l’application s’affiche presque instantanément.

En même temps, il existe des inconvénients importants concernant l’activation du SSR. Il ajoute une complexité au processus de développement. Votre code doit s’exécuter dans deux environnements différents : côté client et côté serveur (dans un environnement Node.js appelé à partir d’ASP.NET Core). Voici quelques éléments à prendre en compte :

  • Le SSR requiert une installation Node.js sur vos serveurs de production. C’est automatiquement le cas pour certains scénarios de déploiement, comme Azure App Services, mais pas pour d’autres, comme Azure Service Fabric.
  • L’activation de l’indicateur de génération BuildServerSideRenderer entraîne votre répertoire node_modules à publier. Ce dossier contient plus de 20 000 fichiers, ce qui allonge le temps de déploiement.
  • Pour exécuter votre code dans un environnement Node.js, il ne peut pas s’appuyer sur l’existence d’API JavaScript spécifiques à un navigateur comme window ou localStorage. Si votre code (ou une bibliothèque tierce que vous référencez) tente d’utiliser ces API, vous obtiendrez une erreur au cours du SSR. Par exemple, n’utilisez pas jQuery, car il fait référence à des API spécifiques au navigateur dans de nombreux endroits. Pour éviter les erreurs, vous devez éviter le SSR ou éviter les bibliothèques ou les API spécifiques au navigateur. Vous pouvez encapsuler tous les appels à ces API dans des vérifications pour vous assurer qu’ils ne sont pas appelés au cours du SSR. Par exemple, utilisez une vérification telle que la suivante dans le code JavaScript ou TypeScript :
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Configurer l’intergiciel de proxy pour SignalR

Pour plus d’informations, consultez http-proxy-middleware.

Ressources supplémentaires