Aspnetcore.docs: Does IIS use ASPNETCORE_ENVIRONMENT?

[norachuga]

The documentation is unclear on whether IIS uses ASPNETCORE_ENVIRONMENT or not.

At the opening of the Windows section, it describes how to set it for the current session for dotnet run. It then describes how to set it globally on Windows, without making clear if this still applies specifically to dotnet run.

After this, there is a section for web.config and IIS Application Pool. Both of these items address setting environment on individual apps. It is unclear if these sections are stating this in addition to being able to set it "globally on Windows".

I am currently unsuccessful in having applications hosted in IIS globally receive their environment from ASPNETCORE_ENVIRONMENT. Because of the ambiguity in the document, I am not sure if this is an error on my part or if it is not meant to work that way.

I would like to be able to set the environment one time on a server and have every application in IIS use that environment. I would appreciate clarification on whether this is achievable or not.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: ceffa6a2-770c-1cd9-5145-dcd423f9dd22
• Version Independent ID: 1cb5eb30-dd84-e5e1-5826-d74243fabf04
• Content: Use multiple environments in ASP.NET Core
• Content Source: aspnetcore/fundamentals/environments.md
• Service: unspecified
• Product: asp.net-core
• GitHub Login: @Rick-Anderson
• Microsoft Alias: riande

[guardrex]

Hi @norachuga ... Thanks for reaching out on the topic.

At the opening of the Windows section, it describes how to set it for the current session for dotnet run. It then describes how to set it globally on Windows, without making clear if this still applies specifically to dotnet run.

Yes, it still applies to dotnet run in a command window when set globally. The global setting applies unless you change it in the command window with the set command as described in the topic (or it's overridden in the app; I'll list the app overrides below).

When making a change in Windows OS with an open command window, you will need to open a new command window after setting it in Windows OS. Each command window you open takes a snapshot of the system environment and uses whatever env vars were loaded throughout the lifetime of that window. A given command window never finds out about new env vars that are set while the window is open.

There are three points to clarify:

1. The one you raised: How does setting it for the command window relate to setting it for the user or the system (globally).
2. It doesn't make clear the difference between setting it for the user account or for the system.
3. It describes set for the current window, but it doesn't address setx for permanently setting the env var (using the setx command is like doing it manually in Windows OS). In addition (same deal as the second point), it doesn't go on to talk about setx with the /M switch at an administrative command prompt to make the setting at the system level. setx used at a non-admin command prompt without the /M switch only sets it for the user account.

After this, there is a section for web.config and IIS Application Pool. Both of these items address setting environment on individual apps. It is unclear if these sections are stating this in addition to being able to set it "globally on Windows".

When the env var is set using web.config, it's setting it for the worker process. This will override whatever is set at the Windows OS system/user level. That's stated in the ASP.NET Core Module topic section ...

Environment variables set in this section take precedence over system environment variables.

The environment can be set by setting the env var from a launch.json/launchSettings.json file when running the app in an IDE like VS Code or VS. Note that running dotnet run also uses the launchSettings.json file, so the file can control what happens in the command window.

... same is true tho for the app overriding this. I'll list the overrides next.

An override can come from ...

• Setting it explicitly on the host builder with UseEnvironment.
• Loading it from a host config with UseConfiguration and AddJsonFile: "{ environment": "Development" }
• Setting it from the command line with UseConfiguration and AddCommandLine: dotnet run --environment Development.

... and two more points ...

• The app default is Production. If it isn't set anywhere by any means, the app's environment defaults to Production.
• When it comes to building the web host, the last setting wins. You can set the environment all over the place to different values ... and right before calling Build on the web host, you call UseEnvironment ... it will be the UseEnvironment setting that wins over all the other places it's set.

There's a lot of flexibility :smile:, but it's also a bit complex :cry:. I think the topic could use some kind of flowchart that shows the precedence of the settings from Windows OS system env var right down to app config.

I am currently unsuccessful in having applications hosted in IIS globally receive their environment from ASPNETCORE_ENVIRONMENT. ... I would like to be able to set the environment one time on a server and have every application in IIS use that environment.

Sounds like you are doing the right thing: You want to set the env var at the system level in Windows and restart the server. Then, make sure it isn't being overridden in the app's web host configuration.

It's been a while since I've worked with the setting using this approach. I do a different thing with my apps and their config (I really don't like env vars and config files! :smile: lol). After investigation if you're still having trouble, I'll spin up an Azure VM and do some testing and see if I can repro your situation.

Let's use this issue to track the work to improve the documentation. Thanks again for opening the issue.

I won't be able to get to this for a few weeks. As u probably know, 2.1 is planned for release next week, so we're 😅 🏃 working hard to get 2.1 issues resolved at the moment. I'll get to this as soon as things calm down in a couple of weeks.

[norachuga]

and restart the server.

That....was the problem! I did not realize a restart was required to pick up changes to env vars.

I had followed the documentation to the letter and was not seeing any results, so I began to doubt whether IIS used env vars since it is not _explicitly_ stated.

[guardrex]

It's Step 2 of this ...

https://docs.microsoft.com/aspnet/core/host-and-deploy/iis#install-the-net-core-hosting-bundle

I suppose the expression "picks up a change to the system PATH" isn't clear enough: The system PATH is an env var. I think I should make that more explicit ... make it call out "environment variable" there.

I plan to do some work to address the things we discussed here, so let's leave this issue open to track the work. Thanks again for opening the issue.

[norachuga]

The document you linked is not very related to configuring environment transformation. In order for Step 2 to have worked for me, I would have needed to set ASPNETCORE_ENVIRONMENT in advance of installing the .NET Core Hosting Bundle.

I believe this would be best addressed by adding an alert before or after the pictures showing how to create the System Variable explaining that the system may need to be rebooted (or IIS restarted).

[!NOTE] In order for IIS to pick up changes to ASPNETCORE_ENVIRONMENT, restart the system or execute net stop was /y followed by net start w3svc from a command prompt.

[guardrex]

Yes, I see your point. When I get to the updates for Use multiple environments in ASP.NET Core, I'll make sure that the instructions are clarified there.

RE IIS: IIS needs C:\Program Files\dotnet\ on the PATH. It doesn't use ASPNETCORE_ENVIRONMENT directly. That's used by the app when the app starts. I just meant that one of the few (or the only place) that a system restart is suggested pertaining to env vars is in the IIS topic. As you say, that's not the right spot to deal with app config. It's a separate, but similar, concern.

I should be free in a week or two to address this. I'll ping u on the PR.

[vnellore]

Hi there. I ran into similar issues about trying to figure out how to best manage multiple environments with IIS hosting. The documentation was a bit inadequate. I added ASPNETCORE_ENVIRONMENT variable to my web.config and it worked. But I did not want to manage web.config for each environment. Since my servers are dedicated to an individual environment adding it globally to system env variables made sense. However that worked only after restarting the servers. This needs to be emphasized. Thank you!