Utiliser plusieurs environnements dans ASP.NET Core

Par Rick Anderson et Kirk Larkin

ASP.NET Core configure le comportement de l’application en fonction de l’environnement d’exécution à l’aide d’une variable d’environnement.

Pour obtenir des instructions sur les environnements Blazor, en complément ou en remplacement des instructions de cet article, consultez Environnements Blazor ASP.NET Core.

Environnements

Pour déterminer l’environnement d’exécution, ASP.NET Core lit à partir des variables d’environnement suivantes :

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT lorsque la méthode WebApplication.CreateBuilder est appelée. Les modèles d’application web par défaut ASP.NET Core appellent WebApplication.CreateBuilder. La valeur DOTNET_ENVIRONMENT remplace ASPNETCORE_ENVIRONMENT quand WebApplicationBuilder est utilisé. Pour les autres hôtes, tels que ConfigureWebHostDefaults et WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT est prioritaire.

IHostEnvironment.EnvironmentName peut être défini sur n’importe quelle valeur, mais les valeurs suivantes sont fournies par l’infrastructure :

• Development: Le fichier launchSettings.json définit ASPNETCORE_ENVIRONMENT sur Development sur l’ordinateur local.
• Staging
• Production: La valeur par défaut si DOTNET_ENVIRONMENT et ASPNETCORE_ENVIRONMENT n’ont pas été définis.

Le code suivant :

• Est similaire au code généré par les modèles ASP.NET Core.
• Active la page d’exception du développeur lorsque ASPNETCORE_ENVIRONMENT est défini sur Development. Cette opération est effectuée automatiquement par la méthode WebApplication.CreateBuilder.
• Appelle UseExceptionHandler lorsque la valeur de ASPNETCORE_ENVIRONMENT est autre que Development.
• Fournit une instance IWebHostEnvironment dans la propriété Environment de WebApplication.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Le Tag helper d’environnement utilise la valeur de la propriété IHostEnvironment.EnvironmentName pour inclure ou exclure le balisage dans l’élément :

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

La page À propos de l’échantillon de code inclut le balisage précédent et affiche la valeur de IWebHostEnvironment.EnvironmentName.

Sur Windows et macOS, les valeurs et les variables d’environnement ne respectent pas la casse. Les valeurs et les variables d’environnement Linux respectent la casse par défaut.

Créer des échantillons d’environnements

L’échantillon de code utilisé dans cet article est basé sur un projet Pages Razor nommé EnvironmentsSample.

Les commandes CLI .NET suivantes créent et exécutent une application web nommée EnvironmentsSample :

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

Lorsque vous exécutez l’application, elle affiche une sortie similaire à ce qui suit :

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Définir l’environnement sur la ligne de commande

Utilisez l’indicateur --environment pour définir l’environnement. Par exemple :

dotnet run --environment Production

La commande précédente définit l’environnement sur Production et affiche une sortie similaire à ce qui suit dans la fenêtre de commande :

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Développement et launchSettings.json

L’environnement de développement peut activer des fonctionnalités qui ne doivent pas être exposées en production. Par exemple, les modèles du projet ASP.NET Core activent la page d’exceptions du développeur dans l’environnement de développement. En raison du coût des performances, la validation de l’étendue et la validation des dépendances se produisent uniquement dans le développement.

L’environnement de développement de l’ordinateur local peut être défini dans le fichier Properties\launchSettings.json du projet. Les valeurs d’environnement définies dans launchSettings.json remplacent les valeurs définies dans l’environnement système.

Le fichier launchSettings.json :

• Est utilisé uniquement sur l’ordinateur de développement local.
• N’est pas déployé.
• Contient les paramètres de profil.

Le JSON suivant présente le fichier launchSettings.json d’un projet web ASP.NET Core nommé EnvironmentsSample créé avec Visual Studio ou dotnet new :

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Le JSON précédent contient deux profils :

• EnvironmentsSample : Le nom du profil est le nom du projet. En tant que premier profil répertorié, ce profil est utilisé par défaut. La clé "commandName" a la valeur "Project", par conséquent, le serveur web Kestrel est lancé.

• IIS Express: La clé "commandName" a la valeur "IISExpress", par conséquent IISExpress est le serveur web.

Vous pouvez définir le profil de lancement sur le projet ou tout autre profil inclus dans launchSettings.json. Par exemple, dans l’image ci-dessous, la sélection du nom du projet lance le serveur webKestrel.

La valeur de commandName peut spécifier le serveur web à lancer. commandName peut avoir l’une des valeurs suivantes :

