Environment Variables in ASP.NET Core

Environment Variables are one of the sources from which ASP.NET Core reads the configuration values. In this tutorial, let us learn how to set Environment Variables in Windows, Mac, Linux, IIS Server, Visual Studio, Visual Studio Code & dotnet run. We also learn how to read them in ASP.NET core.

Setting the Environment Variables

How we set environment variable depends on the OS


There are three ways in which you can set the environment variable in Windows

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

Command Line Utility

Using the set command

use the set command to temporarily set the environment variable.

  1. It will affect the current shell
  2. change is immediate
  3. change is lost, when you close the shell
  4. will not affect any other shell

Using the setx command

The following command sets the variable for the current logged in user and the change is permanent.

But the changes are reflected only if you close the current window and open another window.

  1. setx creates the environment value permanently.
  2. The change will not affect the current shell or the shells that are already running.
  3. You need to open a new shell for the changes to become available.
  4. Only affects the current logged in user.
  5. To make the variable available to all users (machine-wide) use the setx with /m flag

The /m flag saves the changes globally (machine wise). Hence it will be available to all the users


PowerShell is the another way to change the Environment Variable

For temporary changes use the $Env. it is similar to the set command.

for Permanent changes use the [Environment]::SetEnvironmentVariable. Use the third argument to set the variable User wise or machine wise.

Windows GUI tools

You can update the environment variable using the Windows GUI tools. Search for edit environment variable and click on the option as shown below.

Add ASPNETCORE_ENVIRONMENT to environment Variables in windows

This will open the Environment variables window, where you can use the New button to add a new environment variable.

Add it to the User Variables if you want to set the variable only for the current logged in user or use the System variables for all the logged-in users.

Linux/ Mac

Use the export to temporarily set the Environment variable.

To check if it correctly set use the echo command

Remove the variable using the unset command

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

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

IIS Server

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

Use web.config

The sample web.config. is as shown below.

If you make changes to the web.config in the production server, you will lose the changes, when you publish again. Hence create a web.config file in the project root folder and update the environment variables. This way you will not loose the change.


The default configuration loads the environment variable after appsettings.json, appsettings.Environment.json, & user secrets. Therefore, any settings we set in the environment variable is overrides values from the above sources

Hierarchical keys

You can set the Hierarchical keys by using the __ double underscore. You can also use double colon (:), but it may not support it.

We can read the configuration using the configuration service.


EnvironmentVariablesConfigurationProvider is the Configuration Provider. It contains the extension method AddEnvironmentVariables which is responsible loading the Environment Variables.

AddEnvironmentVariables takes one optional parameter prefix. When specified the method will load only those variables, which begins with that prefix

For Example consider the following environment variables

The method AddEnvironmentVariables(prefix:"settings_"), will load only the first two variable. The prefix is stripped off when the configuration key-value pairs are read.

Hosting Environment Variable

ASP.NET Core apps configure and launch a host. The host is responsible for starting the app and running it. It is created when the application starts.

The Host also needs to be configured. The ASP.NET core also uses the environment variables to configure the host. These environment variables are prefixed with ASPNETCORE_{configurationKey}. For Example ASPNETCORE_ENVIRONMENT

These Hosting Configurations are loaded at the app startup and even before the default configurations are loaded.


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