ASP.NET Configuration Builders

https://learn.microsoft.com/aspnet/
Admin
ASP.NET Configuration Builders provide a modern and flexible mechanism for ASP.NET applications to...
Tokens:6,331
Snippets:38
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### SimpleJsonConfigBuilder Sectional mode JSON example

Source: https://learn.microsoft.com/aspnet/config-builder

Example JSON file used when jsonMode is Sectional. The top-level property names (like 'appSettings') match configuration section names, and each dictionary is applied only to that section. Nested properties are flattened with ':' as a delimiter.

```json
{
    "appSettings" : {
        "setting1" : "value1",
        "setting2" : "value2",
        "complex" : {
            "setting1" : "complex:value1",
            "setting2" : "complex:value2",
        }
    }
}
```

--------------------------------

### web.config with stripPrefix enabled

Source: https://learn.microsoft.com/aspnet/config-builder

Example web.config that uses stripPrefix="true" for both environment builders, allowing keys without the prefix in the config file. The prefix is still required in the environment source.

```XML
<configuration>

  <configSections>
    <section name="configBuilders"
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="AS_Environment" mode="Greedy" prefix="AppSetting_" 
           stripPrefix="true"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
      <add name="CS_Environment" mode="Greedy" prefix="ConnStr_" 
           stripPrefix="true"
            type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="AS_Environment">
    <add key="ServiceID" value="ServiceID value from web.config" />
    <add key="default" value="AppSetting_default value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="CS_Environment">
    <add name="default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>


```

--------------------------------

### web.config with two EnvironmentConfigBuilder entries using distinct prefixes

Source: https://learn.microsoft.com/aspnet/config-builder

Use this XML configuration to define two EnvironmentConfigBuilder instances in Greedy mode with distinct prefixes (AppSetting_ and ConnStr_) so that a flat environment variable source can populate both appSettings and connectionStrings sections. The configBuilders attributes on the appSettings and connectionStrings elements reference the respective builders. This approach allows reading both sections without updating the configuration file when environment variables are set.

```XML
<configuration>

  <configSections>
    <section name="configBuilders"
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment" />
      <add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="AS_Environment">
    <add key="AppSetting_ServiceID" value="ServiceID value from web.config" />
    <add key="AppSetting_default" value="AppSetting_default value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="CS_Environment">
    <add name="ConnStr_default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>



>
```

--------------------------------

### Custom KeyValueConfigBuilder implementation in C#

Source: https://learn.microsoft.com/aspnet/config-builder

Inherit from KeyValueConfigBuilder and implement GetValue and GetAllValues to provide custom key/value pairs. The base class handles substitution modes and prefix concerns. The GetValue method should be case-insensitive, and GetAllValues should return a collection of key/value pairs.

```csharp
using Microsoft.Configuration.ConfigurationBuilders;
using System.Collections.Generic;

public class MyCustomConfigBuilder : KeyValueConfigBuilder
{
    public override string GetValue(string key)
    {
        // Key lookup should be case-insensitive, because most key/value collections in 
        // .NET Framework config sections are case-insensitive.
        return "Value for given key, or null.";
    }

    public override ICollection<KeyValuePair<string, string>> GetAllValues(string prefix)
    {
        // Populate the return collection.
        return new Dictionary<string, string>() { { "one", "1" }, { "two", "2" } };
    }
}

```

--------------------------------

### C# code-behind reading appSettings and connectionStrings from configuration

Source: https://learn.microsoft.com/aspnet/config-builder

This C# code reads the appSettings and connectionStrings values from the configuration, using the keys defined in the web.config file. It sets properties for ServiceID, AppSetting_default, and ConString by accessing ConfigurationManager.AppSettings and ConfigurationManager.ConnectionStrings. The values come from environment variables if set, otherwise from the web.config file.

```C#
public partial class Contact : Page
{
    public string ServiceID { get; set; }
    public string AppSetting_default { get; set; }
    public string ConString { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        ServiceID = ConfigurationManager.AppSettings["AppSetting_ServiceID"];
        AppSetting_default = ConfigurationManager.AppSettings["AppSetting_default"];
        ConString = ConfigurationManager.ConnectionStrings["ConnStr_default"]
                                     ?.ConnectionString;
    }
}

```

--------------------------------

### KeyPerFileConfigBuilder XML configuration

Source: https://learn.microsoft.com/aspnet/config-builder

Configures the KeyPerFileConfigBuilder to read configuration values from files in a directory. The directoryPath attribute is required. Other attributes control prefix handling, key delimiters, and error behavior.

```xml
<add name="KeyPerFile"
    [mode|prefix|stripPrefix|tokenPattern]
    (directoryPath="PathToSourceDirectory")
    [ignorePrefix="ignore."]
    [keyDelimiter=":"]
    [optional="false"]
    type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />

```

