Utiliser plusieurs environnements dans ASP.NET Core

Article
04/26/2024

Remarque

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

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la Stratégie de prise en charge de .NET et .NET Core. 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.

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 :

DOTNET_ENVIRONMENT
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 ASPNETCORE_ENVIRONMENT remplace DOTNET_ENVIRONMENT.

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

DOTNET_ENVIRONMENT
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.

Lancement d’IIS Express dans le menu

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.

Propriétés de projet, définition des variables d’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 :

Sélectionnez l’application dans la page App Services.
Dans le groupe Paramètres, sélectionnez Variables d’environnement.
Dans l’onglet Paramètres de l’application, sélectionnez + Ajouter.
Dans la fenêtre Ajouter/Modifier un paramètre , indiquez ASPNETCORE_ENVIRONMENT pour le Nom. Pour Valeur, spécifiez l’environnement (par exemple Staging).
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.
Sélectionnez OK pour fermer la boîte de dialogue Ajouter/modifier le paramètre d’application .
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

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.

Environnements

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

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

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 :

Appelle UseDeveloperExceptionPage quand la valeur ASPNETCORE_ENVIRONMENT est définie sur Development.
Appelle UseExceptionHandler lorsque la valeur de ASPNETCORE_ENVIRONMENT est définie sur Staging, Productionou Staging_2.
Injecte IWebHostEnvironment dans Startup.Configure. 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.
Est similaire au code généré par les modèles ASP.NET Core.

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

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

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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 ce document est basé sur un projet Pages Razor nommé EnvironmentsSample.

Le code suivant crée et exécute une application web nommée EnvironmentsSample :

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

Lorsque l’application s’exécute, elle affiche certaines des sorties suivantes :

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\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 ASP.NET Core activent la page d’exceptions du développeur dans l’environnement de développement.

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:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Le balisage précédent contient deux profils :

IIS Express: Le profil par défaut utilisé lors du lancement de l’application à partir de Visual Studio. 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. Par exemple, dans l’image ci-dessous, la sélection du nom du projet lance le serveur webKestrel.
EnvironmentsSample : Le nom du profil est le nom du projet. Ce profil est utilisé par défaut lors du lancement de l’application avec dotnet run. La clé "commandName" a la valeur "Project", par conséquent, le serveur web Kestrel est lancé.

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 des propriétés de projet Visual Studio fournit une interface graphique utilisateur qui permet de modifier le fichier launchSettings.json. 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.

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

Le fichier suivant launchSettings.json contient plusieurs profils :

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

Les profils peuvent être sélectionnés :

À partir de l’interface utilisateur de Visual Studio.
Utilisation de la commande dotnet run dans un interpréteur de commandes 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 "SampleApp"
```

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.

{
    "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 uniquement utilisé par Visual Studio Code.

Production

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

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 Azure App Service, effectuez les étapes suivantes :

Sélectionnez l’application dans le panneau App Services.
Dans le groupe Paramètres, sélectionnez le panneau Configuration .
Sous l’onglet Paramètres d’application, sélectionnez Nouveau paramètre d’application.
Dans la fenêtre Ajouter/Modifier un paramètre , indiquez ASPNETCORE_ENVIRONMENT pour le Nom. Pour Valeur, spécifiez l’environnement (par exemple Staging).
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.
Sélectionnez OK pour fermer la fenêtre Ajouter/modifier le paramètre d’application .
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

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

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 :

Invite de commandes

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

PowerShell

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

La commande précédente définit 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 :

Invite de commandes
```
setx ASPNETCORE_ENVIRONMENT Staging /M
```
Le commutateur /M indique de définir 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.

PowerShell
```
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
```
La valeur d’option Machine indique de définir 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.

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.

Fichier projet ou profil de publication

Pour les déploiements d’IIS Windows : inclure 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>

Par pool d’applications IIS

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>. 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.

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

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Définir l’environnement dans le code

Appelez UseEnvironment lors de la génération de l’hôte. Consultez Hôte générique .NET dans ASP.NET Core.

Configuration par environnement

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

Classe et méthodes Startup en fonction de l’environnement

Injecter IWebHostEnvironment dans la classe Startup

Injecter IWebHostEnvironment dans le constructeur Startup. Cette approche est utile lorsque l’application nécessite une configuration Startup pour seulement quelques environnements avec des différences de code minimales par environnement.

Dans l’exemple suivant :

L’environnement est tenu sur le terrain _env.
_env est utilisé dans ConfigureServices et Configure pour appliquer la configuration de démarrage en fonction de l’environnement de l’application.

public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Conventions de la classe Startup

Quand une application ASP.NET Core démarre, la classe Startup amorce l’application. L’application peut définir plusieurs classes Startup pour différents environnements. La classe appropriée Startup est sélectionnée au moment de l’exécution. 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. Cette approche est utile lorsque l’application nécessite la configuration du démarrage pour plusieurs environnements avec de nombreuses différences de code par environnement. Les applications classiques n’auront pas besoin de cette approche.

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

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Utilisez plutôt la surcharge UseStartup(IWebHostBuilder, String) qui accepte un nom d’assembly :

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

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

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

Conventions de la méthode Startup

Configure et ConfigureServices prennent en charge les versions propres à l’environnement de la forme Configure<EnvironmentName> et Configure<EnvironmentName>Services. Si une correspondance Configure<EnvironmentName>Services ou une méthode Configure<EnvironmentName> est introuvable, la méthode ConfigureServices ou Configure est utilisée, respectivement. Cette approche est utile lorsque l’application nécessite la configuration du démarrage pour plusieurs environnements avec de nombreuses différences de code par environnement :

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}

Partager via

Utiliser plusieurs environnements dans ASP.NET Core

Environnements

Créer des échantillons d’environnements

Définir l’environnement sur la ligne de commande

Développement et launchSettings.json

Production

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

Azure App Service

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

Windows - Définir la variable d’environnement globalement

Windows - Utiliser web.config

Windows - Déploiements IIS

macOS

Linux

Définir l’environnement dans le code

Configuration par environnement

Configurer les services et les intergiciels par environnement

Ressources supplémentaires

Environnements

Créer des échantillons d’environnements

Développement et launchSettings.json

Production

Définir l’environnement

Azure App Service

Windows

macOS

Linux

Définir l’environnement dans le code

Configuration par environnement

Classe et méthodes Startup en fonction de l’environnement

Injecter IWebHostEnvironment dans la classe Startup

Conventions de la classe Startup

Conventions de la méthode Startup

Ressources supplémentaires

Ressources supplémentaires