• IISExpress : lance IIS Express.
• IIS : Aucun serveur web n’a été lancé. IIS est censé être disponible.
• Project : lance Kestrel.

L’onglet Déboguer/Général des propriétés du projet Visual Studio 2022 fournit un lien d’interface utilisateur Ouvrir les profils de lancement de débogage. Ce lien ouvre une boîte de dialogue Lancer les profils qui vous permet de modifier les paramètres de variable d’environnement dans le fichier launchSettings.json. Vous pouvez également ouvrir la boîte de dialogue Lancer les profils dans le menu Déboguer en sélectionnant le <nom du projet> Propriétés du débogage. Les modifications apportées aux profils de projet peuvent ne prendre effet qu’une fois le serveur web redémarré. Vous devez redémarrer Kestrel pour qu’il puisse détecter les modifications apportées à son environnement.

Le fichier suivant launchSettings.json contient plusieurs profils :

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Les profils peuvent être sélectionnés :

• À partir de l’interface utilisateur de Visual Studio.

• Utilisation de la commande dotnet run CLI avec l’option --launch-profile définie sur le nom du profil. Cette approche prend uniquement en charge les profils Kestrel.

  dotnet run --launch-profile "EnvironmentsSample"
  

Avertissement

launchSettings.json ne doit pas stocker les secrets. Vous pouvez utiliser l’outil Secret Manager afin de stocker des secrets pour le développement local.

Quand vous utilisez Visual Studio Code, les variables d’environnement peuvent être définies dans le fichier .vscode/launch.json. L’exemple suivant définit plusieurs variables d’environnement pour les valeurs de configuration de l’hôte :

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            // Configuration ommitted for brevity.
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "https://localhost:5001",
                "ASPNETCORE_DETAILEDERRORS": "1",
                "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
            },
            // Configuration ommitted for brevity.

Le fichier .vscode/launch.json est utilisé uniquement par Visual Studio Code.

Production

Vous devez configurer l’environnement de production pour optimiser la sécurité, les performances et la robustesse de l’application. Voici quelques paramètres courants qui diffèrent du développement :

• Mise en cache.
• Les ressources côté client sont groupées, réduites et éventuellement servies à partir d’un CDN.
• Les Pages d’erreur de diagnostic sont désactivées.
• Les pages d’erreur conviviales sont activées.
• La journalisation et la surveillance de la production sont activées. Par exemple, en utilisat Application Insights.

Définir l’environnement en définissant une variable d’environnement

Il est souvent utile de définir un environnement spécifique pour les tests avec une variable d’environnement ou un paramètre de plateforme. Si l’environnement n’est pas défini, il prend par défaut la valeur Production, ce qui désactive la plupart des fonctionnalités de débogage. La méthode de configuration de l’environnement dépend du système d’exploitation.

Lorsque l’hôte est généré, le dernier paramètre d’environnement lu par l’application détermine l’environnement de l’application. L’environnement de l’application ne peut pas être changé pendant que l’application est en cours d’exécution.

La page À propos de l’échantillon de code affiche la valeur de IWebHostEnvironment.EnvironmentName.

Azure App Service

Production est la valeur par défaut si DOTNET_ENVIRONMENT et ASPNETCORE_ENVIRONMENT n’ont pas été définis. Les applications déployées sur Azure sont Production par défaut.

Pour définir l’environnement dans une application Azure App Service à l’aide du portail :

1. Sélectionnez l’application dans la page App Services.
2. Dans le groupe Paramètres, sélectionnez Variables d’environnement.
3. Dans l’onglet Paramètres de l’application, sélectionnez + Ajouter.
4. Dans la fenêtre Ajouter/Modifier un paramètre , indiquez ASPNETCORE_ENVIRONMENT pour le Nom. Pour Valeur, spécifiez l’environnement (par exemple Staging).
5. Cochez la case Paramètre d’emplacement de déploiement si vous souhaitez que le paramètre d’environnement reste avec l’emplacement actuel quand des emplacements de déploiement sont permutés. Pour plus d’informations, consultez Configurer des environnements intermédiaires dans Azure App Service dans la documentation Azure.
6. Sélectionnez OK pour fermer la boîte de dialogue Ajouter/modifier le paramètre d’application .
7. Sélectionnez Enregistrer en haut de la page Configuration.

Azure App Service redémarre automatiquement l’application après qu’un paramètre d’application est ajouté, changé ou supprimé dans le portail Azure.

Windows - Définir une variable d’environnement pour un processus

