environnements d’exécution ASP.NET Core

Note

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

Warning

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 de cet article.

ASP.NET Core configure le comportement de l’application en fonction de l’environnement d’exécution, qui reflète généralement l’emplacement d’exécution de l’application.

Les applications s’exécutent généralement dans l’environnement de développement pendant le développement local et les tests sur l’ordinateur d’un développeur avec un ensemble de comportements configurés. En revanche, ils s’exécutent dans l’environnement de production lorsqu’ils sont déployés sur un serveur avec un ensemble différent de comportements configurés. Vous pouvez utiliser n’importe quel nombre d’environnements supplémentaires, tels que l’environnement intermédiaire fourni par l’infrastructure pour la mise en lots d’une application avant le déploiement en direct ou d’autres environnements que les développeurs créent.

Cet article décrit les environnements d’exécution d’application, comment utiliser l’environnement pour contrôler le comportement de l’application et comment définir l’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.

Environments

Bien que l’environnement puisse être n’importe quelle valeur de chaîne, les valeurs d’environnement suivantes sont fournies par l’infrastructure :

L’environnement de production est configuré pour optimiser la sécurité, les performances et la fiabilité des applications. Les paramètres et la configuration courants des développeurs qui diffèrent de l’environnement de développement sont les suivants :

Activation de la mise en cache.
Regroupement et minification des ressources côté client, ainsi que leur distribution via un CDN.
Désactivation des pages d’erreurs de diagnostic et activation des pages d’erreurs conviviales.
Activation de la journalisation et de la surveillance de la production. Par exemple, la journalisation est activée pour Azure Application Insights.

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.

Logging

La sortie dans l’interpréteur de commandes d’une application en cours d’exécution au démarrage indique l’environnement de l’application. Dans l’exemple suivant, l’application s’exécute dans l’environnement intermédiaire :

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Variables d’environnement qui déterminent l’environnement d’exécution

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

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT

Lors de l’utilisation WebApplication, la DOTNET_ENVIRONMENT valeur est prioritaire sur ASPNETCORE_ENVIRONMENT. Lors de l’utilisation WebHost, ASPNETCORE_ENVIRONMENT est prioritaire.

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT lorsque la méthode WebApplication.CreateBuilder est appelée. Les modèles de projet d’application web ASP.NET Core appellent WebApplication.CreateBuilder. La valeur ASPNETCORE_ENVIRONMENT remplace DOTNET_ENVIRONMENT.

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT quand ConfigureWebHostDefaults est appelé. Les modèles de projet d’application web ASP.NET Core appellent ConfigureWebHostDefaults. La valeur ASPNETCORE_ENVIRONMENT remplace DOTNET_ENVIRONMENT.

Si les variables d’environnement DOTNET_ENVIRONMENT et ASPNETCORE_ENVIRONMENT ne sont pas définies, l’environnement de production est l’environnement par défaut.

Sur Windows et macOS, les noms de variables d’environnement sont insensibles à la casse. Les variables d’environnement Linux respectent la casse.

Contrôler l’exécution du code 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 code suivant dans le fichier de l’application Program :

Utilise WebApplication.Environment pour distinguer l’environnement.
Appelle UseExceptionHandler, qui ajoute le middleware du gestionnaire d'exceptions au pipeline de traitement des requêtes pour gérer les exceptions.
Appelle , ce qui ajoute le middleware HSTS pour appliquer l’en-tête .

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

L’exemple précédent vérifie l’environnement actuel pour le pipeline de traitement des demandes. Pour vérifier l’environnement actuel lors de la configuration des services, utilisez builder.Environment au lieu de app.Environment.

Utilisez IWebHostEnvironment ou WebApplication.Environment pour ajouter de manière conditionnelle des services ou des intergiciels en fonction de l’environnement actuel.

Le code suivant dans Startup.Configure:

