Structure typique du code et du projet

Plus un projet grossit, plus est nécessaire d'avoir de l'ordre une structure solide dans un projet. La raison est fort, simple vous risquez d'introduire des illogismes et ou des incohérences dans votre projet lorsqu'il devra plus gros. Il est vrai que si le but d'un projet est simple d'afficher un «Hello World», il n'est pas nécessaire d'avoir de tel structure, mais les logiciels répondant à des demandes de toute sorte, mettre très vite à l'épreuve une structure mal pensés.

Structure de répertoire

La structure de répertoire d'un projet ASP.NET Core suit généralement une organisation claire et modulaire pour faciliter la gestion du code, la maintenance et le déploiement. À la racine du projet, le répertoire principal contient divers sous-dossiers et fichiers essentiels, tels que global.json pour spécifier la version du .NET SDK utilisée, README.md pour documenter le projet, et .gitignore pour exclure certains fichiers du contrôle de version. Cette structure garantit une meilleure organisation et un repérage rapide des éléments clés du projet.

Les fichiers et répertoires liés aux builds et configurations sont souvent centralisés dans des dossiers spécifiques. Par exemple, .build contient les scripts de construction (build.ps1) et les configurations de déploiement comme azure-pipelines.yml pour Azure DevOps. De plus, .config regroupe les fichiers de configuration locale pour les machines de développement, tandis que artifacts stocke les artefacts générés lors des builds, tels que les binaires ou les journaux. Cette séparation permet de bien distinguer les phases de développement et de déploiement.

Le dossier azure est dédié à l'infrastructure infonuagique et contient des sous-dossiers comme infrastructure pour les scripts de provisionnement et gabarits pour les fichiers ARM/Bicep définissant l'infrastructure Azure. D'autre part, bd regroupe les scripts de construction de la base de données, facilitant ainsi la gestion des migrations et des mises à jour des schémas. Cette organisation est essentielle pour assurer une bonne gouvernance du projet, en particulier lorsqu'il est déployé dans des environnements infonuagique ou hybrides.

La section docs centralise toute la documentation du projet, avec des sous-dossiers pour l'architecture (architecture), l'API (api, pouvant inclure des fichiers Swagger), et les guides d'utilisation (guides). Pour les dépendances externes, le dossier lib contient les bibliothèques non gérées par NuGet, ce qui permet d'éviter des dépendances inutiles dans le code source. Ainsi, la documentation et les dépendances sont bien organisées et facilement accessibles.

Le coeur du projet se trouve dans src, hébergeant le code source de l'application. Ce dossier peut contenir plusieurs sous-projets, comme MyApp.Api pour l'API ASP.NET Core, MonApp.Library pour une bibliothèque réutilisable, et Site pour l'interface utilisateur. Chaque projet suit la structure MVC avec des répertoires Controllers, Models et Views. On y retrouve aussi des fichiers fondamentaux comme Program.cs, servant de point d'entrée, et Startup.cs, configurant l'application (si applicable). Cette organisation modulaire facilite la mise à l'échelle et la réutilisation du code.

Les ressources statiques sont regroupées dans resources, contenant des sous-dossiers pour le CSS (css/site.css), le JavaScript (js/site.js), la localisation (locales), les images (images), et des fichiers de configuration supplémentaires (config). De plus, samples fournit des exemples de code et des preuves de concept (SampleApp), permettant ainsi aux développeurs d'expérimenter avec des implémentations spécifiques sans impacter le projet principal.

Enfin, le dossier tests contient les tests de l'application, avec des sous-dossiers dédiés aux tests unitaires (MyApp.Tests.Unit), aux tests d'intégration (MyApp.Tests.Integration) et aux tests fonctionnels (MyApp.Tests.Functional). De son côté, tools héberge des outils de développement et de migration, y compris des scripts SQL pour les bases de données. Cette séparation des tests et des outils de développement garantit une meilleure qualité du code et simplifie le travail des équipes en charge de la maintenance et du déploiement.

La structure de répertoire typique d'un projet ASP.NET Core bien organisé, incluant des éléments comme la documentation, des API, des pipelines Azure, des scripts, des bibliothèques, des exemples, des tests, des outils, et des ressources, pourrait ressembler à ceci :

Environnement

Dans un projet ASP.NET Core, la variable ASPNETCORE_ENVIRONMENT est essentielle pour gérer la configuration en fonction du contexte d'exécution. Cette variable permet de définir si l'application fonctionne en mode Développement, Staging (préproduction) ou Production. Grâce à cette distinction, l'application peut charger des paramètres spécifiques à chaque environnement, comme les fichiers de configuration appsettings.Development.json, appsettings.Staging.json ou appsettings.Production.json. Ce mécanisme garantit que l'application utilise des réglages adaptés à chaque phase de son cycle de vie.

Le fichier de configuration principal, appsettings.json, contient les paramètres de base, mais il est complété par un fichier spécifique selon la valeur de ASPNETCORE_ENVIRONMENT. Par exemple, en mode Développement, le fichier appsettings.Development.json peut activer des journaux détaillés et un serveur de base de données local, tandis qu'en mode Production, appsettings.Production.json désactivera certaines fonctionnalités comme le Swagger et réduira la verbosité des journaux de bord. Cette flexibilité permet aux développeurs d'adapter leur application aux besoins réels de chaque environnement.

