Document .NET 9 breaking change: environment variables now take precedence over runtimeconfig.json

[Copilot]

Starting in .NET 9, environment variables take precedence over runtimeconfig.json settings when both are present. Previously, runtimeconfig.json took precedence.

Changes

• New breaking change article (deployment/9.0/envvar-precedence.md)

  • Documents precedence reversal with concrete example using DOTNET_gcServer vs System.GC.Server
  • Provides migration guidance for environments with conflicting configurations

• Updated runtime config overview (runtime-config/index.md)

  • Updated configuration mechanisms table to reflect new precedence order
  • Added explicit note in environment variables section about .NET 9 behavior change

• Index updates

  • Added entry to TOC and 9.0 breaking changes index

Example

Before .NET 9:

// runtimeconfig.json
{ "System.GC.Server": true }

export DOTNET_gcServer=0  # Ignored - runtimeconfig.json wins

.NET 9+:

export DOTNET_gcServer=0  # Now takes precedence

This aligns .NET runtime configuration with standard configuration precedence patterns where environment variables override file-based settings.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: Environment variables take precedence in app runtime configuration settings</issue_title>
<issue_description>### Description

Starting with .NET 9, the priority of how app runtime configuration (https://learn.microsoft.com/dotnet/core/runtime-config/) is resolved has changed. If both an environment variable and a corresponding setting in the application's runtimeconfig.json (or project file) are provided, the environment variable takes precedence over the configuration file.

dotnet/runtime#121899

Version

.NET 9

Previous behavior

When both an environment variable and the corresponding setting in the application's runtimeconfig.json are set, the runtimeconfig.json took precedence.

New behavior

When both an environment variable and the corresponding setting in the application's runtimeconfig.json are set, the environment variable takes precedence.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

The new behaviour is more consistent with how configuration tends to work in .NET and elsewhere, with environment variables taking precedence.

Recommended action

If running in an environment with the environment variable set to a configuration value different than what is desired, either unset the environment variable or set it to the desired configuration value.

Feature area

Deployment

Affected APIs

No response

---

Associated WorkItem - 544017</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Breaking change]: Environment variables take precedence in app runtime configuration settings #50993

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/9.0.md	Breaking changes in .NET 9
docs/core/compatibility/deployment/9.0/envvar-precedence.md	Environment variables take precedence in app runtime configuration settings
docs/core/compatibility/toc.yml	docs/core/compatibility/toc
docs/core/extensions/globalization-icu.md	.NET globalization and ICU
docs/core/runtime-config/index.md	Windows
docs/core/tools/dotnet-environment-variables.md	.NET environment variables
docs/core/versions/selection.md	Select the .NET version to use

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.