Injecte IWebHostEnvironmentStartup.Configure dans le code pour adapter le code à l’environnement. Cette approche est utile lorsque l’application nécessite uniquement un ajustement Startup.Configure pour quelques environnements avec des différences de code minimales par environnement. Lorsque de nombreuses différences de code existent par environnement, envisagez d’utiliser l’accès à l’environnement à partir d’une Startup classe, qui est abordée plus loin dans cet article.
Appelle UseDeveloperExceptionPage quand la valeur ASPNETCORE_ENVIRONMENT est définie sur Development. L’appel ajoute un intergiciel qui capture les exceptions et génère des réponses d’erreur HTML.
Appelle UseExceptionHandler lorsque la valeur de ASPNETCORE_ENVIRONMENT est définie sur Production, Stagingou Testing. L’appel ajoute l’intergiciel du gestionnaire d’exceptions au pipeline pour gérer les exceptions.

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

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

    ...
}

L’exemple précédent vérifie l’environnement actuel lors de la génération du pipeline de requête. Pour vérifier l’environnement actuel dans Startup.ConfigureServices lors de la configuration des services, injectez IWebHostEnvironment dans la classe Startup au lieu de l’injecter dans Startup.Configure, et utilisez le service injecté pour déterminer l’environnement dans Startup.ConfigureServices et Startup.Configure.

Dans l'application, le IHostEnvironment fournit des informations générales sur l'environnement d'hébergement de l'application, et la propriété IHostEnvironment.EnvironmentName indique l'environnement actuel de l'application.

Contrôler le contenu rendu

Injectez IHostEnvironment dans un composant rendu serveur Razor et utilisez les méthodes d’extension et EnvironmentName la propriété du service pour déterminer l’environnement pour le rendu du contenu :

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Pour Blazor Web Apps nécessitant que l'environnement contrôle le rendu côté client, consultez les composants Prerender ASP.NET CoreRazor.

Définir l’environnement dans un interpréteur de commandes lorsque l’application est exécutée (`dotnet run`)

Utilisez l’option pour définir l’environnement -e|--environment :

dotnet run -e Staging

Définir l’environnement avec le fichier de paramètres de lancement (`launchSettings.json`)

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

Le fichier launchSettings.json :

Est utilisé uniquement sur l’ordinateur de développement local.
N’est pas déployé lorsque l’application est publiée.
Peut contenir plusieurs profils, chacun configurant un environnement différent.

L’exemple suivant définit l’environnement de préproduction pour le profil de lancement https, en utilisant la variable d’environnement ASPNETCORE_ENVIRONMENT.

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

Dans Visual Studio, il existe deux approches pour définir l’environnement via des profils de lancement :

Appuyez sur+ Entrée ou sélectionnez Propriétés après avoir cliqué avec le bouton droit sur le projet dans l’Explorateur de solutions. Sélectionnez Déboguer>Général, puis sélectionnez le lien Ouvrir l’interface utilisateur des profils de lancement de débogage.
Une fois le projet sélectionné dans l’Explorateur de solutions, sélectionnez {PROJECT NAME} Propriétés de débogage dans le menu Débogage , où l’espace {PROJECT NAME} réservé est un nom de projet.

Les approches précédentes ouvrent la boîte de dialogue Profils de lancement dans laquelle vous pouvez modifier les paramètres de variable d’environnement dans le launchSettings.json fichier. 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.

Les profils peuvent être sélectionnés dans l’interface utilisateur de Visual Studio en regard du bouton Démarrer (>).

Lorsqu’une solution contient plusieurs projets, définissez uniquement l’environnement pour le projet de démarrage.

Vous pouvez également utiliser la commande dotnet run avec l’option -lp|--launch-profile définie comme nom du profil. Cette approche prend uniquement en charge les profils de lancement en fonction de la Project commande.

dotnet run -lp "https"

Lorsque vous utilisez Visual Studio Code avec le Kit de développement C# pour Visual Studio Code (Prise en main de C# dans VS Code), les profils de lancement sont récupérés à partir du fichier de l’application launchSettings.json .

Si le Kit de développement C# n’est pas utilisé, définissez la ASPNETCORE_ENVIRONMENT variable d’environnement dans la .vscode/launch.jsonenv section, ainsi que les autres variables d’environnement définies dans la section :

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

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

