ASPNETCORE_ENVIRONMENT is an environment variable, which ASP.NET Core uses to identify the runtime environment. ASP.NET Core configuration system uses it to load different configurations for different stages of application like Development, Staging & Production, etc. In this tutorial, we will show what is ASPNETCORE_ENVIRONMENT and how to set its value while developing the application and while hosting the application, etc.


An application moves through different stages before it reaches the end-user. Each of these stages requires different requirements and configurations. For Example, we need to load different connection strings for development & Production. Similarly, we need to configure features like logging, minification, exception handling differently for different stages of the application.

To Load different configurations for different stages, ASP.NET Core needs to identify the stage or environment, in which the application is running. This is where it uses the ASPNETCORE_ENVIRONMENT environment variable.


The ASP.NET Core Configuration system automatically loads the ASPNETCORE_ENVIRONMENT variable during the application startup. It does so very early in the application (even before the creation of the host).

Open the program.cs and you will see the following code.

The purpose of the CreateHostBuilder is to build the host. To do that it invokes the CreateDefaultBuilder method. The following is the source code of CreateDefaultBuilder method.

The first line of code creates a WebHostBuilder.

The source code of the WebHostBuilder. The constructer method creates new HostingEnvironment. The next line loads the environment variables, which starts with ASPNETCORE_.,

The CreateDefaultBuilder method gets the value of the current environment from the HostingEnvironment.

The further down in the CreateDefaultBuilder method, you will see that ASP.NET core making use of the ASPNETCORE_ENVIRONMENT to load different configurations. For Example, it loads the appsettings.development.json if the environment is development & appsettings.production.json, when the production.

The .NET Core provides built-in support for development, staging, and production environment. We can also define our own custom environment.


How we set the environment variable depends on the OS. We covered this in our tutorial on how to set the environment variable in ASP.NET Core.

Windows OS

For Windows OS, you can use the

  1. Command-line utility
  2. PowerShell
  3. Windows GUI Tool

Temporarily. only for the current session

Permanent only for the current logged in user. You need to close the window and open the new window for changes to be effective

Same as above, but for all users (machine wise)


The following command creates the variable only for the current window. Changes is lost , when the window is closed.

The following creates the Permanent change. But you need to close and create a new window. Use the third argument to create the variable either for the current user / machine wise.

Windows GUI tools

Using the GUI tool is the easiest way to create the ASPNETCORE_ENVIRONMENT variable

Go to Control Panel -> System -> Advanced System Settings -> Environment Variables. You will see the following screen. Add the Variable either the User Variable or to system variables by clicking on the new button.

Edit environment Variables in Windows

Linux/ Mac

Use the export to temporarily set the Environment variable.

To save the variable permanently you need to consider the shell that you are using. The most used shell is the bash shell. But the latest version of Mac uses the Zsh Shell.

bash shell

  1. login shell will load /etc/profile~/.bash_profile~/.bash_login~/.profile in the order
  2. non-login interactive shell will load ~/.bashrc
  3. non-login non-interactive shell will load the configuration specified in the environment variable $BASH_ENV

Open the shell file in an editor and add the following at the bottom

Zsh Shell

Open /.zprofile and add the following command at the bottom

IIS Server

For the IIS Server use the web.config file to set the value of ASPNETCORE_ENVIRONMENT. Add the following under the aspNetCore node

Use web.config

The sample web.config. is as shown below.

changes made to the web.config directly are lost, when you run publish again.

There are three ways, you can solve this problem. Thanks to the

Modifying the project file (.CsProj) file

Adding the EnvironmentName Property in the publish profiles

You will find the publish profile in the folder Properties/PublishProfiles/<profilename.pubxml>.

Command line options using dotnet publish

Pass the property EnvironmentName as a command-line option to the dotnet publish command.

All the three methods will update the web.config, when you publish the application.

Visual Studio

If you are debugging the code using the visual studio, remember that it also loads the environment variables from the launchSettings.json. The settings from the launchSettings.json always overwrite any environment variable we define in the OS.

A typical launchsetting.json is as below. We can add any environment variable under the node environmentVariables. for each debug profile.

You read more about launchSettings.json & debug Profile

Visual Studio, loads the environment variables when it starts up. Hence if you make any changes to the environment variable, your application will not read it. You have to restart the Visual Studio to reload the environment variables

Visual Studio Code

The visual studio uses the .vscode/launch.json file for configuration. The file is as shown below. You can change the environment variable from the "env" node.

dotnet run

dotnet run command runs the application from the source code. It will pickups the environment variables from the OS. But if you make any changes to the environment variable, ensure that you close and reopen the shell

You can use the --launch-profile flag to specify the debug profile. In such case, the environment variable from the launchSettings.json, will take precedence over those from the OS


Using IWebHostEnvironment

You can read the ASPNETCORE_ENVIRONMENT by injecting the IWebHostEnvironment in the constructor of any class.

EnvironmentName: Read/write property used to get or set the name of the environment
IsDevelopment(): Returns true if the EnvironmentName is Development
IsStaging(): True if the EnvironmentName is Staging
IsProduction(): Returns true if the EnvironmentName is Production
IsEnvironment(string environmentName): Returns true if the passed argument
environmentName matches the current EnvironmentName

Environment Tag Helper

We can also display the content based on the value of the environment variable using the Environment Tag Helper.

For Example


  1. Multiple Environments
  2. Set the Hosting Environment

1 thought on “ASPNETCORE_ENVIRONMENT Variable in ASP.NET Core”

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to Top