Skip to content

Commit 0c62ae9

Browse files
guardrexguardrex
authored
Update the 'Bind an array' section (#36765)
1 parent 4486241 commit 0c62ae9

1 file changed

Lines changed: 44 additions & 146 deletions

File tree

  • aspnetcore/fundamentals/configuration

‎aspnetcore/fundamentals/configuration/index.md‎

Lines changed: 44 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
22
title: Configuration in ASP.NET Core
3+
ai-usage: ai-assisted
34
author: tdykstra
45
description: Learn how to use the Configuration API to configure app settings in an ASP.NET Core app.
56
monikerRange: '>= aspnetcore-3.1'
67
ms.author: tdykstra
78
ms.custom: mvc
8-
ms.date: 01/23/2026
9+
ms.date: 02/11/2026
910
uid: fundamentals/configuration/index
1011
---
1112
# Configuration in ASP.NET Core
@@ -1063,8 +1064,6 @@ Host.CreateDefaultBuilder(args)
10631064

10641065
::: moniker-end
10651066

1066-
For an additional example that uses a <xref:Microsoft.Extensions.Configuration.Memory.MemoryConfigurationProvider>, see the [Bind an array](#bind-an-array) section.
1067-
10681067
## Kestrel endpoint configuration
10691068

10701069
Kestrel-specific endpoint configuration overrides all [cross-server](xref:fundamentals/servers/index) endpoint configurations. Cross-server endpoint configurations include:
@@ -1230,7 +1229,7 @@ The <xref:Microsoft.Extensions.Configuration.ConfigurationBinder.Bind%2A?display
12301229

12311230
A configuration provider is added for `array.json` by calling [`AddJsonFile`](#json-configuration-provider).
12321231

1233-
The following code reads the configuration values:
1232+
The following code reads the configuration values.
12341233

12351234
`ArrayExample.cs`:
12361235

@@ -1249,8 +1248,6 @@ if (array is null)
12491248
throw new ArgumentNullException(nameof(array));
12501249
}
12511250

1252-
string output = String.Empty;
1253-
12541251
for (int j = 0; j < array.Entries?.Length; j++)
12551252
{
12561253
Console.WriteLine($"Index: {j} Value: {array.Entries[j]}");
@@ -1269,171 +1266,72 @@ Index: 4 Value: value50
12691266

12701267
In the preceding output, Index 3 has value `value40`, corresponding to `"4": "value40",` in `array.json`. The bound array indices are continuous and not bound to the configuration key index. The configuration binder isn't capable of binding `null` values or creating `null` entries in bound objects.
12711268

1272-
:::moniker range="< aspnetcore-6.0"
1269+
The missing configuration item for Index 3 can be supplied before binding to the `ArrayExample` instance by any configuration provider that reads the Index 3 key/value pair. In the following example, assume that the values provided by `array.json` in the preceding example are provided by an [in-memory collection](#memory-configuration-provider). The example shows how to load the Index 3 value from the [JSON Configuration Provider](#json-configuration-provider) before the collection is bound.
12731270

1274-
The following code loads the `array:entries` configuration with the <xref:Microsoft.Extensions.Configuration.MemoryConfigurationBuilderExtensions.AddInMemoryCollection%2A> extension method:
1271+
`value3.json`:
12751272

1276-
```csharp
1277-
public class Program
1273+
```json
12781274
{
1279-
public static void Main(string[] args)
1280-
{
1281-
CreateHostBuilder(args).Build().Run();
1282-
}
1283-
1284-
public static IHostBuilder CreateHostBuilder(string[] args)
1285-
{
1286-
var arrayDict = new Dictionary<string, string>
1287-
{
1288-
{"array:entries:0", "value0"},
1289-
{"array:entries:1", "value1"},
1290-
{"array:entries:2", "value2"},
1291-
// 3 Skipped
1292-
{"array:entries:4", "value4"},
1293-
{"array:entries:5", "value5"}
1294-
};
1295-
1296-
return Host.CreateDefaultBuilder(args)
1297-
.ConfigureAppConfiguration((hostingContext, config) =>
1298-
{
1299-
config.AddInMemoryCollection(arrayDict);
1300-
})
1301-
.ConfigureWebHostDefaults(webBuilder =>
1302-
{
1303-
webBuilder.UseStartup<Startup>();
1304-
});
1305-
}
1275+
"array:entries:3": "value30"
13061276
}
13071277
```
13081278

1309-
The following code reads the configuration in the `arrayDict` `Dictionary` and displays the values:
1279+
::: moniker range=">= aspnetcore-6.0"
13101280

13111281
```csharp
1312-
public class ArrayModel : PageModel
1282+
var configSettings = new Dictionary<string, string>
13131283
{
1314-
private readonly IConfiguration Config;
1315-
public ArrayExample _array { get; private set; }
1316-
1317-
public ArrayModel(IConfiguration config)
1318-
{
1319-
Config = config;
1320-
}
1321-
1322-
public ContentResult OnGet()
1323-
{
1324-
_array = Config.GetSection("array").Get<ArrayExample>();
1325-
string s = null;
1326-
1327-
for (int j = 0; j < _array.Entries.Length; j++)
1328-
{
1329-
s += $"Index: {j} Value: {_array.Entries[j]} \n";
1330-
}
1331-
1332-
return Content(s);
1333-
}
1334-
}
1335-
```
1336-
1337-
The preceding code returns the following output:
1284+
{ "array:entries:0", "value00" },
1285+
{ "array:entries:1", "value10" },
1286+
{ "array:entries:2", "value20" },
1287+
{ "array:entries:4", "value40" },
1288+
{ "array:entries:5", "value50" }
1289+
};
13381290

1339-
```text
1340-
Index: 0 Value: value0
1341-
Index: 1 Value: value1
1342-
Index: 2 Value: value2
1343-
Index: 3 Value: value4
1344-
Index: 4 Value: value5
1291+
builder.Configuration.AddInMemoryCollection(configSettings);
1292+
builder.Configuration.AddJsonFile("value3.json", optional: false,
1293+
reloadOnChange: false);
13451294
```
13461295

1347-
Index &num;3 in the bound object holds the configuration data for the `array:4` configuration key and its value of `value4`. When configuration data containing an array is bound, the array indices in the configuration keys are used to iterate the configuration data when creating the object. A null value can't be retained in configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip one or more indices.
1348-
1349-
The missing configuration item for index &num;3 can be supplied before binding to the `ArrayExample` instance by any configuration provider that reads the index &num;3 key/value pair. Consider the following `Value3.json` file from the sample download:
1350-
1351-
```json
1352-
{
1353-
"array:entries:3": "value3"
1354-
}
1355-
```
1296+
::: moniker-end
13561297

1357-
The following code includes configuration for `Value3.json` and the `arrayDict` `Dictionary`:
1298+
::: moniker range="< aspnetcore-6.0"
13581299

13591300
```csharp
1360-
public class Program
1361-
{
1362-
public static void Main(string[] args)
1363-
{
1364-
CreateHostBuilder(args).Build().Run();
1365-
}
1366-
1367-
public static IHostBuilder CreateHostBuilder(string[] args)
1301+
Host.CreateDefaultBuilder(args)
1302+
.ConfigureWebHostDefaults(webBuilder =>
13681303
{
1369-
var arrayDict = new Dictionary<string, string>
1304+
webBuilder.UseStartup<Startup>();
1305+
})
1306+
.ConfigureAppConfiguration(config =>
1307+
{
1308+
var configSettings = new Dictionary<string, string>
13701309
{
1371-
{"array:entries:0", "value0"},
1372-
{"array:entries:1", "value1"},
1373-
{"array:entries:2", "value2"},
1374-
// 3 Skipped
1375-
{"array:entries:4", "value4"},
1376-
{"array:entries:5", "value5"}
1310+
{ "array:entries:0", "value00" },
1311+
{ "array:entries:1", "value10" },
1312+
{ "array:entries:2", "value20" },
1313+
{ "array:entries:4", "value40" },
1314+
{ "array:entries:5", "value50" }
13771315
};
13781316

1379-
return Host.CreateDefaultBuilder(args)
1380-
.ConfigureAppConfiguration((hostingContext, config) =>
1381-
{
1382-
config.AddInMemoryCollection(arrayDict);
1383-
config.AddJsonFile("Value3.json",
1384-
optional: false, reloadOnChange: false);
1385-
})
1386-
.ConfigureWebHostDefaults(webBuilder =>
1387-
{
1388-
webBuilder.UseStartup<Startup>();
1389-
});
1390-
}
1391-
}
1317+
config.AddInMemoryCollection(configSettings);
1318+
config.AddJsonFile("value3.json", optional: false, reloadOnChange: false);
1319+
});
13921320
```
13931321

1394-
The following code reads the preceding configuration and displays the values:
1395-
1396-
```csharp
1397-
public class ArrayModel : PageModel
1398-
{
1399-
private readonly IConfiguration Config;
1400-
public ArrayExample _array { get; private set; }
1401-
1402-
public ArrayModel(IConfiguration config)
1403-
{
1404-
Config = config;
1405-
}
1406-
1407-
public ContentResult OnGet()
1408-
{
1409-
_array = Config.GetSection("array").Get<ArrayExample>();
1410-
string s = null;
1411-
1412-
for (int j = 0; j < _array.Entries.Length; j++)
1413-
{
1414-
s += $"Index: {j} Value: {_array.Entries[j]} \n";
1415-
}
1416-
1417-
return Content(s);
1418-
}
1419-
}
1420-
```
1322+
:::moniker-end
14211323

1422-
The preceding code returns the following output:
1324+
The preceding code results in the following bound array:
14231325

1424-
```text
1425-
Index: 0 Value: value0
1426-
Index: 1 Value: value1
1427-
Index: 2 Value: value2
1428-
Index: 3 Value: value3
1429-
Index: 4 Value: value4
1430-
Index: 5 Value: value5
1326+
```console
1327+
Index: 0 Value: value00
1328+
Index: 1 Value: value10
1329+
Index: 2 Value: value20
1330+
Index: 3 Value: value30
1331+
Index: 4 Value: value40
1332+
Index: 5 Value: value50
14311333
```
14321334

1433-
Custom configuration providers aren't required to implement array binding.
1434-
1435-
:::moniker-end
1436-
14371335
## Custom configuration provider
14381336

14391337
The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using [Entity Framework (EF)](/ef/core/).

0 commit comments

Comments
 (0)