ConfigurationBinder: Behavior change when binding arrays with invalid elements (.NET 6 → .NET 8)

[kyogo-hayashi]

Description

Hello, I have a question regarding the behavior of IConfiguration.Get().
In a .NET application, we use IConfiguration.Get() (which internally uses ConfigurationBinder) to read configuration values.
When upgrading the target framework from .NET 6 to .NET 8, and updating the Microsoft.Extensions.Configuration packages from 6.x to 8.x, we noticed that the binding behavior for array (or array-like) properties has changed.

1. What I already understand (Breaking change)

　　
I’m aware of the .NET 8 breaking change where:
ConfigurationBinder.Get<T>(..., options => options.ErrorOnUnknownConfiguration = true)

will now throw an exception when a value cannot be converted to the destination type.
However, the behavior I’m asking about is the default behavior of IConfiguration.Get() when no BinderOptions are specified.

2. What I would like to confirm

With the default IConfiguration.Get() (no options), the behavior when an array element fails type conversion seems to differ
between .NET 6 and .NET 8.
Is this behavior:

• an intended change in .NET 7/8+,a regression, or a documentation gap?

Reproduction Steps

Reproduction (simplified)

appsettings.json

{
  "ApiUrl": "https://example.com/api",
  "Timeout": 5,
  "OutputPath": "./output",
  "List": [
    {
      "Name": "A",
      "Address": "AA",
      "Interval": 10
    },
    {
      "Name": "B",
      "Address": "BB",
      "Interval": "a"
    }
  ]
} 

Settings classes

public class SampleSettings
{
    public string ApiUrl { get; set; }
    public int Timeout { get; set; }
    public string OutputPath { get; set; }
    public ListSetting[] List { get; set; }
}

public class ListSetting
{
    public string Name { get; set; }
    public string Address { get; set; }
    public int Interval { get; set; }
}

Loading method

public static SampleSettings LoadSettings(IConfiguration configuration)
{
    SampleSettings settings = configuration.Get<SampleSettings>();
    return settings;
}

Then, run the loading method shown above to bind the configuration.

Expected behavior

.NET 6 Expected behavior

List[0] = { Name = "A", Address = "AA", Interval = 10 }
List[1] = null   // Conversion failed but null placeholder remains (array length 2)

Actual behavior

.NET 8 Actual behavior

List[0] = { Name = "A", Address = "AA", Interval = 10 }
List[1] is skipped entirely (array length becomes 1)

Note: I also tested this behavior on .NET 10, and it behaves the same.

Regression?

No response

Known Workarounds

No response

Configuration

NET versions tested:

• .NET 6
• .NET 8

Other information

Additional notes (speculated cause)

After checking the public ConfigurationBinder implementation in dotnet/runtime, it appears that:

In .NET 6, the binder pre-allocated the array and attempted to bind each element, resulting in failed elements becoming null.
In .NET 8, the binder first collects only successfully bound elements into a list, and then materializes the final array afterwards.

This difference may explain why failed elements are no longer preserved as null, but instead skipped.
This is only an observation based on the public source code.

Questions

1. For the default IConfiguration.Get() (no BinderOptions),
   is it intended that elements which fail type conversion are now skipped rather than preserved as null?

2. If this is an intended behavior change,from which
   .NET version does this change originate?

If this is simply my misunderstanding or a documentation oversight, I apologize.
Thank you very much for your help.

[tarekgh]

This is an intentional behavior change. We made several changes to collection binding to improve overall behavior, as the previous behavior was incorrect and misleading. For example, when binding a value-type array (such as int[]), it was difficult to distinguish an invalid configuration value from a valid value of 0 after binding.
You can refer to PR #97777, which intentionally addressed this issue in response to user feedback and complaints about the old behavior. Let us know if you have any more questions.

[kyogo-hayashi]

Sorry for the late reply, and thank you very much for your response.

I now understand that this behavior is intentional.

If I may, I have two additional questions:

1. Do you have any plans to document this behavior explicitly in the official documentation?

2. In .NET 6, when binding array elements, any element that failed to bind was preserved as null.
   This made it possible to identify which specific element contained an invalid value based on its index.

   However, starting in .NET 8, invalid elements are skipped entirely, which changes the element ordering and
   makes it impossible to determine which index originally had the invalid value.

   For example, given the following configuration:

   ```appsettings.json
   {
     "ApiUrl": "https://example.com/api",
     "Timeout": 5,
     "OutputPath": "./output",
     "List": [
       {
         "Name": "A",
         "Address": "AA",
         "Interval": "a"
       },
       {
         "Name": "B",
         "Address": "BB",
         "Interval": 10
       }
     ]
   }

In .NET 6, the first element would be preserved as null (because "Interval": "a" cannot be converted to an integer),
and the second element would be successfully bound — meaning we could tell which element failed.
In .NET 8+, the invalid first element is skipped entirely, and only the second element remains in the resulting array.
As a result, the application cannot determine whether the successfully-bound element came from index 0 or index 1.
For applications that relied on the previous behavior (using preserved null positions for validation or error reporting),
what kind of mitigation or recommended approach does the .NET team envision for developers?
I understand that the new behavior is an intentional change, but I would appreciate any guidance or best practices
for handling scenarios like the above.
Thank you again for your time.

[rosebyte]

@kyogo-hayashi, thank you for the post, it raises a good point. The problem with preserving default values is that it then becomes indistinguishable whether the configuration was invalid or whether the default value was used. That said, do you think additional logging or an event source to subscribe to would be a reasonable alternative? If so, could you please create another issue proposing that directly?

[tarekgh]

Do you have any plans to document this behavior explicitly in the official documentation?

Sure, we can try to do that. For your point of view, which doc usually you review for the configuration behavior.

I understand that the new behavior is an intentional change, but I would appreciate any guidance or best practices for handling scenarios like the above.

I suggest you enable options.ErrorOnUnknownConfiguration = true at least in your development cycle. This will give you the chance to see which configuration is wrong and fix it.

[kyogo-hayashi]

@tarekgh @rosebyte
Thank you very much for your proposal and your response.

Sure, we can try to do that. For your point of view, which doc usually you review for the configuration behavior.

I usually refer to documentation such as the following when checking configuration behavior:

• API reference: https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.configurationbinder.get
• Compatibility / breaking change notes: https://learn.microsoft.com/dotnet/core/compatibility/8.0

I suggest you enable options.ErrorOnUnknownConfiguration = true at least in your development cycle. This will give you the chance to see which configuration is wrong and fix it.

Thank you.
I understanded that, for now, enabling options.ErrorOnUnknownConfiguration = true during development is the recommended approach.

[tarekgh]

I filed the breaking change doc issue dotnet/docs#51753.