daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/fundamentals/environments.md

34 KiB
Raw Blame History

title author description monikerRange ms.author ms.custom ms.date no-loc uid
Use multiple environments in ASP.NET Core rick-anderson Learn how to control app behavior across multiple environments in ASP.NET Core apps. >= aspnetcore-3.1 riande mvc 10/08/2021
Home
Privacy
Kestrel
appsettings.json
ASP.NET Core Identity
cookie
Cookie
Blazor
Blazor Server
Blazor WebAssembly
Identity
Let's Encrypt
Razor
SignalR
fundamentals/environments

Use multiple environments in ASP.NET Core

::: moniker range=">= aspnetcore-6.0"

By Rick Anderson and Kirk Larkin

ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Environments

To determine the runtime environment, ASP.NET Core reads from the following environment variables:

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENT when the WebApplication.CreateBuilder method is called. The default ASP.NET Core web app templates call WebApplication.CreateBuilder. The ASPNETCORE_ENVIRONMENT value overrides DOTNET_ENVIRONMENT.

IHostEnvironment.EnvironmentName can be set to any value, but the following values are provided by the framework:

The following code:

The Environment Tag Helper uses the value of IHostEnvironment.EnvironmentName to include or exclude markup in the element:

[!code-cshtml]

The About page from the sample code includes the preceding markup and displays the value of IWebHostEnvironment.EnvironmentName.

On Windows and macOS, environment variables and values aren't case-sensitive. Linux environment variables and values are case-sensitive by default.

Create EnvironmentsSample

The sample code used in this article is based on a Razor Pages project named EnvironmentsSample.

The following .NET CLI commands create and run a web app named EnvironmentsSample:

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

When the app runs, it displays output similar to the following example:

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

Development and launchSettings.json

The development environment can enable features that shouldn't be exposed in production. For example, the ASP.NET Core project templates enable the Developer Exception Page in the development environment.

The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Environment values set in launchSettings.json override values set in the system environment.

The launchSettings.json file:

  • Is only used on the local development machine.
  • Is not deployed.
  • Contains profile settings.

The following JSON shows the launchSettings.json file for an ASP.NET Core web project named EnvironmentsSample created with Visual Studio or dotnet new:

[!code-json]

The preceding JSON contains two profiles:

  • EnvironmentsSample: The profile name is the project name. This profile is used by default. The "commandName" key has the value "Project", therefore, the Kestrel web server is launched.

  • IIS Express: The "commandName" key has the value "IISExpress", therefore, IISExpress is the web server.

You can set the launch profile to the project or any other profile included in launchSettings.json. For example, in the image below, selecting the project name launches the Kestrel web server.

IIS Express launch on menu

The value of commandName can specify the web server to launch. commandName can be any one of the following:

  • IISExpress : Launches IIS Express.
  • IIS : No web server launched. IIS is expected to be available.
  • Project : Launches Kestrel.

The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file. Changes made to project profiles may not take effect until the web server is restarted. Kestrel must be restarted before it can detect changes made to its environment.

Project Properties Setting Environment variables

The following launchSettings.json file contains multiple profiles:

[!code-json]

Profiles can be selected:

  • From the Visual Studio UI.

  • Using the dotnet run CLI command with the --launch-profile option set to the profile's name. This approach only supports Kestrel profiles.

    dotnet run --launch-profile "SampleApp"

[!WARNING] launchSettings.json shouldn't store secrets. The Secret Manager tool can be used to store secrets for local development.

When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. The following example sets several environment variables for Host configuration values:

[!code-json]

The .vscode/launch.json file is used only by Visual Studio Code.

Production

The production environment should be configured to maximize security, performance, and application robustness. Some common settings that differ from development include:

  • Caching.
  • Client-side resources are bundled, minified, and potentially served from a CDN.
  • Diagnostic error pages disabled.
  • Friendly error pages enabled.
  • Production logging and monitoring enabled. For example, using Application Insights.

Set the environment by setting an environment variable

It's often useful to set a specific environment for testing with an environment variable or platform setting. If the environment isn't set, it defaults to Production, which disables most debugging features. The method for setting the environment depends on the operating system.

When the host is built, the last environment setting read by the app determines the app's environment. The app's environment can't be changed while the app is running.

The About page from the sample code displays the value of IWebHostEnvironment.EnvironmentName.

Azure App Service

xref:Microsoft.Extensions.Hosting.Environments.Production is the default value if DOTNET_ENVIRONMENT and ASPNETCORE_ENVIRONMENT have not been set. Apps deployed to Azure are Production by default.

To set the environment in an Azure App Service app by using the portal:

  1. Select the app from the App Services page.
  2. In the Settings group, select Configuration.
  3. In the Application settings tab, select New application setting.
  4. In the Add/Edit application setting window, provide ASPNETCORE_ENVIRONMENT for the Name. For Value, provide the environment (for example, Staging).
  5. Select the Deployment slot setting checkbox if you wish the environment setting to remain with the current slot when deployment slots are swapped. For more information, see Set up staging environments in Azure App Service in the Azure documentation.
  6. Select OK to close the Add/Edit application setting dialog.
  7. Select Save at the top of the Configuration page.

