In ASP.NET Core 10, when DOTNET_ENVIRONMENT and ASPNETCORE_ENVIRONMENT disagree, which one sets the environment under WebApplication.CreateBuilder, and why?
answer
- two prefixes, one configuration key
- the last source added wins
- ASPNETCORE_ variables are added first
- --environment beats both variables
- WebApplicationOptions.EnvironmentName overrides everything
basics
~10 sUnder WebApplication.CreateBuilder in ASP.NET Core 10, DOTNET_ENVIRONMENT wins. Both prefixes map to the same environment key, the DOTNET_ source is added after the ASPNETCORE_ one, and configuration returns the value from the last source.
solid answer
~40 s`WebApplicationBuilder` creates a `ConfigurationManager` and adds environment variables with the `ASPNETCORE_` prefix; the `HostApplicationBuilder` it wraps then adds the `DOTNET_`-prefixed variables, then the command-line arguments, and last the values from `WebApplicationOptions`. Prefixes are stripped, so both variables become the key `environment`, and configuration answers with the last source that has the key. The order from weakest to strongest is `ASPNETCORE_ENVIRONMENT`, `DOTNET_ENVIRONMENT`, `--environment`, then `WebApplicationOptions.EnvironmentName`. In ASP.NET Core 10 that means a stray `DOTNET_ENVIRONMENT` set machine-wide or in a base image silently overrides the `ASPNETCORE_ENVIRONMENT` your deployment sets, so an estate should standardise on one variable. Older answers say the opposite because the obsolete `WebHost` builder, and the ASP.NET Core 6 `WebApplication`, let `ASPNETCORE_ENVIRONMENT` win.
code
bash · 8 linesexport ASPNETCORE_ENVIRONMENT=Staging
export DOTNET_ENVIRONMENT=Development
dotnet FerryBooking.dll
# info: Microsoft.Hosting.Lifetime[0] Hosting environment: Development
dotnet FerryBooking.dll --environment Staging
# info: Microsoft.Hosting.Lifetime[0] Hosting environment: Staginggo deeper
Remember that both variables exist and that under WebApplication the DOTNET_ one wins when they disagree.
Walk through the order the builder adds ASPNETCORE_ variables, DOTNET_ variables, arguments and WebApplicationOptions, and why the last source wins.
Diagnose hosts where a machine-wide or image-level variable overrides the deployment's, and explain why UseEnvironment after CreateBuilder throws.
Set one estate-wide convention for the environment variable so web apps and workers on shared hosts cannot disagree.
## Two variables, one key ASP.NET Core reads the environment from the `environment` key of **host configuration**. Two environment variables can supply it: `ASPNETCORE_ENVIRONMENT`, the historic web-specific name, and `DOTNET_ENVIRONMENT`, the name every .NET host understands. The environment-variables configuration provider strips the prefix it was registered with, so both become the same key, and the question of which one wins is really the question of **which configuration source was added last**. ## The order the sources are added Reading `WebApplicationBuilder` and `HostApplicationBuilder` in ASP.NET Core 10 gives this sequence: 1. The `WebApplicationBuilder` constructor creates a `ConfigurationManager` and calls `AddEnvironmentVariables(prefix: "ASPNETCORE_")`. 2. It creates a `HostApplicationBuilder` over that configuration, which calls `AddEnvironmentVariables(prefix: "DOTNET_")`. 3. The host builder adds the command-line arguments, so `--environment Staging` is a source of its own. 4. Values from `WebApplicationOptions` (passed through `HostApplicationBuilderSettings`) are added last; a comment in the source states that these settings override all other configuration sources. 5. Only then does the host create its environment object, using the resolved name or `Environments.Production`. Because `IConfiguration` returns the value from the **last** provider that has a key, the effective precedence is the reverse of that list. | Source | Example | Beats | |---|---|---| | `WebApplicationOptions.EnvironmentName` | `EnvironmentName = "Staging"` in code | everything below | | Command-line argument | `--environment Staging` | both variables | | `DOTNET_ENVIRONMENT` | `DOTNET_ENVIRONMENT=Development` | `ASPNETCORE_ENVIRONMENT` | | `ASPNETCORE_ENVIRONMENT` | `ASPNETCORE_ENVIRONMENT=Staging` | nothing | ## Why it surprises people - **The name suggests otherwise.** Developers assume the ASP.NET Core-specific variable is the more specific and therefore stronger one. Configuration has no notion of specificity, only of order. - **History disagrees.** The ASP.NET Core docs record that under the ASP.NET Core 6 `WebApplication`, and under the `WebHost` builder (obsolete in 10 as `ASPDEPR008`), `ASPNETCORE_ENVIRONMENT` took precedence. Blog posts written then still circulate. - **One variable can be invisible.** `DOTNET_ENVIRONMENT` is often set for worker services or by a base container image, and nobody on the web team looks for it. ## Where this bites in production - A machine-wide `DOTNET_ENVIRONMENT=Production` on a shared staging host makes every web app there ignore its `ASPNETCORE_ENVIRONMENT=Staging`. - A base image that sets `DOTNET_ENVIRONMENT` overrides what the deployment manifest sets with the `ASPNETCORE_` name. - A service's start command that appends `--environment` overrides both variables, which is easy to miss when you only inspect the environment block. Pick **one** variable for the whole estate and document it. If services and web apps share hosts, `DOTNET_ENVIRONMENT` is the one both host types read: `HostApplicationBuilder` on its own adds only the `DOTNET_` prefix, while the `ASPNETCORE_` source is something `WebApplicationBuilder` adds. ## Checking which source won When the answer is not obvious, ask configuration itself. `builder.Configuration` is a `ConfigurationManager`, which implements `IConfigurationRoot`, and `IConfigurationRoot.GetDebugView()` prints every key with its value and the provider that supplied it. Look for the `environment` key: the provider name shows whether the winning value came from the environment-variables provider with the `ASPNETCORE_` prefix, the one with the `DOTNET_` prefix, the command line or an in-memory source. Two cautions apply: - The debug view lists configuration values, including secrets such as connection strings, so print it locally or behind a guarded diagnostics switch, never into production logs. - It explains the configuration key, while `builder.Environment.EnvironmentName` is the resolved environment; the two agree unless the key was empty and the host fell back to Production. ## Changing the environment after CreateBuilder The precedence list ends at `CreateBuilder` because the environment is frozen once it returns: it has already chosen the `appsettings.{Environment}.json` file, whether to load user secrets and whether to validate DI scopes. Calling `builder.WebHost.UseEnvironment("Staging")` or `builder.Host.UseEnvironment("Staging")` afterwards throws `NotSupportedException` with a message that the environment changed and that changing host configuration through `WebApplicationBuilder.WebHost` (or `.Host`) is not supported, pointing you to `WebApplication.CreateBuilder(WebApplicationOptions)`. Setting the same name again, in any letter case, does not throw. ```bash export ASPNETCORE_ENVIRONMENT=Staging export DOTNET_ENVIRONMENT=Development dotnet FerryBooking.dll # Hosting environment: Development dotnet FerryBooking.dll --environment Staging # Hosting environment: Staging ```
- What happens if Program.cs calls builder.WebHost.UseEnvironment("Staging") after CreateBuilder?It throws NotSupportedException saying the environment changed and that changing host configuration through WebApplicationBuilder.WebHost is not supported; builder.Host.UseEnvironment throws the same way. The name has already selected configuration files and defaults, so you pass WebApplicationOptions.EnvironmentName to CreateBuilder, or use --environment, instead.
- Does a worker service built on Host.CreateApplicationBuilder read ASPNETCORE_ENVIRONMENT?No. HostApplicationBuilder adds only DOTNET_-prefixed variables; the ASPNETCORE_ source is added by WebApplicationBuilder. A worker running beside a web app on the same host needs DOTNET_ENVIRONMENT or an --environment argument, which is one reason to standardise on DOTNET_ENVIRONMENT.
- ASPNETCORE_ENVIRONMENT always wins because the app is an ASP.NET Core app.
- Configuration keeps the first source that defines a key and ignores the rest.
- Setting the two variables to different values makes the host throw at startup.
- builder.WebHost.UseEnvironment can still switch the environment any time before Build().
Assumes ASP.NET Core 10 with WebApplication, where DOTNET_ENVIRONMENT wins; the docs record ASPNETCORE_ENVIRONMENT winning under the ASP.NET Core 6 WebApplication and under the WebHost builder, now obsolete as ASPDEPR008.