Utiliser plusieurs environnements dans ASP.NET CoreUse multiple environments in ASP.NET Core

Par Rick AndersonBy Rick Anderson

ASP.NET Core configure le comportement de l’application en fonction de l’environnement d’exécution à l’aide d’une variable d’environnement.ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

EnvironnementsEnvironments

ASP.NET Core lit la variable d’environnement ASPNETCORE_ENVIRONMENT au démarrage de l’application et stocke la valeur dans IHostingEnvironment.EnvironmentName.ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in IHostingEnvironment.EnvironmentName. Vous pouvez affecter n’importe quelle valeur à ASPNETCORE_ENVIRONMENT. Toutefois, trois valeurs sont prises en charge par le framework : Development, Staging et Production.You can set ASPNETCORE_ENVIRONMENT to any value, but three values are supported by the framework: Development, Staging, and Production. Si ASPNETCORE_ENVIRONMENT n’est pas définie, la valeur par défaut est Production.If ASPNETCORE_ENVIRONMENT isn't set, it defaults to Production.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseMvc();
}

Le code précédent :The preceding code:

Le Tag helper d’environnement utilise la valeur de la propriété IHostingEnvironment.EnvironmentName pour inclure ou exclure le balisage dans l’élément :The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude markup in the element:

<environment include="Development">
    <div>&lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>&lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

Sur Windows et macOS, les valeurs et les variables d’environnement ne respectent pas la casse.On Windows and macOS, environment variables and values aren't case sensitive. Les valeurs et les variables d’environnement Linux respectent la casse par défaut.Linux environment variables and values are case sensitive by default.

DéveloppementDevelopment

L’environnement de développement peut activer des fonctionnalités qui ne doivent pas être exposées en production.The development environment can enable features that shouldn't be exposed in production. Par exemple, les modèles ASP.NET Core activent la page d’exceptions du développeur dans l’environnement de développement.For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

L’environnement de développement de l’ordinateur local peut être défini dans le fichier Properties\launchSettings.json du projet.The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Les valeurs d’environnement définies dans launchSettings.json remplacent les valeurs définies dans l’environnement système.Environment values set in launchSettings.json override values set in the system environment.

Le code JSON suivant montre trois profils à partir d’un fichier launchSettings.json :The following JSON shows three profiles from a launchSettings.json file:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:54339/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:54340/"
    },
    "Kestrel Staging": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:51997/"
    }
  }
}

Notes

La propriété applicationUrl dans launchSettings.json peut spécifier une liste d’URL de serveur.The applicationUrl property in launchSettings.json can specify a list of server URLs. Utilisez un point-virgule entre les URL de la liste :Use a semicolon between the URLs in the list:

"EnvironmentsSample": {
   "commandName": "Project",
   "launchBrowser": true,
   "applicationUrl": "https://localhost:5001;http://localhost:5000",
   "environmentVariables": {
     "ASPNETCORE_ENVIRONMENT": "Development"
   }
}

Quand l’application est lancée avec dotnet run, le premier profil avec "commandName": "Project" est utilisé.When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. La valeur de commandName spécifie le serveur web à lancer.The value of commandName specifies the web server to launch. commandName peut avoir l’une des valeurs suivantes :commandName can be any one of the following:

  • IISExpress
  • IIS
  • Project (qui lance Kestrel)Project (which launches Kestrel)

Quand une application est lancée avec dotnet run :When an app is launched with dotnet run:

  • launchSettings.json est lu, s’il est disponible.launchSettings.json is read if available. Les paramètres environmentVariables dans launchSettings.json remplacent les variables d’environnement.environmentVariables settings in launchSettings.json override environment variables.
  • L’environnement d’hébergement s’affiche.The hosting environment is displayed.

La sortie suivante montre une application démarrée avec dotnet run :The following output shows an app started with dotnet run:

PS C:\Websites\EnvironmentsSample> dotnet run
Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.

L’onglet Déboguer des propriétés de projet Visual Studio fournit une interface graphique utilisateur qui permet de modifier le fichier launchSettings.json :The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:

Propriétés de projet, définition des variables d’environnement

Les modifications apportées aux profils de projet peuvent ne prendre effet qu’une fois le serveur web redémarré.Changes made to project profiles may not take effect until the web server is restarted. Vous devez redémarrer Kestrel pour qu’il puisse détecter les modifications apportées à son environnement.Kestrel must be restarted before it can detect changes made to its environment.

Avertissement

launchSettings.json ne doit pas stocker de secrets.launchSettings.json shouldn't store secrets. Vous pouvez utiliser l’outil Secret Manager afin de stocker des secrets pour le développement local.The Secret Manager tool can be used to store secrets for local development.

