ASP.NET Core runtime environments

ASP.NET Core configures app behavior based on the runtime environment, which usually reflects where the app is running.

Apps usually run in the Development environment during local development and testing on a developer's machine with one set of configured behaviors. In contrast, they run in the Production environment when deployed to a server with a different set of configured behaviors. Any number of additional environments can be used, such as the Staging environment provided by the framework for staging an app prior to live deployment or other environments that developers create.

This article describes app runtime environments, how to use the environment to control app behavior, and how to set the environment.

For Blazor environments guidance, which adds to or supersedes the guidance in this article, see ASP.NET Core Blazor environments.

Environments

Although the environment can be any string value, the following environment values are provided by the framework:

• Development
• Staging
• Production

The Production environment is configured to maximize security, performance, and app reliability. Common developer settings and configuration that differ from the Development environment include:

• Enabling caching.
• Bundling and minifying client-side resources, along with potentially serving them from a CDN.
• Disabling diagnostic error pages and enabling friendly error pages.
• Enabling production logging and monitoring. For example, logging is enabled for Azure Application Insights.

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.

Logging

Output in the command shell of a running app at startup indicates the app's environment. In the following example, the app is running in the Staging environment:

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

Environment variables that determine the runtime environment

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

If the DOTNET_ENVIRONMENT and ASPNETCORE_ENVIRONMENT environment variables aren't set, the Production environment is the default environment.

On Windows and macOS, environment variable names aren't case-sensitive. Linux environment variables are case-sensitive.

Control code execution by environment

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

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

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

    ...
}

Within the app, the IHostEnvironment provides general information about the app's hosting environment, and the IHostEnvironment.EnvironmentName property indicates the app's current environment.

Control rendered content

Inject IHostEnvironment into a server-rendered Razor component and use the service's extension methods and EnvironmentName property to determine the environment for rendering content:

@inject IHostEnvironment Env

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

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

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

For Blazor Web Apps that require the environment to control client-side rendering, see Prerender ASP.NET Core Razor components.

Set the environment in a command shell when the app is run (dotnet run)

Use the -e|--environment option to set the environment:

dotnet run -e Staging

Set the environment with the launch settings file (launchSettings.json)

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

The launchSettings.json file:

• Is only used on the local development machine.
• Isn't deployed when the app is published.
• May contain multiple profiles, each configuring a different environment.

The following example sets the Staging environment for the https launch profile using the ASPNETCORE_ENVIRONMENT environment variable:

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

In Visual Studio, there are two approaches for setting the environment via launch profiles:

• Press Alt+Enter or select Properties after right-clicking the project in Solution Explorer. Select Debug > General, followed by selecting the Open debug launch profiles UI link.

• With the project selected in Solution Explorer, select {PROJECT NAME} Debug Properties from the Debug menu, where the {PROJECT NAME} placeholder is a project name.

The preceding approaches open the Launch Profiles dialog where you can edit the environment variable settings in 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.

Profiles can be selected in the Visual Studio UI next to the Start button (►).

When a solution contains multiple projects, only set the environment for the startup project.

Alternatively, use the dotnet run command with the -lp|--launch-profile option set to the profile's name. This approach only supports launch profiles based on the Project command.

dotnet run -lp "https"

When using Visual Studio Code with the C# Dev Kit for Visual Studio Code (Getting Started with C# in VS Code), launch profiles are picked up from the app's launchSettings.json file.

If the C# Dev Kit isn't used, set the ASPNETCORE_ENVIRONMENT environment variable in the .vscode/launch.json in the env section, along with any other environment variables set in the section:

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

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

Set the environment with 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 the Production environment, which disables most debugging features. The method for setting the environment depends on the operating system.

Azure App Service

Apps deployed to Azure App Service adopt the Production environment by default.

To set the ASPNETCORE_ENVIRONMENT environment variable, see the following resources in the Azure documentation:

• Configure an App Service app
• Set up staging environments in Azure App Service

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

Set environment variable for a process

To set the ASPNETCORE_ENVIRONMENT environment variable for the current session (command shell) when the app is started using dotnet run, use the following commands. After the environment variable is set, the app is started without a launch profile using the --no-launch-profile option.

1. In the command shell, set the environment variable using the appropriate approach for your operating system.

2. Execute the dotnet run command without using a launch profile:

   dotnet run --no-launch-profile
   

When using PowerShell, the preceding steps can be combined in the following two commands. The following example sets the Staging environment:

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

Set environment variable globally

Use the appropriate guidance for your operating system to set the ASPNETCORE_ENVIRONMENT environment variable.

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

Set the environment for apps deployed to IIS

To set the ASPNETCORE_ENVIRONMENT environment variable with the web.config file, see web.config file.

To set the environment variable on deployment to IIS, include the <EnvironmentName> property in the publish profile (.pubxml) or project file. The following example sets the environment in web.config to the Staging environment when the project is published:

<PropertyGroup>
  <EnvironmentName>Staging</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 Environment Variables <environmentVariables>. When the ASPNETCORE_ENVIRONMENT environment variable is set for an Application 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 either of the following approaches to have the new value take effect for running apps:

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

Docker

Set the app's environment using any of the approaches in this section.

Use a Dockerfile

Set the ASPNETCORE_ENVIRONMENT environment variable within the Dockerfile using the ENV instruction:

ENV ASPNETCORE_ENVIRONMENT=Staging

Use Docker Compose

For multi-service apps managed with Docker Compose, define ASPNETCORE_ENVIRONMENT environment variables within the docker-compose.yml file:

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

An environment set at runtime with Docker Compose overrides an environment set by the Dockerfile.

Use the docker run command

When running the Docker container with the docker run command, Set the ASPNETCORE_ENVIRONMENT environment variable with the -e|--env option:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

An environment set at runtime with docker run overrides an environment set by the Dockerfile.

Docker environment file

Set the ASPNETCORE_ENVIRONMENT environment variable using a Docker environment file (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Load the file with the --env-file option when executing the docker run command:

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

An environment set at runtime with docker run overrides an environment set by the Dockerfile.

Set the environment in the app's startup code

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

Load configuration by environment

To load configuration by environment, see Configuration in ASP.NET Core.

Access the environment from a Startup class

Use of a Startup class (Startup.cs) with Configure and ConfigureServices methods was required before the release of .NET 6 and remains supported.

Inject IWebHostEnvironment into the Startup constructor to control code execution. This approach is useful when the app requires configuring startup code for only a few environments with minimal code differences per environment.

In the following example, the environment is held in the _env field and controls code execution based on the app's environment:

public class Startup
{
    private readonly IWebHostEnvironment _env;

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

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

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

        ...
    }
}

Environment-specific Startup class

An app can define multiple Startup classes for different environments with the naming convention Startup{EnvironmentName} class, where the {ENVIRONMENT NAME} placeholder is the environment name.

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.

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

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Where the host builder is created, call HostingAbstractionsWebHostBuilderExtensions.UseStartup, which accepts an assembly name to load the correct Startup class:

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

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

Environment-specific Startup class methods

The Configure and ConfigureServices methods support environment-specific versions of the form Configure{ENVIRONMENT NAME} and Configure{ENVIRONMENT NAME}Services, where the {ENVIRONMENT NAME} placeholder is the environment name. If a matching environment name isn't found for the named methods, the ConfigureServices or Configure method is used, respectively.

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

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

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

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

Additional resources

• View or download sample code (how to download)
• App startup in ASP.NET Core
• Configuration in ASP.NET Core
• ASP.NET Core Blazor environments