Utiliser plusieurs environnements dans ASP.NET Core

  • Article
  • 23 minutes de lecture

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 :

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

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 WebApplication.CreateBuilder méthode est appelée. Les modèles d’application web par défaut ASP.NET Core appellent WebApplication.CreateBuilder. La DOTNET_ENVIRONMENT valeur remplace quand ASPNETCORE_ENVIRONMENTWebApplicationBuilder est utilisé. Pour les autres hôtes, tels que ConfigureWebHostDefaults et WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT a une priorité plus élevée.

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

Le code suivant :

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 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’exemple de code inclut le balisage précédent et affiche la valeur de IWebHostEnvironment.EnvironmentName.

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

Créer des environnementsÉchantillon

L’exemple de code utilisé dans cet article est basé sur un Razor projet Pages 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 l’application s’exécute, 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 de projet ASP.NET Core activent la page d’exception 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. Valeurs d’environnement définies dans launchSettings.json remplacer 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 fichier ON suivant JSmontre le launchSettings.json fichier 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"
      }
    }
  }
}

L’on précédent JScontient 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 "commandName" clé a la valeur "Project", par conséquent, le Kestrel serveur web est lancé.

  • IIS Express: la "commandName" clé 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 Kestrel serveur web.

IIS Express lancer 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 launchSettings.json fichier. 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é. Kestrel doit être redémarré avant de pouvoir 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 dotnet run commande CLI avec l’option --launch-profile définie sur le nom du profil. Cette approche prend uniquement en charge les Kestrel profils.

    dotnet run --launch-profile "SampleApp"

Avertissement

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

Lorsque vous utilisez Visual Studio Code, des variables d’environnement peuvent être définies dans le .vscode/launch.json fichier. 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 .vscode/launch.json fichier est utilisé uniquement par Visual Studio Code.

Production

L’environnement de production doit être configuré pour optimiser la sécurité, les performances et la robustesse des applications. 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.
  • Journalisation et supervision de production activées. Par exemple, à l’aide d’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 modifié pendant l’exécution de l’application.

La page À propos de l’exemple 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 Configuration.
  3. Sous l’onglet Paramètres de l’application, sélectionnez Nouveau paramètre d’application.
  4. Dans la fenêtre Ajouter/Modifier un paramètre d’application , indiquez ASPNETCORE_ENVIRONMENT le Nom. Pour Valeur, fournissez 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 lorsque les emplacements de déploiement sont échangé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 l’ajout, la modification ou la suppression d’un paramètre d’application dans le Portail Azure.

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

Valeurs d’environnement dans launchSettings.json les valeurs de remplacement 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éfinies 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 lesparamètres systèmePanneau de configuration>System> Advanced et ajoutez ou modifiez la ASPNETCORE_ENVIRONMENT valeur :

    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 :

    • setx ASPNETCORE_ENVIRONMENT Staging /M

      Le /M commutateur 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")

      L’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. Valeurs d’environnement dans launchSettings.json les valeurs de remplacement 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éfinir des variables d’environnement de web.config fichier.

Windows - Déploiements IIS

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

<PropertyGroup>
  <EnvironmentName>Development</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 commandeAppCmd.exe de l’environnement Variables <d’environnementVariables>. 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 de la modification de la ASPNETCORE_ENVIRONMENT variable d’environnement, utilisez l’une des approches suivantes pour que la nouvelle valeur soit récupérée par les 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, utilisez la export commande à l’invite de commandes pour les paramètres de variables basées sur la session et le fichier bash_profile pour les paramètres d’environnement au niveau de l’ordinateur.

Définir l’environnement dans le code

Pour définir l’environnement dans le code, utilisez WebApplicationOptions.EnvironmentName lors de la création WebApplicationBuilderde , 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();

Pour plus d’informations, 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.

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 :

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENT quand ConfigureWebHostDefaults est appelé. Les modèles d’application web par défaut ASP.NET Core appellent ConfigureWebHostDefaults. La ASPNETCORE_ENVIRONMENT valeur 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_ENVIRONMENTDevelopment sur sur l’ordinateur local.
  • Staging
  • Production : valeur par défaut si DOTNET_ENVIRONMENT et ASPNETCORE_ENVIRONMENT n’ont pas été définis.

