ConfigurationBinder silently coerces null into default values for non-nullable typed properties (JSON configuration provider)

[Justin-Nietzel]

Description

Related: dotnet/docs#46890 [Breaking change]: Preserving Null Values in Configuration

In versions before 10.0, Microsoft.Extensions.Configuration would throw an Exception when attempting to parse a null value into a non-nullable value type.

// Exception message from Microsoft.Extensions.Configuration 9.0.17
Failed to convert configuration value at 'TestOption:TheDayOfTheWeek' to type 'System.DayOfWeek'.

Starting in version 10.0, null will be silently coerced into the default value for that property.

Reproduction Steps

Using the default settings for a file-based app will produce different behavior for versions of Microsoft.Extensions.Hosting before 10.0 because PublishAot is enabled by default.

This might a completely separate bug, but the behavior of Microsoft.Extensions.Configuration@9.0.17 depends on where AOT is enable or not. When enabled, it behaves like Microsoft.Extensions.Configuration@10.09. I'm not familiar with AOT, so I'm not sure if minor differences in behavior are acceptable or not.

// #:package Microsoft.Extensions.Hosting@9.0.17
#:package Microsoft.Extensions.Hosting@10.0.9
#:property TargetFramework=net10.0
#:property PublishAot=false

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using System.Text;

string jsonString1 =
$$"""
{
  "TestOption": {
    "TheDayOfTheWeek": null
  }
}
""";

TestJson(jsonString1);

static void TestJson(string jsonString)
{
    var builder = Host.CreateEmptyApplicationBuilder(null);
    builder.Configuration
        .AddJsonStream(new MemoryStream(Encoding.UTF8.GetBytes(jsonString)));
    builder.Services
        .AddOptions<TestOption>()
        .BindConfiguration("TestOption");
    var host = builder.Build();

    try
    {
        var options = host.Services.GetRequiredService<IOptions<TestOption>>().Value;
        Console.WriteLine(options.TheDayOfTheWeek);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.Message);
    }
}

public record TestOption
{
    public required DayOfWeek TheDayOfTheWeek { get; init; }
}

Expected behavior

InvalidOperationException with the message

Failed to convert configuration value at 'TestOption:TheDayOfTheWeek' to type 'System.DayOfWeek'.

Actual behavior

No InvalidOperationException is thrown and its message is written to the console.

Regression?

Yes, this was changed with .NET preview 7 according to dotnet/docs#46890.

Known Workarounds

No response

Configuration

Windows 11 Pro 25H2 (x64)
Dotnet 10.0.202
AOT Disabled (this makes a difference)

Other information

I personally prefer being as explicit as possible and differentiating between null and 0, but I don't think I can come up with a realistic use case where the distinction matters. The lack of any mention of non-nullable value types in dotnet/docs#46890 leads me to believe these changes were unintentional. It may be more appropriate to just update the documentation.

[tarekgh]

Thanks for the detailed report and repro.

This is working as expected in .NET 10, and the difference comes down to how a JSON null is represented in configuration, not a change in the binder's conversion logic.

Why .NET 9 threw

On .NET 9 the JSON configuration provider did not preserve null. It materialized a JSON null as an empty string "". So the section existed with the value "", and when the binder tried to convert "" into a non-nullable DayOfWeek, the conversion failed and you got:

Failed to convert configuration value at 'TestOption:TheDayOfTheWeek' to type 'System.DayOfWeek'.

In other words, the exception was a side effect of the value having been rewritten to "", not of the binder deliberately rejecting null.

Why .NET 10 does not throw

Starting in .NET 10 the JSON provider preserves null as an actual null value (the "Preserving Null Values in Configuration" change). The binder now sees a real null. When the binder encounters a configuration value that is present but null, it sets the target member to null. For a non-nullable value type, that null is coerced to default(T), so the property ends up at its default (DayOfWeek.Sunday, which is 0), and no exception is thrown.

You can confirm the conversion logic itself is unchanged: an explicit empty string still throws on both 9.0 and 10.0, and a valid value like "Monday" binds correctly on both. Only the storage of null changed.

I will admit you can argue this behavior is not that desirable. Silently coercing a present null into a default is easy to miss, and it is worth noting that an explicit null is not quite the same as an absent key: an absent key leaves any initialized value in place, whereas an explicit null overwrites it with the default. But this is how the binder has worked, and the change in .NET 10 simply lets it see the real null instead of a provider-rewritten "".

This is also the existing source generator behavior

The configuration source generator already behaves this way, even on .NET 9. That is why you saw the AOT build (which uses the source-generated binder) silently produce the default on 9.0 too. The .NET 10 change actually brings the reflection binder in line with the source generator, so the two are now consistent.

The old behavior was provider-dependent

It is worth stressing that the .NET 9 throwing behavior was specific to providers that rewrote null to "". It was not consistent across providers. For example, on .NET 9.0 with the in-memory provider (which stores a real null), the same scenario does not throw, it binds DayOfWeek.Sunday, exactly like .NET 10 with JSON:

var config = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?> { ["TestOption:TheDayOfTheWeek"] = null })
    .Build();
var opt = config.GetSection("TestOption").Get<TestOption>();
// .NET 9.0: opt.TheDayOfTheWeek == DayOfWeek.Sunday, no exception

So the previous JSON behavior was really an artifact of one provider's null handling rather than a guaranteed contract.

Given that the old behavior was provider-dependent and inconsistent with the source generator, I am inclined to treat the .NET 10 behavior as by-design. The most actionable follow-up here is likely a documentation update to call out this case for non-nullable value types.

[Justin-Nietzel]

Thanks for the background info. I observed a lot of what you mentioned while putting together the reproduction steps so this clarifies a lot for me. I agree, I also thought the most reasonable follow up action was some extra documentation regarding non-nullable value types.

Would you recommend updating dotnet/docs#46890 specifically, or would it be more appropriate to update some of the general documentation regarding configuration sources?

[tarekgh]

Thanks @Justin-Nietzel

I'll close this one and we can follow opening a PR to fix docs. Editing the breaking change doc will be better as most likely users will get into this page before hitting the actual docs.

https://github.com/dotnet/docs/blob/main/docs/core/compatibility/extensions/10.0/configuration-null-values-preserved.md

CC @gewarren

[tarekgh]

I opened dotnet/docs#54464 to address the ask.