Skip to content

Commit 99ce071

Browse files
CopilotCopilot
authored
Add breaking change documentation for preserving null values in configuration (#47742)
1 parent 7e35b03 commit 99ce071

File tree

3 files changed

+121
-0
lines changed

3 files changed

+121
-0
lines changed

‎docs/core/compatibility/10.0.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
4141

4242
| Title | Type of change | Introduced version |
4343
|-------|---------------------|--------------------|
44+
| [Null values preserved in configuration](extensions/10.0/configuration-null-values-preserved.md) | Behavioral change | Preview 7 |
4445
| [Message no longer duplicated in Console log output](extensions/10.0/console-json-logging-duplicate-messages.md) | Behavioral change | Preview 7 |
4546
| [ProviderAliasAttribute moved to Microsoft.Extensions.Logging.Abstractions assembly](extensions/10.0/provideraliasattribute-moved-assembly.md) | Source incompatible | Preview 4 |
4647
| [Removed DynamicallyAccessedMembers annotation from trim-unsafe Microsoft.Extensions.Configuration code](extensions/10.0/dynamically-accessed-members-configuration.md) | Binary incompatible | Preview 6 |

‎docs/core/compatibility/extensions/10.0/configuration-null-values-preserved.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: "Breaking change: Null values preserved in configuration"
3+
description: "Learn about the breaking change in .NET 10 where configuration providers now preserve null values instead of treating them as missing values."
4+
ms.date: 08/07/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/46890
7+
---
8+
9+
# Null values preserved in configuration
10+
11+
The .NET configuration binder retrieves configuration values via configuration providers and attempts to bind those values to object properties. Previously, when a configuration value was null, the binder treated it as if the value didn't exist at all, and therefore skipped the binding. In other words, it did not distinguish between `null` values and missing values. This behavior caused significant confusion for users who expected explicitly defined `null` values in their configuration to be respected and properly bound.
12+
13+
Additionally, the JSON configuration provider previously converted `null` values in the configuration to empty strings. This further contributed to confusion, as properties bound to these values would receive an empty string rather than the expected null.
14+
15+
This change addresses both issues. The JSON configuration provider now correctly reports `null` values without altering them, and the binder treats `null` values as valid inputs, binding them like any other value.
16+
17+
The update also includes improvements to support binding `null` values within arrays and enables binding of empty arrays.
18+
19+
## Version introduced
20+
21+
.NET 10 Preview 7
22+
23+
## Previous behavior
24+
25+
Previously, when a configuration value was `null`, the binder treated it as if the value didn't exist at all, and therefore skipped the binding. The system didn't distinguish between `null` values and missing values.
26+
27+
Additionally, the JSON configuration provider converted `null` values in the configuration to empty strings. This caused properties bound to these values to receive an empty string rather than the expected `null`.
28+
29+
Consider the following configuration file `appsettings.json` contents:
30+
31+
```json
32+
{
33+
"NullConfiguration": {
34+
"StringProperty": null,
35+
"IntProperty": null,
36+
"Array1": [null, null],
37+
"Array2": []
38+
}
39+
}
40+
```
41+
42+
And the corresponding binding code:
43+
44+
```csharp
45+
public class NullConfiguration
46+
{
47+
public NullConfiguration()
48+
{
49+
// Initialize with non-default value to
50+
// ensure binding overrides these values.
51+
StringProperty = "Initial Value";
52+
IntProperty = 123;
53+
}
54+
public string? StringProperty { get; set; }
55+
public int? IntProperty { get; set; }
56+
public string[]? Array1 { get; set; }
57+
public string[]? Array2 { get; set; }
58+
}
59+
60+
var configuration = new ConfigurationBuilder()
61+
.AddJsonFile("appsettings.json")
62+
.Build().GetSection("NullConfiguration");
63+
64+
// Now bind the configuration.
65+
NullConfiguration? result = configuration.Get<NullConfiguration>();
66+
67+
Console.WriteLine($"StringProperty: '{result!.StringProperty}', intProperty: {(result!.IntProperty.HasValue ? result!.IntProperty : "null")}");
68+
Console.WriteLine($"Array1: {(result!.Array1 is null ?
69+
"null" : string.Join(", ", result!.Array1.Select(a => $"'{(a is null ? "null" : a)}'")))}");
70+
Console.WriteLine($"Array2: {(result!.Array2 is null ?
71+
"null" : string.Join(", ", result!.Array2.Select(a => $"'{(a is null ? "null" : a)}'")))}");
72+
```
73+
74+
Output:
75+
76+
```txt
77+
StringProperty: '', intProperty: 123
78+
Array1: '', ''
79+
Array2: null
80+
```
81+
82+
Explanation of the output:
83+
84+
- `StringProperty`: The `null` value in the JSON was converted by the JSON provider into an empty string (""), overwriting the initial value.
85+
- `IntProperty`: Remained unchanged (123) because the provider converted `null` to an empty string, which couldn't be parsed as an `int?`, so the original value was retained.
86+
- `Array1`: Bound to an array containing two empty strings because each `null` array element was treated as an empty string.
87+
- `Array2`: Remained `null` since an empty array `[]` in the JSON was ignored by the binder.
88+
89+
## New behavior
90+
91+
Starting in .NET 10, `null` values are now properly bound to their corresponding properties, including array elements. Even empty arrays are correctly recognized and bound as empty arrays rather than being ignored.
92+
93+
Running the same code sample produces the following results using the JSON configuration provider:
94+
95+
```txt
96+
StringProperty: 'null', intProperty: null
97+
Array1: 'null', 'null'
98+
Array2:
99+
```
100+
101+
## Type of breaking change
102+
103+
This is a [behavioral change](../../categories.md#behavioral-change).
104+
105+
## Reason for change
106+
107+
The previous behavior was confusing and frequently led to user complaints. By addressing this issue, the configuration binding process is now more intuitive and consistent, reducing confusion and aligning the behavior with user expectations.
108+
109+
## Recommended action
110+
111+
If you prefer the previous behavior, you can adjust your configuration accordingly:
112+
113+
- When using the JSON configuration provider, replace `null` values with empty strings (`""`) to restore the original behavior, where empty strings are bound instead of `null`.
114+
- For other providers that support `null` values, remove the `null` entries from the configuration to replicate the earlier behavior, where missing values are ignored and existing property values remain unchanged.
115+
116+
## Affected APIs
117+
118+
- <xref:Microsoft.Extensions.Configuration> APIs

‎docs/core/compatibility/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ items:
5252
items:
5353
- name: Message no longer duplicated in Console log output
5454
href: extensions/10.0/console-json-logging-duplicate-messages.md
55+
- name: Null values preserved in configuration
56+
href: extensions/10.0/configuration-null-values-preserved.md
5557
- name: ProviderAliasAttribute moved to Microsoft.Extensions.Logging.Abstractions assembly
5658
href: extensions/10.0/provideraliasattribute-moved-assembly.md
5759
- name: Removed DynamicallyAccessedMembers annotation from trim-unsafe Microsoft.Extensions.Configuration code

0 commit comments

Comments
 (0)