Définir l’environnement avec 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 est défini par défaut sur l’environnement de 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.

Azure App Service

Les applications déployées sur Azure App Service adoptent l’environnement de production par défaut.

Pour définir la variable d’environnement ASPNETCORE_ENVIRONMENT , consultez les ressources suivantes dans la documentation Azure :

Azure App Service redémarre automatiquement l’application après l’ajout, la modification ou la suppression d’un paramètre d’application.

Définir une variable d’environnement pour un processus

Pour définir la variable d’environnement ASPNETCORE_ENVIRONMENT pour la session actuelle (interpréteur de commandes) lorsque l’application est démarrée avec dotnet run, utilisez les commandes suivantes. Une fois la variable d’environnement définie, l’application est démarrée sans profil de lancement à l’aide de l’option --no-launch-profile .

Dans l’interpréteur de commandes, définissez la variable d’environnement à l’aide de l’approche appropriée pour votre système d’exploitation.
Exécutez la dotnet run commande sans utiliser de profil de lancement :
```
dotnet run --no-launch-profile
```

Lorsque vous utilisez PowerShell, les étapes précédentes peuvent être combinées dans les deux commandes suivantes. L’exemple suivant définit l’environnement intermédiaire :

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

Définir globalement une variable d’environnement

Utilisez les conseils appropriés pour votre système d’exploitation pour définir la variable d’environnement ASPNETCORE_ENVIRONMENT .

Lorsque la ASPNETCORE_ENVIRONMENT variable d’environnement est définie globalement, elle prend effet pour la dotnet run commande dans n’importe quel interpréteur de commandes ouvert une fois la valeur définie. Les valeurs d’environnement définies par les profils de lancement dans le launchSettings.json fichier remplacent les valeurs définies pour l’environnement système.

Définir l’environnement pour les applications déployées sur IIS

Pour définir la ASPNETCORE_ENVIRONMENT variable d’environnement avec le web.config fichier, consultez web.config fichier.

Pour définir la variable d’environnement sur LE déploiement sur IIS, incluez la <EnvironmentName> propriété dans le profil de publication (.pubxml) ou le fichier projet. L’exemple suivant définit l’environnement dans web.config l’environnement intermédiaire lorsque le projet est publié :

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

Pour définir la ASPNETCORE_ENVIRONMENT variable d’environnement d’une application s’exécutant dans un pool d’applications isolé (pris en charge sur IIS 10.0 ou version ultérieure), consultez la section Variables d’environnement <environmentVariables>. Lorsque la ASPNETCORE_ENVIRONMENT variable d’environnement 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 l’ajout ou la modification de la ASPNETCORE_ENVIRONMENT variable d’environnement, utilisez l’une des approches suivantes pour que la nouvelle valeur prenne effet pour les applications en cours d’exécution :

Exécutez net stop was /y suivi de net start w3svc dans un interpréteur de commandes.
Redémarrez le serveur.

Docker

Définissez l’environnement de l’application à l’aide de l’une des approches de cette section.

Utiliser un fichier Dockerfile

Définissez la variable d’environnement ASPNETCORE_ENVIRONMENT dans le fichier Dockerfile à l’aide de l’instruction ENV :

ENV ASPNETCORE_ENVIRONMENT=Staging

Utiliser Docker Compose

Pour les applications multiservices gérées avec Docker Compose, définissez des ASPNETCORE_ENVIRONMENT variables d’environnement dans le docker-compose.yml fichier :

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Un environnement défini au moment de l’exécution avec Docker Compose remplace un environnement défini par le fichier Dockerfile.

Utiliser la `docker run` commande

Lors de l’exécution du conteneur Docker avec la docker run commande, définissez la ASPNETCORE_ENVIRONMENT variable d’environnement avec l’option -e|--env :

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Un environnement défini au moment de l’exécution par docker run remplace un environnement défini par le fichier Dockerfile.

Fichier d’environnement Docker

Définissez la variable d’environnement ASPNETCORE_ENVIRONMENT en utilisant un fichier d’environnement Docker (.env).