Au-delà des fichiers de configuration, ASPNETCORE_ENVIRONMENT influence également le comportement de l'application dans Program.cs ou Startup.cs. Par exemple, une page d'erreur détaillée (UseDeveloperExceptionPage()) peut être activée uniquement en développement, tandis qu'en production, une page d'erreur générique sera affichée. De même, certains services comme Swagger ou les outils de debugging peuvent être activés uniquement en mode Développement pour éviter toute exposition en production.

La définition de ASPNETCORE_ENVIRONMENT peut se faire de plusieurs manières. Elle peut être spécifiée dans le fichier launchSettings.json de Visual Studio, définie comme une variable d'environnement dans le terminal (export ASPNETCORE_ENVIRONMENT=Production sous Linux, ou $env:ASPNETCORE_ENVIRONMENT="Production" sous Windows), ou encore configurée via IIS ou Kestrel. Cette flexibilité permet d'adapter l'environnement d'exécution sans modifier le code source de l'application.

La gestion des environnements via ASPNETCORE_ENVIRONMENT est un atout majeur d'ASP.NET Core. Elle permet d'adapter automatiquement l'application aux besoins de chaque contexte d'exécution, en ajustant les fichiers de configuration, les services activés et les comportements de sécurité. Cette approche améliore à la fois la sécurité, la mise à l'échelle et la maintenabilité des applications, en facilitant la transition entre les différentes phases du développement et du déploiement.

Structure typique des environnements dans un projet ASP.NET Core

Un projet ASP.NET Core est généralement organisé ainsi :

Impact de ASPNETCORE_ENVIRONMENT sur la configuration

• Chargement conditionnel des fichiers de configuration : Dans Program.cs, ASP.NET Core charge la configuration de base (appsettings.json) et ajoute les fichiers spécifiques à l'environnement en fonction de ASPNETCORE_ENVIRONMENT :
1. var builder = WebApplication.CreateBuilder(args);
2.  
3. builder.Configuration
4.     .SetBasePath(Directory.GetCurrentDirectory())
5.     .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
6.     .AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true, reloadOnChange: true)
7.     .AddEnvironmentVariables();

Si ASPNETCORE_ENVIRONMENT=Development, alors appsettings.Development.json sera chargé en complément de appsettings.json.

• Configuration des journaux de bord en fonction de l'environnement : Le système de journaux de bord peut être configuré différemment selon l'environnement. Par exemple un fichier appsettings.Development.json :
1. {
2.   "Logging": {
3.     "LogLevel": {
4.       "Default": "Debug",
5.       "Microsoft": "Debug",
6.       "Microsoft.Hosting.Lifetime": "Information"
7.     }
8.   }
9. }

Journal de bord réduit pour éviter trop de détails en production (appsettings.Production.json) :

1. {
2.   "Logging": {
3.      "LogLevel": {
4.        "Default": "Warning",
5.        "Microsoft": "Error",
6.        "Microsoft.Hosting.Lifetime": "Information"
7.      }
8.   }
9. }


• Utilisation dans launchSettings.json (Visual Studio) : Dans Visual Studio, launchSettings.json définit ASPNETCORE_ENVIRONMENT pour différents profils :
1. "profiles": {
2.   "IIS Express": {
3.     "commandName": "IISExpress",
4.     "environmentVariables": {
5.       "ASPNETCORE_ENVIRONMENT": "Development"
6.     }
7.   },
8.   "MonProjet": {
9.     "commandName": "Project",
10.     "environmentVariables": {
11.       "ASPNETCORE_ENVIRONMENT": "Development"
12.     }
13.   }
14. }

Ainsi, en lançant l'application en mode IIS Express ou depuis Visual Studio, l'environnement sera automatiquement défini sur Development.

• Gestion des services selon l'environnement : ASP.NET Core permet aussi d'activer certains services uniquement pour un environnement donné. Exemple dans Program.cs :
1. if (builder.Environment.IsDevelopment())
2. {
3.     builder.Services.AddSwaggerGen(); // Active Swagger uniquement en développement
4. }

Autre exemple dans Startup.cs (ASP.NET Core < 6) :

1. public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
2. {
3.     if (env.IsDevelopment())
4.     {
5.         app.UseDeveloperExceptionPage(); // Active la page d'erreur détaillée en développement
6.     }
7.     else
8.     {
9.         app.UseExceptionHandler("/Home/Error"); // Redirige vers une page d'erreur générique
10.     }
11. }

Définir ASPNETCORE_ENVIRONMENT

• Via une variable d'environnement :

Interpréteur de commande	Ligne de commande
Windows (PowerShell)	$env:ASPNETCORE_ENVIRONMENT = "Staging"
Linux/macOS (Bash)	export ASPNETCORE_ENVIRONMENT=Staging



• Via Visual Studio : Modifier launchSettings.json comme vu précédemment.
• Via IIS ou Kestrel :
• Dans IIS, ajouter la variable dans web.config :

<environmentVariables>    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" /> </environmentVariables>



• Dans Kestrel, ajouter la variable dans le fichier systemd (Linux) :

[Service] Environment=ASPNETCORE_ENVIRONMENT=Production