Document .runtimeconfig.dev.json configProperties precedence change in .NET 11

docs/core/compatibility/11.md

@@ -41,6 +41,12 @@ See [Breaking changes in ASP.NET Core 11](/aspnet/core/breaking-changes/11/overv
 |----------------------------------------------------------------|-------------------|
 | [DSA removed from macOS](cryptography/11/dsa-removed-macos.md) | Behavioral change |
 
+## Deployment
+
+| Title | Type of change    |
+|-------|-------------------|
+| [configProperties in .runtimeconfig.dev.json override .runtimeconfig.json](deployment/11/runtimeconfigdev-configproperties-precedence.md) | Behavioral change |
+
 <!--
 ## Entity Framework Core
 

docs/core/compatibility/deployment/11/runtimeconfigdev-configproperties-precedence.md

@@ -0,0 +1,74 @@
+---
+title: "Breaking change: configProperties in .runtimeconfig.dev.json override .runtimeconfig.json"
+description: "Learn about the breaking change in .NET 11 where configProperties in .runtimeconfig.dev.json override matching configProperties in .runtimeconfig.json."
+ms.date: 07/05/2026
+ai-usage: ai-assisted
+---
+
+# configProperties in .runtimeconfig.dev.json override .runtimeconfig.json
+
+If an app defines the same runtime `configProperties` key in both `.runtimeconfig.json` and `.runtimeconfig.dev.json`, the `.runtimeconfig.dev.json` value takes precedence.
+
+## Version introduced
+
+.NET 11 Preview 6
+
+## Previous behavior
+
+Previously, `.runtimeconfig.json` took precedence over `.runtimeconfig.dev.json` for duplicate `configProperties` keys.
+
+For example:
+
+```json
+// app.runtimeconfig.json
+{
+  "runtimeOptions": {
+    "configProperties": {
+      "System.GC.Concurrent": true
+    }
+  }
+}
+```
+
+```json
+// app.runtimeconfig.dev.json
+{
+  "runtimeOptions": {
+    "configProperties": {
+      "System.GC.Concurrent": false
+    }
+  }
+}
+```
+
+With this configuration, the runtime used `System.GC.Concurrent: true`.
+
+## New behavior
+
+To support development-time overrides in .NET 11, `.runtimeconfig.dev.json` takes precedence over `.runtimeconfig.json` for duplicate `configProperties` keys.
+
+Using the same example, the runtime now uses `System.GC.Concurrent: false`.
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change enables developers to override production settings during development without modifying production configuration files.
+
+For more information, see [dotnet/runtime issue #126606](https://github.com/dotnet/runtime/issues/126606).
+
+## Recommended action
+
+For predictable production behavior, only place development-time overrides in `.runtimeconfig.dev.json`.
+
+To prevent a development-time override, remove the duplicate key from `.runtimeconfig.dev.json`.
+
+## Affected APIs
+
+None.
+
+## See also
+
+- [.NET runtime configuration settings](../../../runtime-config/index.md)

docs/core/compatibility/toc.yml

@@ -38,6 +38,10 @@ items:
             items:
               - name: DSA removed from macOS
                 href: cryptography/11/dsa-removed-macos.md
+          - name: Deployment
+            items:
+              - name: configProperties in .runtimeconfig.dev.json override .runtimeconfig.json
+                href: deployment/11/runtimeconfigdev-configproperties-precedence.md
           - name: Extensions
             items:
               - name: IHost.RunAsync and IHost.StopAsync throw when a BackgroundService fails

docs/core/runtime-config/index.md

@@ -39,6 +39,10 @@ Specify runtime configuration options in the **configProperties** section of the
 }
 ```
 
+Starting in .NET 11, to support development-time overrides, the value in *[appname].runtimeconfig.dev.json* takes precedence when you define the same key in `configProperties` in both *[appname].runtimeconfig.dev.json* and *[appname].runtimeconfig.json*.
+
+For more information, see [configProperties in .runtimeconfig.dev.json override .runtimeconfig.json](../compatibility/deployment/11/runtimeconfigdev-configproperties-precedence.md).
+
 ### Example [appname].runtimeconfig.json file
 
 If you're placing the options in the *output* JSON file, nest them under the `runtimeOptions` property.