diff --git a/docs/core/extensions/configuration.md b/docs/core/extensions/configuration.md index b83db3d94099a..1bea25df9ef2d 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,14 @@ 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 + +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"::: + +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: 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}"); + } +}