Quand vous utilisez Visual Studio Code, les variables d’environnement peuvent être définies dans le fichier .vscode/launch.json.When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. L’exemple suivant définit Development comme environnement :The following example sets the environment to Development:

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",

            ... additional VS Code configuration settings ...

            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

Un fichier .vscode/launch.json dans le projet n’est pas lu au démarrage de l’application avec dotnet run de la même façon que Properties/launchSettings.json.A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as Properties/launchSettings.json. Lors du lancement d’une application en cours de développement qui n’a pas de fichier launchSettings.json, vous devez définir l’environnement avec une variable d’environnement ou un argument de ligne de commande pour la commande dotnet run.When launching an app in development that doesn't have a launchSettings.json file, either set the environment with an environment variable or a command-line argument to the dotnet run command.

ProductionProduction

Vous devez configurer l’environnement de production pour optimiser la sécurité, les performances et la robustesse de l’application.The production environment should be configured to maximize security, performance, and app robustness. Voici quelques paramètres courants qui diffèrent du développement :Some common settings that differ from development include:

  • La mise en cache.Caching.
  • Les ressources côté client sont groupées, réduites et éventuellement servies à partir d’un CDN.Client-side resources are bundled, minified, and potentially served from a CDN.
  • Les Pages d’erreur de diagnostic sont désactivées.Diagnostic error pages disabled.
  • Les pages d’erreur conviviales sont activées.Friendly error pages enabled.
  • La journalisation et la surveillance de la production sont activées.Production logging and monitoring enabled. Par exemple, Application Insights.For example, Application Insights.

Définir l’environnementSet the environment

Il est souvent utile de définir un environnement spécifique à des fins de test.It's often useful to set a specific environment for testing. 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.If the environment isn't set, it defaults to Production, which disables most debugging features. La méthode de configuration de l’environnement dépend du système d’exploitation.The method for setting the environment depends on the operating system.

Azure App ServiceAzure App Service

Pour définir l’environnement dans Azure App Service, effectuez les étapes suivantes :To set the environment in Azure App Service, perform the following steps:

  1. Sélectionnez l’application dans le panneau App Services.Select the app from the App Services blade.
  2. Dans le groupe PARAMÈTRES, sélectionnez le panneau Paramètres de l’application.In the SETTINGS group, select the Application settings blade.
  3. Dans la zone Paramètres d’application, sélectionnez Ajouter un nouveau paramètre.In the Application settings area, select Add new setting.
  4. Pour Entrer un nom, spécifiez ASPNETCORE_ENVIRONMENT.For Enter a name, provide ASPNETCORE_ENVIRONMENT. Pour Entrer une valeur, spécifiez l’environnement (par exemple Staging).For Enter a value, provide the environment (for example, Staging).
  5. Cochez la case Paramètre d’emplacement si vous souhaitez que le paramètre d’environnement reste avec l’emplacement actuel quand des emplacements de déploiement sont permutés.Select the Slot Setting check box if you wish the environment setting to remain with the current slot when deployment slots are swapped. Pour plus d’informations, consultez Documentation Azure : Quels sont les paramètres échangés ?.For more information, see Azure Documentation: Which settings are swapped?.
  6. Sélectionnez Enregistrer en haut du panneau.Select Save at the top of the blade.

Azure App Service redémarre automatiquement l’application après qu’un paramètre d’application (variable d’environnement) est ajouté, changé ou supprimé dans le portail Azure.Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed, or deleted in the Azure portal.

WindowsWindows

Pour définir ASPNETCORE_ENVIRONMENT pour la session actuelle quand l’application est démarrée avec dotnet run, les commandes suivantes sont utilisées :To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

Invite de commandesCommand prompt

set ASPNETCORE_ENVIRONMENT=Development

PowerShellPowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Ces commandes prennent effet uniquement pour la fenêtre active.These commands only take effect for the current window. Quand la fenêtre est fermée, le paramètre ASPNETCORE_ENVIRONMENT reprend la valeur de machine ou la valeur par défaut.When the window is closed, the ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.