Les valeurs d’environnement dans launchSettings.json remplacent les valeurs définies dans l’environnement système.

Pour définir le ASPNETCORE_ENVIRONMENT pour la session active lorsque l’application est démarrée à l’aide de dotnet run, utilisez les commandes suivantes à l’invite de commandes ou dans PowerShell :

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

Windows - Définir la variable d’environnement globalement

Les commandes précédentes définissent ASPNETCORE_ENVIRONMENT uniquement pour les processus lancés à partir de cette fenêtre de commande.

Pour définir la valeur globalement dans Windows, utilisez l’une des approches suivantes :

• Ouvrez le Panneau de configuration>Système>Paramètres système avancés, puis ajoutez ou modifiez la valeur ASPNETCORE_ENVIRONMENT :

  

  

• Ouvrez une invite de commandes d’administration, puis utilisez la commande setx, ou ouvrez une invite de commandes PowerShell d’administration et utilisez [Environment]::SetEnvironmentVariable :

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    Le commutateur /M définit la variable d’environnement au niveau du système. Si le commutateur /M n’est pas utilisé, la variable d’environnement est définie pour le compte d’utilisateur.

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    La valeur d’option Machine définit la variable d’environnement au niveau du système. Si la valeur d’option est remplacée par User, la variable d’environnement est définie pour le compte d’utilisateur.

Quand la variable d’environnement ASPNETCORE_ENVIRONMENT est définie globalement, elle prend effet pour dotnet run dans n’importe quelle fenêtre Commande ouverte une fois la valeur définie. Les valeurs d’environnement dans launchSettings.json remplacent les valeurs définies dans l’environnement système.

Windows - Utiliser web.config

Pour définir la variable d’environnement ASPNETCORE_ENVIRONMENT avec web.config, consultez la section Définition des variables d’environnement à l’adresse web.config file.

Windows - Déploiements IIS

Incluez la propriété <EnvironmentName> dans le profil de publication (.pubxml) ou le fichier projet. Cette approche définit l’environnement dans web.config lorsque le projet est publié :

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Pour définir la variables d’environnement ASPNETCORE_ENVIRONMENT pour une application qui s’exécute dans un pool d’applications isolé (prie en charge sur IIS 10.0 ou versions ultérieures), consultez la section Commande AppCmd.exe de Variables d’environnement <environmentVariables>. Quand la variable d’environnement ASPNETCORE_ENVIRONMENT est définie pour un pool d’applications, sa valeur remplace un paramètre au niveau du système.

Lors de l’hébergement d’une application dans IIS et de l’ajout ou du changement de la variable d’environnement ASPNETCORE_ENVIRONMENT, utilisez l’une des approches suivantes pour que la nouvelle valeur soit récupérée par des applications :

• Exécutez la commande net stop was /y suivie de net start w3svc à partir d’une invite de commandes.
• Redémarrez le serveur.

macOS

Vous pouvez définir l’environnement actuel pour macOS en ligne durant l’exécution de l’application :

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Vous pouvez également définir l’environnement avec export avant d’exécuter l’application :

export ASPNETCORE_ENVIRONMENT=Staging

Les variables d’environnement de niveau machine sont définies dans le fichier .bashrc ou .bash_profile. Modifiez le fichier à l’aide d’un éditeur de texte. Ajoutez l’instruction suivante :

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Pour les distributions Linux, exécutez la commande export à une invite de commandes pour les paramètres de variable basés sur la session, et le fichier bash_profile pour les paramètres d’environnement de niveau machine.

Définir l’environnement dans le code

Pour définir l’environnement dans le code, utilisez WebApplicationOptions.EnvironmentName lors de la création de WebApplicationBuilder, comme illustré dans l’exemple suivant :

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Configuration par environnement

Pour charger la configuration par environnement, consultez Configuration dans ASP.NET Core.

Configurer les services et les intergiciels par environnement

Utilisez WebApplicationBuilder.Environment ou WebApplication.Environment pour ajouter de manière conditionnelle des services ou des intergiciels en fonction de l’environnement actuel. Le modèle de projet inclut un exemple de code qui ajoute des intergiciels uniquement lorsque l’environnement actuel n’est pas Développement :

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Le code en surbrillance vérifie l’environnement actuel lors de la génération du pipeline de requête. Pour vérifier l’environnement actuel lors de la configuration des services, utilisez builder.Environment au lieu de app.Environment.

Ressources supplémentaires

• Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
• Démarrage d’une application dans ASP.NET Core
• Configuration dans ASP.NET Core
• Environnements ASP.NET Core Blazor