You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/core/compatibility/extensions/7.0/config-bind-dictionary.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ ms.date: 08/02/2023
5
5
---
6
6
# Binding config to dictionary extends values
7
7
8
-
When binding a configuration using a <xref:System.Collections.Generic.Dictionary%602> object where the value is a mutable collection type, binding to the same key more than once now extends the values collection instead of replacing the whole collection with the new value.
8
+
When binding a configuration using a <xref:System.Collections.Generic.Dictionary`2> object where the value is a mutable collection type, binding to the same key more than once now extends the values collection instead of replacing the whole collection with the new value.
@@ -30,7 +31,7 @@ Given one or more configuration sources, the <xref:Microsoft.Extensions.Configur
30
31
31
32
## Configure console apps
32
33
33
-
.NET console applications created using the [dotnet new](../tools/dotnet-new.md) command template or Visual Studio by default *don't* expose configuration capabilities. To add configuration in a new .NET console application, [add a package reference](../tools/dotnet-package-add.md) to [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration). This package is the foundation for configuration in .NET apps. It provides the <xref:Microsoft.Extensions.Configuration.ConfigurationBuilder> and related types.
34
+
.NET console apps created using the [dotnet new](../tools/dotnet-new.md) command template or Visual Studio by default *don't* expose configuration capabilities. To add configuration in a new .NET console application, [add a package reference](../tools/dotnet-package-add.md) to [📦 Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration). This package is the foundation for configuration in .NET apps. It provides the <xref:Microsoft.Extensions.Configuration.ConfigurationBuilder> and related types.
- Calls the <xref:Microsoft.Extensions.Configuration.ConfigurationBuilder.Build> method to create an <xref:Microsoft.Extensions.Configuration.IConfiguration> instance.
42
43
- Writes the value of the `SomeKey` key to the console.
43
44
44
-
While this example uses an in-memory configuration, there are many configuration providers available, exposing functionality for file-based, environment variables, commandline arguments, and other configuration sources. For more information, see [Configuration providers in .NET](configuration-providers.md).
45
+
While this example uses an in-memory configuration, there are many configuration providers available, exposing functionality for file-based, environment variables, command-line arguments, and other configuration sources. For more information, see [Configuration providers in .NET](configuration-providers.md).
45
46
46
-
###Alternative hosting approach
47
+
## Alternative hosting approach
47
48
48
-
Commonly, your apps will do more than just read configuration. They'll likely use dependency injection, logging, and other services. The [.NET Generic Host](generic-host.md) approach is recommended for apps that use these services. Instead, consider [adding a package reference](../tools/dotnet-package-add.md) to [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting). Modify the *Program.cs* file to match the following code:
49
+
Commonly, your apps will do more than just read configuration. They'll likely use dependency injection, logging, and other services. The [.NET Generic Host](generic-host.md) approach is recommended for apps that use these services. Instead, consider [adding a package reference](../tools/dotnet-package-add.md) to [📦 Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting). Modify the *Program.cs* file to match the following code:
@@ -60,9 +61,9 @@ The <xref:Microsoft.Extensions.Hosting.Host.CreateApplicationBuilder(System.Stri
60
61
61
62
Adding a configuration provider overrides previous configuration values. For example, the [Command-line configuration provider](configuration-providers.md#command-line-configuration-provider) overrides all values from other providers because it's added last. If `SomeKey` is set in both *appsettings.json* and the environment, the environment value is used because it was added after *appsettings.json*.
62
63
63
-
###Binding
64
+
## Binding
64
65
65
-
One of the key advantages of using the .NET configuration abstractions is the ability to bind configuration values to instances of .NET objects. For example, the JSON configuration provider can be used to map *appsettings.json* files to .NET objects and is used with [dependency injection](dependency-injection/overview.md). This enables the [options pattern](options.md), which uses classes to provide strongly typed access to groups of related settings. The default binder is reflection-based, but there's a [source generator alternative](configuration-generator.md) that's easy to enable.
66
+
One of the key advantages of using the .NET configuration abstractions is the ability to *bind* configuration values to instances of .NET objects. For example, the JSON configuration provider can be used to map *appsettings.json* files to .NET objects and is used with [dependency injection](dependency-injection/overview.md). This enables the [options pattern](options.md), which uses classes to provide strongly typed access to groups of related settings. The default binder is reflection-based, but there's a [source generator alternative](configuration-generator.md) that's easy to enable.
66
67
67
68
.NET configuration provides various abstractions. Consider the following interfaces:
68
69
@@ -84,7 +85,7 @@ The binder can use different approaches to process configuration values:
84
85
> - Properties are ignored if they have private setters or their type can't be converted.
85
86
> - Properties without corresponding configuration keys are ignored.
86
87
87
-
####Binding hierarchies
88
+
### Binding hierarchies
88
89
89
90
Configuration values can contain hierarchical data. Hierarchical objects are represented with the use of the `:` delimiter in the configuration keys. To access a configuration value, use the `:` character to delimit a hierarchy. For example, consider the following configuration values:
90
91
@@ -110,7 +111,61 @@ The following table represents example keys and their corresponding values for t
110
111
|`"Parent:Child:Name"`|`"Example"`|
111
112
|`"Parent:Child:GrandChild:Age"`|`3`|
112
113
113
-
### Basic example
114
+
### Advanced binding scenarios
115
+
116
+
The configuration binder has specific behaviors and limitations when working with certain types. This section includes the following subsections:
117
+
118
+
-[Bind to dictionaries](#bind-to-dictionaries)
119
+
-[Dictionary keys with colons](#dictionary-keys-with-colons)
120
+
-[Bind to IReadOnly* types](#bind-to-ireadonly-types)
121
+
-[Bind with parameterized constructors](#bind-with-parameterized-constructors)
122
+
123
+
#### Bind to dictionaries
124
+
125
+
When you bind configuration to a <xref:System.Collections.Generic.Dictionary`2> where the value is a mutable collection type (like arrays or lists), repeated binds to the same key extend the collection values instead of replacing them.
For more information, see [Binding config to dictionary extends values](../compatibility/extensions/7.0/config-bind-dictionary.md).
132
+
133
+
#### Dictionary keys with colons
134
+
135
+
The colon (`:`) character is reserved as a hierarchy delimiter in configuration keys. This means you can't use colons in dictionary keys when binding configuration. If your keys contain colons (such as URLs or other formatted identifiers), the configuration system interprets them as hierarchy paths rather than literal characters. Consider the following workarounds:
136
+
137
+
- Use alternative delimiter characters (such as double underscores `__`) in your configuration keys and transform them programmatically if needed.
138
+
- Manually deserialize the configuration as raw JSON using <xref:System.Text.Json> or a similar library, which supports colons in keys.
139
+
- Create a custom mapping layer that translates safe keys to your desired keys with colons.
140
+
141
+
#### Bind to IReadOnly\* types
142
+
143
+
The configuration binder doesn't support binding directly to `IReadOnlyList<T>`, `IReadOnlyDictionary<TKey, TValue>`, or other read-only collection interfaces. These interfaces lack the mechanisms the binder needs to populate the collections.
144
+
145
+
To work with read-only collections, use mutable types for the properties that the binder populates, then expose them as read-only interfaces for consumers:
This approach allows the binder to populate the mutable `List<string>` while presenting an immutable interface to consumers through `IReadOnlyList<string>`.
154
+
155
+
#### Bind with parameterized constructors
156
+
157
+
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:
> The binder only supports types with a single public parameterized constructor. If a type has multiple public parameterized constructors, the binder cannot determine which one to use and binding will fail. Use either a single parameterized constructor or a parameterless constructor with property setters.
167
+
168
+
## Basic example
114
169
115
170
To access configuration values in their basic form, without the assistance of the _generic host_ approach, use the <xref:Microsoft.Extensions.Configuration.ConfigurationBuilder> type directly.
116
171
@@ -148,7 +203,7 @@ The `Settings` object is shaped as follows:
To access the `IConfiguration` value, you can rely again on the [`Microsoft.Extensions.Hosting`](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) NuGet package. Create a new console application, and paste the following project file contents into it:
154
209
@@ -173,7 +228,7 @@ When you run this application, the `Host.CreateApplicationBuilder` defines the b
173
228
> [!TIP]
174
229
> Using the raw `IConfiguration` instance in this way, while convenient, doesn't scale very well. When applications grow in complexity, and their corresponding configurations become more complex, we recommend that you use the [_options pattern_](options.md) as an alternative.
175
230
176
-
###Basic example with hosting and using the indexer API
231
+
## Basic example with hosting and using the indexer API
177
232
178
233
Consider the same _appsettings.json_ file contents from the previous example:
179
234
@@ -189,17 +244,17 @@ The values are accessed using the indexer API where each key is a string, and th
189
244
190
245
The following table shows the configuration providers available to .NET Core apps.
|[App secrets (secret manager)](/aspnet/core/security/app-secrets)| File in the user profile directory |
203
258
204
259
> [!TIP]
205
260
> The order in which configuration providers are added matters. When multiple configuration providers are used and more than one provider specifies the same key, the last one added is used.
0 commit comments