Pour définir la valeur globalement dans Windows, utilisez l’une des approches suivantes :To set the value globally in Windows, use either of the following approaches:

  • Ouvrez le Panneau de configuration > Système > Paramètres système avancés, puis ajoutez ou modifiez la valeur ASPNETCORE_ENVIRONMENT :Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    Propriétés système avancées

    Variable d’environnement ASPNET Core

  • 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 :Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    Invite de commandesCommand prompt

    setx ASPNETCORE_ENVIRONMENT Development /M
    

    Le commutateur /M indique de définir la variable d’environnement au niveau du système.The /M switch indicates to set the environment variable at the system level. Si le commutateur /M n’est pas utilisé, la variable d’environnement est définie pour le compte d’utilisateur.If the /M switch isn't used, the environment variable is set for the user account.

    PowerShellPowerShell

    [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
    

    La valeur d’option Machine indique de définir la variable d’environnement au niveau du système.The Machine option value indicates to set the environment variable at the system level. Si la valeur d’option est remplacée par User, la variable d’environnement est définie pour le compte d’utilisateur.If the option value is changed to User, the environment variable is set for the user account.

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.When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set.

web.configweb.config

Pour définir la variable d’environnement ASPNETCORE_ENVIRONMENT avec web.config, consultez la section Définition des variables d’environnement à l’adresse Module ASP.NET Core.To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables section of Module ASP.NET Core.

Fichier projet ou profil de publicationProject file or publish profile

Pour les déploiements Windows IIS : Incluez la propriété <EnvironmentName> dans le profil de publication (.pubxml) ou le fichier projet.For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Cette approche définit l’environnement dans web.config lorsque le projet est publié :This approach sets the environment in web.config when the project is published:

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

Par pool d’applications IISPer IIS Application Pool

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 la rubrique Variables d’environnement <environmentVariables>.To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic. 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.When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

Important

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 :When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of the following approaches to have the new value picked up by apps:

  • Exécutez la commande net stop was /y suivie de net start w3svc à partir d’une invite de commandes.Execute net stop was /y followed by net start w3svc from a command prompt.
  • Redémarrez le serveur.Restart the server.

macOSmacOS

Vous pouvez définir l’environnement actuel pour macOS en ligne durant l’exécution de l’application :Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Development dotnet run

Vous pouvez également définir l’environnement avec export avant d’exécuter l’application :Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Development

Les variables d’environnement de niveau machine sont définies dans le fichier .bashrc ou .bash_profile.Machine-level environment variables are set in the .bashrc or .bash_profile file. Modifiez le fichier à l’aide d’un éditeur de texte.Edit the file using any text editor. Ajoutez l’instruction suivante :Add the following statement:

export ASPNETCORE_ENVIRONMENT=Development

LinuxLinux

Pour les versions 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.For Linux distros, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Configuration par environnementConfiguration by environment

Pour charger la configuration par environnement, nous vous recommandons de disposer des éléments suivants :To load configuration by environment, we recommend:

Classe et méthodes Startup en fonction de l’environnementEnvironment-based Startup class and methods

Conventions de la classe StartupStartup class conventions

Quand une application ASP.NET Core démarre, la classe Startup amorce l’application.When an ASP.NET Core app starts, the Startup class bootstraps the app. L’application peut définir différentes classes Startup pour différents environnements (par exemple, StartupDevelopment), et la classe Startup appropriée est sélectionnée au moment de l’exécution.The app can define separate Startup classes for different environments (for example, StartupDevelopment), and the appropriate Startup class is selected at runtime. La classe dont le suffixe du nom correspond à l'environnement actuel est prioritaire.The class whose name suffix matches the current environment is prioritized. Si aucune classe Startup{EnvironmentName} correspondante n’est trouvée, la classe Startup est utilisée.If a matching Startup{EnvironmentName} class isn't found, the Startup class is used.

Pour implémenter des classes Startup basées sur l’environnement, créez une classe Startup{EnvironmentName} pour chaque environnement en cours d’utilisation et une classe Startup de base :To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each environment in use and a fallback Startup class:

// Startup class to use in the Development environment
public class StartupDevelopment
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...
    }
}

// Startup class to use in the Production environment
public class StartupProduction
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...
    }
}

// Fallback Startup class
// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...
    }
}

Utilisez la surcharge UseStartup (IWebHostBuilder, String) qui accepte un nom d’assembly :Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return WebHost.CreateDefaultBuilder(args)
        .UseStartup(assemblyName);
}

Conventions de la méthode StartupStartup method conventions

Configure et ConfigureServices prennent en charge les versions propres à l’environnement de la forme Configure<EnvironmentName> et Configure<EnvironmentName>Services :Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))
        {
            app.UseExceptionHandler("/Error");
        }

        app.UseStaticFiles();
        app.UseMvc();
    }

    public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (!env.IsStaging())
        {
            throw new Exception("Not staging.");
        }

        app.UseExceptionHandler("/Error");
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Ressources supplémentairesAdditional resources