Azure App Service automatically restarts the app after an app setting is added, changed, or deleted in the Azure portal.

Windows - Set environment variable for a process

Environment values in launchSettings.json override values set in the system environment.

To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, use the following commands at a command prompt or in PowerShell:

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

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

Windows - Set environment variable globally

The preceding commands set ASPNETCORE_ENVIRONMENT only for processes launched from that command window.

To set the value globally in Windows, use either of the following approaches:

  • Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    System Advanced Properties

    ASPNET Core Environment Variable

  • Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    • setx ASPNETCORE_ENVIRONMENT Staging /M

      The /M switch sets the environment variable at the system level. If the /M switch isn't used, the environment variable is set for the user account.

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

      The Machine option sets the environment variable at the system level. If the option value is changed to User, the environment variable is set for the user account.

When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set. Environment values in launchSettings.json override values set in the system environment.

Windows - Use web.config

To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Set environment variables section of xref:host-and-deploy/iis/web-config#set-environment-variables.

Windows - IIS deployments

Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. This approach sets the environment in web.config when the project is published:

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

To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of Environment Variables <environmentVariables>. When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use one of the following approaches to have the new value picked up by apps:

  • Execute net stop was /y followed by net start w3svc from a command prompt.
  • Restart the server.

macOS

Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Staging

Machine-level environment variables are set in the .bashrc or .bash_profile file. Edit the file using any text editor. Add the following statement:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

For Linux distributions, use the export command at a command prompt for session-based variable settings and the bash_profile file for machine-level environment settings.

Set the environment in code

To set the environment in code, use WebApplicationOptions.EnvironmentName when creating WebApplicationBuilder, as shown in the following example:

[!code-csharp]

For more information, see xref:fundamentals/host/generic-host#environmentname.

Configuration by environment

To load configuration by environment, see xref:fundamentals/configuration/index#json-configuration-provider.

Configure services and middleware by environment

Use WebApplicationBuilder.Environment to conditionally add services or middleware depending on the current environment. The project template includes an example of code that adds middleware only when the current environment isn't Development:

[!code-csharp]

Additional resources

::: moniker-end

::: moniker range="< aspnetcore-6.0"

By Rick Anderson and Kirk Larkin

ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Environments

To determine the runtime environment, ASP.NET Core reads from the following environment variables:

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENT when xref:Microsoft.Extensions.Hosting.GenericHostBuilderExtensions.ConfigureWebHostDefaults* is called. The default ASP.NET Core web app templates call ConfigureWebHostDefaults. The ASPNETCORE_ENVIRONMENT value overrides DOTNET_ENVIRONMENT.

IHostEnvironment.EnvironmentName can be set to any value, but the following values are provided by the framework:

The following code:

  • Calls UseDeveloperExceptionPage when ASPNETCORE_ENVIRONMENT is set to Development.
  • Calls UseExceptionHandler when the value of ASPNETCORE_ENVIRONMENT is set to Staging, Production, or Staging_2.
  • Injects xref:Microsoft.AspNetCore.Hosting.IWebHostEnvironment into Startup.Configure. This approach is useful when the app only requires adjusting Startup.Configure for a few environments with minimal code differences per environment.
  • Is similar to the code generated by the ASP.NET Core templates.

[!code-csharp]

The Environment Tag Helper uses the value of IHostEnvironment.EnvironmentName to include or exclude markup in the element:

[!code-cshtml]

The About page from the sample code includes the preceding markup and displays the value of IWebHostEnvironment.EnvironmentName.

On Windows and macOS, environment variables and values aren't case-sensitive. Linux environment variables and values are case-sensitive by default.

Create EnvironmentsSample

The sample code used in this document is based on a Razor Pages project named EnvironmentsSample.

The following code creates and runs a web app named EnvironmentsSample:

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

When the app runs, it displays some of the following output:

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

Development and launchSettings.json

The development environment can enable features that shouldn't be exposed in production. For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Environment values set in launchSettings.json override values set in the system environment.

The launchSettings.json file:

  • Is only used on the local development machine.
  • Is not deployed.
  • contains profile settings.

The following JSON shows the launchSettings.json file for an ASP.NET Core web project named EnvironmentsSample created with Visual Studio or dotnet new:

[!code-json]

The preceding markup contains two profiles:

  • IIS Express: The default profile used when launching the app from Visual Studio. The "commandName" key has the value "IISExpress", therefore, IISExpress is the web server. You can set the launch profile to the project or any other profile included. For example, in the image below, selecting the project name launches the Kestrel web server.

    IIS Express launch on menu

  • EnvironmentsSample: The profile name is the project name. This profile is used by default when launching the app with dotnet run. The "commandName" key has the value "Project", therefore, the Kestrel web server is launched.

The value of commandName can specify the web server to launch. commandName can be any one of the following:

  • IISExpress : Launches IIS Express.
  • IIS : No web server launched. IIS is expected to be available.
  • Project : Launches Kestrel.

The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file. Changes made to project profiles may not take effect until the web server is restarted. Kestrel must be restarted before it can detect changes made to its environment.

