Edit

ASPNET-prefixed environment variable precedence

  • Article

Starting in .NET 7, and only when using the WebApplicationBuilder host, command-line arguments and DOTNET_-prefixed environment variables override ASPNET_-prefixed environment variables when reading from default host configuration sources. These sources are used to read host variables, such as the content root path and environment name, when the WebApplicationBuilder is constructed and serve as a base for app configuration.

ASPNET_-prefixed environment variables now have the lowest precedence of all of the default host configuration sources for WebApplicationBuilder. For other hosts, such as ConfigureWebHostDefaults and WebHost.CreateDefaultBuilder, ASPNET_-prefixed environment variables still have the highest precedence.

Version introduced

ASP.NET Core 7.0

Previous behavior

ASPNET_-prefixed environment variables overrode command-line arguments and DOTNET_-prefixed environment variables when reading WebApplicationBuilder's default host configuration.

New behavior

Command-line arguments and DOTNET_-prefixed environment variables override ASPNET_-prefixed environment variables when reading WebApplicationBuilder's default host configuration.

Type of breaking change

This is a behavioral change.

Reason for change

This change was made to prevent environment variables from overriding explicit command-line arguments when reading host variables. The new behavior is more consistent with application configuration, which has always given command-line arguments the highest precedence.

If you were using ASPNETCORE_-prefixed environment variables to override command-line arguments or DOTNET_-prefixed environment variables, use something with a higher priority. This could mean using custom WebApplicationOptions, which overrides all default hosting configuration sources.

Affected APIs

See also