As we all know, .NET 5 has been released few months back and now .NET 6 previews are also available. If you know this, then it is not a news for you that .NET Framework will not have any major version release and .NET basically is the new name for .NET Core.
The .NET Core web application uses environment variables to identify the logical environment for the running application. This article explains which environment variable is used for this purpose and what are various options to set that environment variable.
Environment Identifier in .NET (core)
The .NET 5 is now the latest version of .NET Core (hereafter referred to as .NET). And it uses JSON configuration file, appsettings.json. The ASPNETCORE_ENVIRONMENT is the environment variable which .NET uses to determine the name of environment.
Just to add up to the complications, there is one more environment variable DOTNET_ENVIRONMENT. This also serves the same purpose. If both environment variables are defined, then ASPNETCORE_ENVIRONMENT takes priority and it overrides the DOTNET_ENVIRONMENT value.
By default, 3 values and methods are provided by framework for ASPNETCORE_ENVIRONMENT:
- Development – you can use
IWebHostEnvironment.IsDevelopment()method to see if the code is running in development environment. - Staging – you can use
IWebHostEnvironment.IsStaging()method to see if the code is running in staging environment. - Production – The default value, if nothing is set on
DOTNET_ENVIRONMENTandASPNETCORE_ENVIRONMENT. You can useIWebHostEnvironment.IsProduction()method to see if the code is running in production environment.
But if you have more than 3 environments or the environment names are different, you can set the environment variable value to any string value(e.g. Test, Dev, Performance, Security, Load, etc.)
In order to check if the code is running in your environment, you can read the value of environment variable and check if it is the expected value.
How to set it ?
There are multiple ways to setup the environment variables. The environment variable can be setup either on machine level, so it would be applicable to all processes running on that machine OR it can be setup only on process level (or user level or session level).
Below are some ways to set the environment.
Local Debugging – launchsettings.json
When running application locally, you can use launchsettings.json file (in Properties folder), to set the environment variables. You can define multiple profiles in the JSON file as shown below:
You can also create the profiles and set the active profile by right clicking on the .NET Core web application project and then selecting Properties option from the context menu.
Command Line Tools
Windows command prompt or PowerShell command line can be used to set the ASPNETCORE_ENVIRONMENT as shown below.
You can check docs for further details.
Windows Control Panel
Search for Edit the system environment variables in the start menu and you should be able to see the option as shown below.
Then, click on Environment Variables button to change the environment variable for either user or for all users on the machine.
IIS App Pools – applicationHost.config
If you wish to deploy the web app in IIS, then you can set the environment variables on application pool level. If you go to applicationHost.config, it will have application pool specific XML configuration section. That section can contain list of environment variables as shown in below snapshot.
If you set the environment variable using this method, it would set the variable to be on process level. Meaning, other app pool can have different value for this environment variable.
I feel the disadvantage with this approach is – the file is not associated with application, but it is associated with whole IIS instance. So, if you also do not want to go with this approach and using IIS for hosing .NET Core app, then next option is probably better for you.
You can setup some scripts to automatically update the file. Alternatively you can also use IIS Manager UI to set the environment variables on the app pool.
Web.Config for IIS based deployments
If the .NET Core web application is being deployed in IIS, then the environment can also be set in web.config as shown below. This config file should be present at root of the application.
Azure Web Apps Environment
If you are using Azure App Service for deployed web app, then navigate to the App Service and then select Configuration under Settings.
Then under Application settings (the first tab), you can add a New application setting with name ASPNETCORE_ENVIRONMENT and set it to the value you want. Then hit on Save to persist the changes and restart the app service.
Code
The default ASP.NET Core web app templates call ConfigureWebHostDefaults, which uses ASPNETCORE_ENVIRONMENT variable. You can create your own method to configure the web host, and that code can set the environment variable.
There are multiple options for setting environment from code. You can either read it from some other file like json file or XML file or environment variables or command line.
In below code sample, the environment is being set by using UseEnvironment method. The value from command line is used to set the environment value.
NOTE
Note that the values set on system level are overridden by the values set in the launchSettings.json file. So, if you want to use the the values from system level or user level environment variables set by using command line or any other option, you need to specify --no-launch-profile switch in dotnet run command.
I have tried to cover some of of the ways that you would want to use for setting ASPNETCORE_ENVIRONMENT in real world projects. If I missed anything, please comment here to let me know which option you used for setting the environment variable.
Pingback: Applying Config Transformations In .NET Web Applications – The Code Blogger
Pingback: How To Create Environment Specific Startup Class In .NET – The Code Blogger
Hi!
Is there anywaoy to override the name of the variable? I need to use ASPNET_ENVIRONMENT instead of ASPNETCORE_ENVIRONMENT
Probably you can just add couple of lines of code to get value from ASPNET_ENVIRONMENT and then assign that value to ASPNETCORE_ENVIRONMENT variable. This code should be called before building the host for web app. I have not tried to test it, but I think conceptually something like this should work.
The code would be something like below:
I tried setting up environment variable using “Edit System Variables…” method but my application deployed in IIS is unable to pick them up. What could be that I am doing wrong. I really need to make it work that way?
When you configure environment variables, the account which reads it should have enough rights to do so. Most probably, I think app pool identity does not have rights to read the environment variables.
As your application is hosted in IIS, I would suggest to use applicationHost.config or web.config to set the environment variables – as this would enable you to set environment variables which are applicable to only concerned web app.
Hope this helps.
Hi Manoj,
Thanks for this informative blog.
I have a web api created by .net core 6.0. And I need to host it on one server with multiple appsetting configs (e.g. appsettings.test1.json, appsettings.test2.json, appsettings.test3.json). When I use dotnet publish command in gitlab-ci.yml, it publishes all the appsetting files. How and where I need to set the environment variable so that web api uses correct config json file.
Thanks in advance
Glad to know you found this helpful. Where are you publishing the output ? if you are using IaaS, then you need to set Env variable on that machine. If you are using Azure App Service for hosting web app, you can navigate to App Service Instance → All Settings → Application settings. So, it depends on which service you are using to host the app.