Project Properties Setting Environment variables

The following launchSettings.json file contains multiple profiles:

[!code-json]

Profiles can be selected:

  • From the Visual Studio UI.

  • Using the dotnet run command in a command shell with the --launch-profile option set to the profile's name. This approach only supports Kestrel profiles.

    dotnet run --launch-profile "SampleApp"

[!WARNING] launchSettings.json shouldn't store secrets. The Secret Manager tool can be used to store secrets for local development.

When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. The following example sets several Host configuration values environment variables:

[!code-json]

The .vscode/launch.json file is only used by Visual Studio Code.

Production

The production environment should be configured to maximize security, performance, and application robustness. Some common settings that differ from development include:

  • Caching.
  • Client-side resources are bundled, minified, and potentially served from a CDN.
  • Diagnostic error pages disabled.
  • Friendly error pages enabled.
  • Production logging and monitoring enabled. For example, using Application Insights.

Set the environment

It's often useful to set a specific environment for testing with an environment variable or platform setting. If the environment isn't set, it defaults to Production, which disables most debugging features. The method for setting the environment depends on the operating system.

When the host is built, the last environment setting read by the app determines the app's environment. The app's environment can't be changed while the app is running.

The About page from the sample code displays the value of IWebHostEnvironment.EnvironmentName.

Azure App Service

xref:Microsoft.Extensions.Hosting.Environments.Production is the default value if DOTNET_ENVIRONMENT and ASPNETCORE_ENVIRONMENT have not been set. Apps deployed to azure are Production by default.

To set the environment in Azure App Service, perform the following steps:

  1. Select the app from the App Services blade.
  2. In the Settings group, select the Configuration blade.
  3. In the Application settings tab, select New application setting.
  4. In the Add/Edit application setting window, provide ASPNETCORE_ENVIRONMENT for the Name. For Value, provide the environment (for example, Staging).
  5. Select the Deployment slot setting checkbox if you wish the environment setting to remain with the current slot when deployment slots are swapped. For more information, see Set up staging environments in Azure App Service in the Azure documentation.
  6. Select OK to close the Add/Edit application setting window.
  7. Select Save at the top of the Configuration blade.

Azure App Service automatically restarts the app after an app setting is added, changed, or deleted in the Azure portal.

Windows

Environment values in launchSettings.json override values set in the system environment.

To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

Command prompt

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

PowerShell

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

The preceding command sets ASPNETCORE_ENVIRONMENT only for processes launched from that command window.

To set the value globally in Windows, use either of the following approaches:

  • Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    System Advanced Properties

    ASPNET Core Environment Variable

  • Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    Command prompt

    setx ASPNETCORE_ENVIRONMENT Staging /M

    The /M switch indicates to set the environment variable at the system level. If the /M switch isn't used, the environment variable is set for the user account.

    PowerShell

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

    The Machine option value indicates to set the environment variable at the system level. If the option value is changed to User, the environment variable is set for the user account.

When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set. Environment values in launchSettings.json override values set in the system environment.

web.config

To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Set environment variables section of xref:host-and-deploy/iis/web-config#set-environment-variables.

Project file or publish profile

For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. This approach sets the environment in web.config when the project is published:

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

Per IIS Application Pool

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

When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of the following approaches to have the new value picked up by apps:

  • Execute net stop was /y followed by net start w3svc from a command prompt.
  • Restart the server.

macOS

Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Staging

Machine-level environment variables are set in the .bashrc or .bash_profile file. Edit the file using any text editor. Add the following statement:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

For Linux distributions, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Set the environment in code

Call xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.UseEnvironment* when building the host. See xref:fundamentals/host/generic-host#environmentname.

Configuration by environment

To load configuration by environment, see xref:fundamentals/configuration/index#json-configuration-provider.

Environment-based Startup class and methods

Inject IWebHostEnvironment into the Startup class

Inject xref:Microsoft.AspNetCore.Hosting.IWebHostEnvironment into the Startup constructor. This approach is useful when the app requires configuring Startup for only a few environments with minimal code differences per environment.

In the following example:

  • The environment is held in the _env field.
  • _env is used in ConfigureServices and Configure to apply startup configuration based on the app's environment.

[!code-csharp]

Startup class conventions

When an ASP.NET Core app starts, the Startup class bootstraps the app. The app can define multiple Startup classes for different environments. The appropriate Startup class is selected at runtime. The class whose name suffix matches the current environment is prioritized. If a matching Startup{EnvironmentName} class isn't found, the Startup class is used. This approach is useful when the app requires configuring startup for several environments with many code differences per environment. Typical apps will not need this approach.

To implement environment-based Startup classes, create a Startup{EnvironmentName} classes and a fallback Startup class:

[!code-csharp]

Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

[!code-csharp]

Startup method conventions

Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services. If a matching Configure<EnvironmentName>Services or Configure<EnvironmentName> method isn't found, the ConfigureServices or Configure method is used, respectively. This approach is useful when the app requires configuring startup for several environments with many code differences per environment:

[!code-csharp]

Additional resources

::: moniker-end