env_variables.env :

ASPNETCORE_ENVIRONMENT=Staging

Chargez le fichier avec l’option --env-file lors de l’exécution de la commande docker run :

docker run --env-file ./env_variables.env aspnet_core_image

Un environnement défini au moment de l’exécution par docker run remplace un environnement défini par le fichier Dockerfile.

Définir l’environnement dans le code de démarrage de l’application

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
});

Appelez UseEnvironment lors de la génération de l’hôte. Pour plus d’informations, consultez l’hôte générique .NET dans ASP.NET Core.

Charger la configuration par environnement

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

Accéder à l’environnement à partir d’une `Startup` classe

L’utilisation d’une Startup classe (Startup.cs) avec Configure et ConfigureServices de méthodes a été requise avant la publication de .NET 6 et reste prise en charge.

Injectez IWebHostEnvironment dans le constructeur pour contrôler l’exécution du Startup code. Cette approche est utile lorsque l’application nécessite de configurer le code de démarrage pour seulement quelques environnements avec des différences de code minimales par environnement.

Dans l’exemple suivant, l’environnement est conservé dans le champ et contrôle l’exécution _env du code en fonction de l’environnement de l’application :

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Classe spécifique à l’environnement `Startup`

Une application peut définir plusieurs classes Startup pour différents environnements suivant la convention de nommage Startup{EnvironmentName} où le nom de l'environnement est représenté par l'espace réservé {ENVIRONMENT NAME}.

La classe dont le suffixe du nom correspond à l'environnement actuel est prioritaire. Si aucune classe Startup{EnvironmentName} correspondante n’est trouvée, la classe Startup est utilisée.

Pour implémenter des classes basées sur Startup l’environnement, créez autant de Startup{EnvironmentName} classes que nécessaire et une classe de secours Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Lorsque le générateur d’hôtes est créé, appelez HostingAbstractionsWebHostBuilderExtensions.UseStartup, qui accepte un nom d’assembly pour charger la classe correcte Startup :

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

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

Méthodes de classe spécifiques à l’environnement `Startup`

Les méthodes Configure et ConfigureServices prennent en charge des versions spécifiques à l’environnement des formulaires Configure{ENVIRONMENT NAME} et Configure{ENVIRONMENT NAME}Services, où le nom de l’environnement est indiqué par l’espace réservé {ENVIRONMENT NAME}. Si un nom d’environnement correspondant n’est pas trouvé pour les méthodes nommées, la méthode ConfigureServices ou la méthode Configure est utilisée, respectivement.

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

Ressources supplémentaires

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2025-09-19

Partage via

environnements d’exécution ASP.NET Core

Environments

Logging

Variables d’environnement qui déterminent l’environnement d’exécution

Contrôler l’exécution du code par environnement

Contrôler le contenu rendu

Définir l’environnement dans un interpréteur de commandes lorsque l’application est exécutée (dotnet run)

Définir l’environnement avec le fichier de paramètres de lancement (launchSettings.json)

Définir l’environnement avec une variable d’environnement

Azure App Service

Définir une variable d’environnement pour un processus

Définir globalement une variable d’environnement

Définir l’environnement pour les applications déployées sur IIS

Docker

Utiliser un fichier Dockerfile

Utiliser Docker Compose

Utiliser la docker run commande

Fichier d’environnement Docker

Définir l’environnement dans le code de démarrage de l’application

Charger la configuration par environnement

Accéder à l’environnement à partir d’une Startup classe

Classe spécifique à l’environnement Startup

Méthodes de classe spécifiques à l’environnement Startup

Ressources supplémentaires

Commentaires

Ressources supplémentaires

Définir l’environnement dans un interpréteur de commandes lorsque l’application est exécutée (`dotnet run`)

Définir l’environnement avec le fichier de paramètres de lancement (`launchSettings.json`)

Utiliser la `docker run` commande

Accéder à l’environnement à partir d’une `Startup` classe

Classe spécifique à l’environnement `Startup`

Méthodes de classe spécifiques à l’environnement `Startup`