From 0cd69504f625d06449d9fc32eac40276c7582d87 Mon Sep 17 00:00:00 2001 From: rosebyte Date: Thu, 27 Aug 2026 15:04:40 +0200 Subject: [PATCH 1/3] add ConfigurationIgnoreAttribute to docs --- docs/core/extensions/configuration.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/core/extensions/configuration.md b/docs/core/extensions/configuration.md index b83db3d94099a..56fde6363a5a5 100644 --- a/docs/core/extensions/configuration.md +++ b/docs/core/extensions/configuration.md @@ -1,7 +1,7 @@ --- title: Configuration description: Learn how to use the Configuration API to configure .NET applications. Explore various inbuilt configuration providers. -ms.date: 10/09/2024 +ms.date: 08/27/2026 ms.topic: overview ai-usage: ai-assisted --- @@ -118,6 +118,7 @@ The configuration binder has specific behaviors and limitations when working wit - [Bind to dictionaries](#bind-to-dictionaries) - [Dictionary keys with colons](#dictionary-keys-with-colons) - [Bind to IReadOnly* types](#bind-to-ireadonly-types) +- [Exclude properties from binding](#exclude-properties-from-binding) - [Bind with parameterized constructors](#bind-with-parameterized-constructors) #### Bind to dictionaries @@ -152,6 +153,22 @@ The configuration class implementation: This approach allows the binder to populate the mutable `List` while presenting an immutable interface to consumers through `IReadOnlyList`. +#### Exclude properties from binding + +Starting in .NET 11, apply to a property when you don't want the configuration binder to populate it. The reflection-based binder and the [configuration source generator](configuration-generator.md) both honour the attribute. + +```csharp +public sealed class AppOptions +{ + public string Endpoint { get; set; } = ""; + + [ConfigurationIgnore] + public string RuntimeValue { get; set; } = "calculated"; +} +``` + +If configuration contains values for both `Endpoint` and `RuntimeValue`, the binder updates `Endpoint` and leaves `RuntimeValue` at its existing value. + #### Bind with parameterized constructors Starting with .NET 7, the configuration binder supports binding to types with a single public parameterized constructor. This enables immutable types and records to be populated directly from configuration: From 1894a5b817da719a58ad3c6c8ff76b9a7d9af5a1 Mon Sep 17 00:00:00 2001 From: rosebyte Date: Thu, 27 Aug 2026 19:28:15 +0200 Subject: [PATCH 2/3] fixes --- docs/core/extensions/configuration.md | 12 ++------ .../ConfigurationIgnore.csproj | 14 +++++++++ .../ConfigurationIgnore/Program.cs | 29 +++++++++++++++++++ 3 files changed, 45 insertions(+), 10 deletions(-) create mode 100644 docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/ConfigurationIgnore.csproj create mode 100644 docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/Program.cs diff --git a/docs/core/extensions/configuration.md b/docs/core/extensions/configuration.md index 56fde6363a5a5..cc7e6c1db7385 100644 --- a/docs/core/extensions/configuration.md +++ b/docs/core/extensions/configuration.md @@ -155,17 +155,9 @@ This approach allows the binder to populate the mutable `List` while pre #### Exclude properties from binding -Starting in .NET 11, apply to a property when you don't want the configuration binder to populate it. The reflection-based binder and the [configuration source generator](configuration-generator.md) both honour the attribute. +If you don't want the configuration binder to populate a property, apply to it (available starting in .NET 11). Both the reflection-based binder and the [configuration source generator](configuration-generator.md) honor this attribute. -```csharp -public sealed class AppOptions -{ - public string Endpoint { get; set; } = ""; - - [ConfigurationIgnore] - public string RuntimeValue { get; set; } = "calculated"; -} -``` +:::code language="csharp" source="snippets/configuration/binding-scenarios/ConfigurationIgnore/Program.cs" id="AppOptions"::: If configuration contains values for both `Endpoint` and `RuntimeValue`, the binder updates `Endpoint` and leaves `RuntimeValue` at its existing value. diff --git a/docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/ConfigurationIgnore.csproj b/docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/ConfigurationIgnore.csproj new file mode 100644 index 0000000000000..1cdbbe9eee51c --- /dev/null +++ b/docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/ConfigurationIgnore.csproj @@ -0,0 +1,14 @@ + + + + Exe + net11.0 + enable + enable + + + + + + + diff --git a/docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/Program.cs b/docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/Program.cs new file mode 100644 index 0000000000000..041e625d3e45a --- /dev/null +++ b/docs/core/extensions/snippets/configuration/binding-scenarios/ConfigurationIgnore/Program.cs @@ -0,0 +1,29 @@ +// +using Microsoft.Extensions.Configuration; + +public sealed class AppOptions +{ + public string Endpoint { get; set; } = ""; + + [ConfigurationIgnore] + public string RuntimeValue { get; set; } = "calculated"; +} +// + +public static class Program +{ + public static void Main() + { + var configuration = new ConfigurationManager + { + [nameof(AppOptions.Endpoint)] = "https://localhost", + [nameof(AppOptions.RuntimeValue)] = "configured", + }; + + var options = new AppOptions(); + configuration.Bind(options); + + Console.WriteLine($"Endpoint: {options.Endpoint}"); + Console.WriteLine($"RuntimeValue: {options.RuntimeValue}"); + } +} From 8ce494ded20c6980e7e15629a8dcc36ab85bea5c Mon Sep 17 00:00:00 2001 From: rosebyte Date: Fri, 28 Aug 2026 15:08:57 +0200 Subject: [PATCH 3/3] remove unnecessary mention --- docs/core/extensions/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/extensions/configuration.md b/docs/core/extensions/configuration.md index cc7e6c1db7385..1bea25df9ef2d 100644 --- a/docs/core/extensions/configuration.md +++ b/docs/core/extensions/configuration.md @@ -155,7 +155,7 @@ This approach allows the binder to populate the mutable `List` while pre #### Exclude properties from binding -If you don't want the configuration binder to populate a property, apply to it (available starting in .NET 11). Both the reflection-based binder and the [configuration source generator](configuration-generator.md) honor this attribute. +If you don't want the configuration binder to populate a property, apply to it (available starting in .NET 11). :::code language="csharp" source="snippets/configuration/binding-scenarios/ConfigurationIgnore/Program.cs" id="AppOptions":::