--------------------------------

### web.config: Enable EnvironmentConfigBuilder in Strict mode

Source: https://learn.microsoft.com/aspnet/config-builder

Configures the EnvironmentConfigBuilder in Strict mode for appSettings and connectionStrings. The builder replaces values from environment variables when keys match; otherwise, values from web.config are used. Requires the configBuilders section declaration and the builder registration.

```XML
<configuration>

  <configSections>
    <section name="configBuilders" 
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="MyEnvironment"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="MyEnvironment">
    <add key="ServiceID" value="ServiceID value from web.config" />
    <add key="ServiceKey" value="ServiceKey value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="MyEnvironment">
    <add name="default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>


```

```C#
using System;
using System.Configuration;
using System.Web.UI;

namespace MyConfigBuilders
{
    public partial class About : Page
    {
        public string ServiceID { get; set; }
        public string ServiceKey { get; set; }
        public string ConString { get; set; }

        protected void Page_Load(object sender, EventArgs e)
        {
            ServiceID = ConfigurationManager.AppSettings["ServiceID"];
            ServiceKey = ConfigurationManager.AppSettings["ServiceKey"];
            ConString = ConfigurationManager.ConnectionStrings["default"]
                                            ?.ConnectionString;
        }
    }
}

```

--------------------------------

### C# code reading appSettings and connectionStrings

Source: https://learn.microsoft.com/aspnet/config-builder

C# code that reads the appSettings and connectionStrings from the preceding web.config. It sets properties from ConfigurationManager.AppSettings and ConnectionStrings, using null-conditional operator for the connection string.

```C#
public partial class About2 : Page
{
    public string ServiceID { get; set; }
    public string AppSetting_default { get; set; }
    public string ConString { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        ServiceID = ConfigurationManager.AppSettings["ServiceID"];
        AppSetting_default = ConfigurationManager.AppSettings["default"];
        ConString = ConfigurationManager.ConnectionStrings["default"]
                                        ?.ConnectionString;
    }
}

```

--------------------------------

### SimpleJsonConfigBuilder XML configuration

Source: https://learn.microsoft.com/aspnet/config-builder

Declares the SimpleJsonConfigBuilder in a configuration file. The jsonFile attribute is required and can use '~' to reference the app root. The optional attribute defaults to true, preventing exceptions if the file is missing. jsonMode defaults to Flat.

```xml
<add name="SimpleJson"
    [mode|prefix|stripPrefix|tokenPattern]
    jsonFile="~\config.json"
    [optional="true"]
    [jsonMode="(Flat|Sectional)"]
    type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Json" />
```

--------------------------------

### EnvironmentConfigBuilder XML configuration

Source: https://learn.microsoft.com/aspnet/config-builder

Adds the EnvironmentConfigBuilder to read values from environment variables. The name attribute is arbitrary, and no additional configuration options are available.

```XML
<add name="Environment"
    [mode|prefix|stripPrefix|tokenPattern] 
    type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Environment" />

```

--------------------------------

### UserSecretsConfigBuilder XML configuration

Source: https://learn.microsoft.com/aspnet/config-builder

Adds the UserSecretsConfigBuilder to read secrets from a file. Requires either userSecretsId or userSecretsFile attribute; userSecretsFile takes precedence if both are specified. The optional attribute defaults to true to prevent exceptions if the file is missing.

```XML
<add name="UserSecrets"
    [mode|prefix|stripPrefix|tokenPattern]
    (userSecretsId="{secret string, typically a GUID}" | userSecretsFile="~\secrets.file")
    [optional="true"]
    type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />

```

--------------------------------

### Secrets file XML format

Source: https://learn.microsoft.com/aspnet/config-builder

The secrets file format used by UserSecretsConfigBuilder. The XML formatting is an implementation detail and should not be relied upon.

```XML
<?xml version="1.0" encoding="utf-8" ?>
<root>
  <secrets ver="1.0">
    <secret name="secret key name" value="secret value" />
  </secrets>
</root>

```

--------------------------------

### AzureKeyVaultConfigBuilder XML configuration

Source: https://learn.microsoft.com/aspnet/config-builder

Configures the AzureKeyVaultConfigBuilder to read secrets from Azure Key Vault. The vaultName attribute is required unless uri is provided. Other attributes control vault connection and secret retrieval behavior.

```xml
<add name="AzureKeyVault"
    [mode|prefix|stripPrefix|tokenPattern]
    (vaultName="MyVaultName" |
     uri="https:/MyVaultName.vault.azure.net")
    [version="secrets version"]
    [preloadSecretNames="true"]
    type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Azure" />

```
Tokens:
Raw