Le code suivant :

  • Appelle UseDeveloperExceptionPage quand ASPNETCORE_ENVIRONMENT est défini sur Development.
  • Appelle UseExceptionHandler lorsque la valeur de ASPNETCORE_ENVIRONMENT est définie sur Staging, Productionou Staging_2.
  • IWebHostEnvironment Injecte 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 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’exemple de code inclut le balisage précédent et affiche la valeur de IWebHostEnvironment.EnvironmentName.

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

Créer des environnementsÉchantillon

L’exemple de code utilisé dans ce document est basé sur un Razor projet Pages 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.

L’environnement de développement de l’ordinateur local peut être défini dans le fichier Properties\launchSettings.json du projet. Valeurs d’environnement définies dans launchSettings.json remplacer 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 fichier ON suivant JSmontre le launchSettings.json fichier 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: profil par défaut utilisé lors du lancement de l’application à partir de Visual Studio. La "commandName" clé 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 Kestrel serveur web.

    IIS Express lancer dans le menu

  • 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 "commandName" clé a la valeur "Project", par conséquent, le Kestrel serveur web 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 lancé. IIS est censé être disponible.
  • Project : lance Kestrel.

L’onglet Débogage des propriétés du projet Visual Studio fournit une interface graphique graphique pour modifier le launchSettings.json fichier. Les modifications apportées aux profils de projet peuvent ne prendre effet qu’une fois le serveur web redémarré. Kestrel doit être redémarré avant de pouvoir 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 dotnet run commande 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 Kestrel profils.

    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.

Lors de l’utilisation de Visual Studio Code, des variables d’environnement peuvent être définies dans le .vscode/launch.json fichier . L’exemple suivant définit plusieurs variables d’environnement de configuration d’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 .vscode/launch.json fichier est utilisé uniquement par Visual Studio Code.

Production

L’environnement de production doit être configuré pour optimiser la sécurité, les performances et la robustesse des applications. 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.
  • Journalisation et supervision de production activées. Par exemple, à l’aide d’Application Insights.

Définir l’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 modifié pendant l’exécution de l’application.

La page À propos de l’exemple 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 :

  1. Sélectionnez l’application dans le panneau App Services.
  2. Dans le groupe Paramètres , sélectionnez le panneau Configuration .
  3. Sous l’onglet Paramètres de l’application, sélectionnez Nouveau paramètre d’application.
  4. Dans la fenêtre Ajouter/Modifier un paramètre d’application , indiquez ASPNETCORE_ENVIRONMENT le Nom. Pour Valeur, fournissez 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 lorsque les emplacements de déploiement sont échangé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 fenêtre Ajouter/Modifier le paramètre d’application .
  7. Sélectionnez Enregistrer en haut du panneau Configuration .

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

Windows

Valeurs d’environnement dans les launchSettings.json valeurs de remplacement 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 lesparamètres systèmePanneau de configuration>System> Advanced et ajoutez ou modifiez la ASPNETCORE_ENVIRONMENT valeur :

    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 :

    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.

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. Valeurs d’environnement dans les launchSettings.json valeurs de remplacement définies dans l’environnement système.

web.config

Pour définir la variable d’environnement ASPNETCORE_ENVIRONMENT avec web.config, consultez la section Définir des variables d’environnement de web.config fichier.

Fichier projet ou profil de publication

Pour les déploiements Windows IIS : Incluez la <EnvironmentName> propriété 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.

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, utilisez la export commande dans une invite de commandes pour les paramètres de variable basés sur la session et bash_profile fichier pour les paramètres d’environnement au niveau de l’ordinateur.

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 Startup constructeur. 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 conservé dans le _env champ.
  • _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 Startup classes 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 basées sur Startup l’environnement, créez des Startup{EnvironmentName} classes et une classe de secours Startup :

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 la UseStartup(IWebHostBuilder, String) surcharge 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

Configurez et ConfigureServices prennent en charge les versions spécifiques à l’environnement du formulaire Configure<EnvironmentName> et Configure<EnvironmentName>Services. Si une correspondance Configure<EnvironmentName>Services ou Configure<EnvironmentName> une méthode est introuvable, la ConfigureServices méthode 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}");
    }
}

Ressources supplémentaires