docs: Breaking change - ConfigurationBinder silently skips array elements that fail type conversion (.NET 8)

[Copilot]

• Create breaking change article at docs/core/compatibility/extensions/8.0/configurationbinder-skips-failed-array-elements.md
• Add entry to docs/core/compatibility/toc.yml under Extensions/8.0
• Add entry to docs/core/compatibility/8.0.md under Extensions section
• Code review completed and feedback addressed
• Add "See also" link from configurationbinder-exceptions.md to the new article

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: ConfigurationBinder silently skips array elements that fail type conversion instead of preserving null placeholders</issue_title>
<issue_description>## Description

Starting in .NET 8, ConfigurationBinder.Get<T>() / ConfigurationBinder.Bind() silently skips array or list elements whose values fail type conversion, resulting in a shorter collection. Previously in .NET 6/7, failed elements were preserved as null placeholders, maintaining the original array length.

This behavioral change affects any code that relies on array indices aligning with configuration indices, or that checks for null entries to detect binding failures.

Related runtime issue: dotnet/runtime#124169

The root cause is that the internal binding logic changed from pre-allocating the array and binding in-place (leaving null on failure) to first collecting successfully-bound elements into a list and then materializing the final array, which drops failed entries entirely.

Previous behavior

When binding an array/list property via IConfiguration.Get<T>() (with default BinderOptions), if an element contained a value that could not be converted to the target type (e.g., "a" for an int property), the element was preserved as a null placeholder in the resulting array. The array length matched the number of elements in configuration.

// appsettings.json
// "List": [
//   { "Name": "A", "Interval": 10 },
//   { "Name": "B", "Interval": "a" }   <-- invalid int
// ]

var settings = configuration.Get<SampleSettings>();
// .NET 6/7 result:
// settings.List.Length == 2
// settings.List[0] = { Name = "A", Interval = 10 }
// settings.List[1] = null  (conversion failed, but placeholder preserved)

New behavior

Starting in .NET 8, elements that fail type conversion are silently skipped. The resulting array only contains successfully-bound elements, and its length is shorter than the number of configuration entries.

var settings = configuration.Get<SampleSettings>();
// .NET 8+ result:
// settings.List.Length == 1
// settings.List[0] = { Name = "A", Interval = 10 }
// List[1] is gone entirely — no null placeholder

This behavior persists in .NET 9 and .NET 10 as well.

Type of breaking change

• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

The internal implementation of ConfigurationBinder was refactored in .NET 8. The binder changed from pre-allocating the target array and binding elements in-place (which left null on conversion failure) to collecting only successfully-bound elements into a temporary list before materializing the final array. This causes elements with conversion errors to be dropped instead of preserved. The previous behavior was also incorrect when binding to arrays of value types, such as int[]. For example, it could store 0 when encountering an invalid configuration value, and it would also store 0 when the actual configuration value was 0. This made it confusing and difficult to distinguish between a legitimate value and an error.

Recommended action

1. Enable ErrorOnUnknownConfiguration during development to catch invalid configuration values early:

   var settings = configuration.Get<SampleSettings>(options =>
       options.ErrorOnUnknownConfiguration = true);

   This will throw an InvalidOperationException when a value cannot be converted, making misconfiguration immediately visible rather than silently dropping elements. It is strongly recommended to enable this option at least during development and testing.

2. Validate array lengths after binding if your code depends on the number of elements matching the configuration source.

3. Fix invalid configuration values — ensure all values in your configuration files match the expected types (e.g., don't use "a" where an int is expected).

4. Use string properties with manual parsing if you need to gracefully handle unconvertible values and preserve all array entries.

Feature area

Extensions

Affected APIs

• Microsoft.Extensions.Configuration.ConfigurationBinder.Get<T>(IConfiguration)
• Microsoft.Extensions.Configuration.ConfigurationBinder.Get<T>(IConfiguration, Action<BinderOptions>)
• Microsoft.Extensions.Configuration.ConfigurationBinder.Bind(IConfiguration, object)
• Microsoft.Extensions.Configuration.ConfigurationBinder.Bind(IConfiguration, object, Action<BinderOptions>)
  </issue_description>

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

• Fixes [Breaking change]: ConfigurationBinder silently skips array elements that fail type conversion instead of preserving null placeholders #51753

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/8.0.md	docs/core/compatibility/8.0
docs/core/compatibility/extensions/8.0/configurationbinder-exceptions.md	docs/core/compatibility/extensions/8.0/configurationbinder-exceptions
docs/core/compatibility/extensions/8.0/configurationbinder-skips-failed-array-elements.md	docs/core/compatibility/extensions/8.0/configurationbinder-skips-failed-array-elements
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull request overview

Adds a new .NET 8 compatibility (breaking change) article for ConfigurationBinder array/list binding behavior and wires it into the compatibility navigation.

Changes:

• Added a new breaking-change article: “ConfigurationBinder silently skips invalid array elements”.
• Added the new article to the .NET 8 compatibility landing page list.
• Added the new article to the .NET 8 “Extensions” section in the compatibility TOC.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/core/compatibility/toc.yml	Adds the new breaking-change article to the .NET 8 Extensions TOC.
docs/core/compatibility/extensions/8.0/configurationbinder-skips-failed-array-elements.md	New breaking-change article describing array/list binding behavior for invalid elements.
docs/core/compatibility/8.0.md	Adds the new article to the .NET 8 compatibility index table.

---

You can also share your feedback on Copilot code review. Take the survey.

[gewarren]

@copilot Please add a "See also" link from configurationbinder-exceptions.md to this new article.

[Copilot]

@copilot Please add a "See also" link from configurationbinder-exceptions.md to this new article.

Added a "See also" section to configurationbinder-exceptions.md linking to the new article (commit c39f2e7).