Events
Nov 19, 11 PM - Nov 21, 11 PM
Join online sessions at Microsoft Ignite created to expand your skills and help you tackle today's complex issues.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
By Rick Anderson and Kirk Larkin
Note
This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see the .NET and .NET Core Support Policy. For the current release, see the .NET 9 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 9 version of this article.
Application configuration in ASP.NET Core is performed using one or more configuration providers. Configuration providers read configuration data from key-value pairs using a variety of configuration sources:
appsettings.json
This article provides information on configuration in ASP.NET Core. For information on using configuration in console apps, see .NET Configuration.
For Blazor configuration guidance, which adds to or supersedes the guidance in this node, see ASP.NET Core Blazor configuration.
ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management. The ASP.NET Core templates create a WebApplicationBuilder which contains the host. While some configuration can be done in both the host and the application configuration providers, generally, only configuration that is necessary for the host should be done in host configuration.
Application configuration is the highest priority and is detailed in the next section. Host configuration follows application configuration, and is described in this article.
ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:
var builder = WebApplication.CreateBuilder(args);
WebApplication.CreateBuilder initializes a new instance of the WebApplicationBuilder class with preconfigured defaults. The initialized WebApplicationBuilder
(builder
) provides default configuration for the app in the following order, from highest to lowest priority:
Development
environment.appsettings.{Environment}.json
using the JSON configuration provider. For example, appsettings.Production.json
and appsettings.Development.json
.The following list contains the default host configuration sources from highest to lowest priority for WebApplicationBuilder:
DOTNET_
-prefixed environment variables using the Environment variables configuration provider.ASPNETCORE_
-prefixed environment variables using the Environment variables configuration provider.For the .NET Generic Host and Web Host, the default host configuration sources from highest to lowest priority is:
ASPNETCORE_
-prefixed environment variables using the Environment variables configuration provider.DOTNET_
-prefixed environment variables using the Environment variables configuration provider.When a configuration value is set in host and application configuration, the application configuration is used.
The following variables are locked in early when initializing the host builders and can't be influenced by application config:
Development
, Production
, and Staging
Every other host setting is read from application config instead of host config.
URLS
is one of the many common host settings that is not a bootstrap setting. Like every other host setting not in the previous list, URLS
is read later from application config. Host config is a fallback for application config, so host config can be used to set URLS
, but it will be overridden by any configuration source in application config like appsettings.json
.
For more information, see Change the content root, app name, and environment and Change the content root, app name, and environment by environment variables or command line
The remaining sections in this article refer to application configuration.
The following code displays the enabled configuration providers in the order they were added:
public class Index2Model : PageModel
{
private IConfigurationRoot ConfigRoot;
public Index2Model(IConfiguration configRoot)
{
ConfigRoot = (IConfigurationRoot)configRoot;
}
public ContentResult OnGet()
{
string str = "";
foreach (var provider in ConfigRoot.Providers.ToList())
{
str += provider.ToString() + "\n";
}
return Content(str);
}
}
The preceding list of highest to lowest priority default configuration sources shows the providers in the opposite order they are added to template generated application. For example, the JSON configuration provider is added before the Command-line configuration provider.
Configuration providers that are added later have higher priority and override previous key settings. For example, if MyKey
is set in both appsettings.json
and the environment, the environment value is used. Using the default configuration providers, the Command-line configuration provider overrides all other providers.
For more information on CreateBuilder
, see Default builder settings.
Consider the following appsettings.json
file:
{
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
},
"MyKey": "My appsettings.json Value",
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The default JsonConfigurationProvider loads configuration in the following order:
appsettings.json
appsettings.{Environment}.json
: For example, the appsettings.Production.json
and appsettings.Development.json
files. The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. For more information, see Use multiple environments in ASP.NET Core.appsettings.{Environment}.json
values override keys in appsettings.json
. For example, by default:
appsettings.Development.json
configuration overwrites values found in appsettings.json
.appsettings.Production.json
configuration overwrites values found in appsettings.json
. For example, when deploying the app to Azure.If a configuration value must be guaranteed, see GetValue. The preceding example only reads strings and doesn’t support a default value.
Using the default configuration, the appsettings.json
and appsettings.{Environment}.json
files are enabled with reloadOnChange: true. Changes made to the appsettings.json
and appsettings.{Environment}.json
file after the app starts are read by the JSON configuration provider.
Comments in appsettings.json
and appsettings.{Environment}.json
files are supported using JavaScript or C# style comments.
The preferred way to read related configuration values is using the options pattern. For example, to read the following configuration values:
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
}
Create the following PositionOptions
class:
public class PositionOptions
{
public const string Position = "Position";
public string Title { get; set; } = String.Empty;
public string Name { get; set; } = String.Empty;
}
An options class:
Position
is not bound. The Position
field is used so the string "Position"
doesn't need to be hard coded in the app when binding the class to a configuration provider.The following code:
PositionOptions
class to the Position
section.Position
configuration data.public class Test22Model : PageModel
{
private readonly IConfiguration Configuration;
public Test22Model(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var positionOptions = new PositionOptions();
Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);
return Content($"Title: {positionOptions.Title} \n" +
$"Name: {positionOptions.Name}");
}
}
In the preceding code, by default, changes to the JSON configuration file after the app has started are read.
ConfigurationBinder.Get<T>
binds and returns the specified type. ConfigurationBinder.Get<T>
may be more convenient than using ConfigurationBinder.Bind
. The following code shows how to use ConfigurationBinder.Get<T>
with the PositionOptions
class:
public class Test21Model : PageModel
{
private readonly IConfiguration Configuration;
public PositionOptions? positionOptions { get; private set; }
public Test21Model(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
positionOptions = Configuration.GetSection(PositionOptions.Position)
.Get<PositionOptions>();
return Content($"Title: {positionOptions.Title} \n" +
$"Name: {positionOptions.Name}");
}
}
In the preceding code, by default, changes to the JSON configuration file after the app has started are read.
An alternative approach when using the options pattern is to bind the Position
section and add it to the dependency injection service container. In the following code, PositionOptions
is added to the service container with Configure and bound to configuration:
using ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<PositionOptions>(
builder.Configuration.GetSection(PositionOptions.Position));
var app = builder.Build();
Using the preceding code, the following code reads the position options:
public class Test2Model : PageModel
{
private readonly PositionOptions _options;
public Test2Model(IOptions<PositionOptions> options)
{
_options = options.Value;
}
public ContentResult OnGet()
{
return Content($"Title: {_options.Title} \n" +
$"Name: {_options.Name}");
}
}
In the preceding code, changes to the JSON configuration file after the app has started are not read. To read changes after the app has started, use IOptionsSnapshot.
Using the default configuration, the appsettings.json
and appsettings.{Environment}.json
files are enabled with reloadOnChange: true. Changes made to the appsettings.json
and appsettings.{Environment}.json
file after the app starts are read by the JSON configuration provider.
See JSON configuration provider in this document for information on adding additional JSON configuration files.
Consider the following which registers services and configures options:
using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<PositionOptions>(
builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
builder.Configuration.GetSection(ColorOptions.Color));
builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();
var app = builder.Build();
Related groups of registrations can be moved to an extension method to register services. For example, the configuration services are added to the following class:
using ConfigSample.Options;
using Microsoft.Extensions.Configuration;
namespace Microsoft.Extensions.DependencyInjection
{
public static class MyConfigServiceCollectionExtensions
{
public static IServiceCollection AddConfig(
this IServiceCollection services, IConfiguration config)
{
services.Configure<PositionOptions>(
config.GetSection(PositionOptions.Position));
services.Configure<ColorOptions>(
config.GetSection(ColorOptions.Color));
return services;
}
public static IServiceCollection AddMyDependencyGroup(
this IServiceCollection services)
{
services.AddScoped<IMyDependency, MyDependency>();
services.AddScoped<IMyDependency2, MyDependency2>();
return services;
}
}
}
The remaining services are registered in a similar class. The following code uses the new extension methods to register the services:
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddConfig(builder.Configuration)
.AddMyDependencyGroup();
builder.Services.AddRazorPages();
var app = builder.Build();
Note: Each services.Add{GROUP_NAME}
extension method adds and potentially configures services. For example, AddControllersWithViews adds the services MVC controllers with views require, and AddRazorPages adds the services Razor Pages requires.
Configuration data guidelines:
By default, the user secrets configuration source is registered after the JSON configuration sources. Therefore, user secrets keys take precedence over keys in appsettings.json
and appsettings.{Environment}.json
.
For more information on storing passwords or other sensitive data:
Non-prefixed environment variables are environment variables other than those prefixed by ASPNETCORE_
or DOTNET_
. For example, the ASP.NET Core web application templates set "ASPNETCORE_ENVIRONMENT": "Development"
in launchSettings.json
. For more information on ASPNETCORE_
and DOTNET_
environment variables, see:
ASPNETCORE_
-prefixed and DOTNETCORE_
-prefixed environment variables.DOTNET_
environment variables used outside of Microsoft.Extensions.Hosting.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json
, appsettings.{Environment}.json
, and user secrets. Therefore, key values read from the environment override values read from appsettings.json
, appsettings.{Environment}.json
, and user secrets.
The :
separator doesn't work with environment variable hierarchical keys on all platforms. For example, the :
separator is not supported by Bash. The double underscore, __
, is:
:
.The following commands:
dotnet run
command must be run in the project directory.set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run
The preceding environment settings:
The following setx commands can be used to set the environment keys and values on Windows. Unlike set
, setx
settings are persisted. /M
sets the variable in the system environment. If the /M
switch isn't used, a user environment variable is set.
setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M
To test that the preceding commands override appsettings.json
and appsettings.{Environment}.json
:
dotnet run
.Call AddEnvironmentVariables with a string to specify a prefix for environment variables:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
var app = builder.Build();
In the preceding code:
builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_")
is added after the default configuration providers. For an example of ordering the configuration providers, see JSON configuration provider.MyCustomPrefix_
prefix override the default configuration providers. This includes environment variables without the prefix.The prefix is stripped off when the configuration key-value pairs are read.
The following commands test the custom prefix:
set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run
The default configuration loads environment variables and command line arguments prefixed with DOTNET_
and ASPNETCORE_
. The DOTNET_
and ASPNETCORE_
prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. For more information on host and app configuration, see .NET Generic Host.
On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service application settings are:
For more information, see Azure Apps: Override app configuration using the Azure Portal.
See Connection string prefixes for information on Azure database connection strings.
Environment variable names reflect the structure of an appsettings.json
file. Each element in the hierarchy is separated by a double underscore (preferable) or a colon. When the element structure includes an array, the array index should be treated as an additional element name in this path. Consider the following appsettings.json
file and its equivalent values represented as environment variables.
appsettings.json
{
"SmtpServer": "smtp.example.com",
"Logging": [
{
"Name": "ToEmail",
"Level": "Critical",
"Args": {
"FromAddress": "MySystem@example.com",
"ToAddress": "SRE@example.com"
}
},
{
"Name": "ToConsole",
"Level": "Information"
}
]
}
environment variables
setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information
Environment variables set in launchSettings.json
override those set in the system environment. For example, the ASP.NET Core web templates generate a launchSettings.json
file that sets the endpoint configuration to:
"applicationUrl": "https://localhost:5001;http://localhost:5000"
Configuring the applicationUrl
sets the ASPNETCORE_URLS
environment variable and overrides values set in the environment.
On Linux, the value of URL environment variables must be escaped so systemd
can parse it. Use the linux tool systemd-escape
which yields http:--localhost:5001
groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001
The following code displays the environment variables and values on application startup, which can be helpful when debugging environment settings:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
foreach (var c in builder.Configuration.AsEnumerable())
{
Console.WriteLine(c.Key + " = " + c.Value);
}
Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:
appsettings.json
and appsettings.{Environment}.json
files.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.
The following command sets keys and values using =
:
dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick
The following command sets keys and values using /
:
dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick
The following command sets keys and values using --
:
dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick
The key value:
=
, or the key must have a prefix of --
or /
when the value follows a space.=
is used. For example, MySetting=
.Within the same command, don't mix command-line argument key-value pairs that use =
with key-value pairs that use a space.
Switch mappings allow key name replacement logic. Provide a dictionary of switch replacements to the AddCommandLine method.
When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. If the command-line key is found in the dictionary, the dictionary value is passed back to set the key-value pair into the app's configuration. A switch mapping is required for any command-line key prefixed with a single dash (-
).
Switch mappings dictionary key rules:
-
or --
.To use a switch mappings dictionary, pass it into the call to AddCommandLine
:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var switchMappings = new Dictionary<string, string>()
{
{ "-k1", "key1" },
{ "-k2", "key2" },
{ "--alt3", "key3" },
{ "--alt4", "key4" },
{ "--alt5", "key5" },
{ "--alt6", "key6" },
};
builder.Configuration.AddCommandLine(args, switchMappings);
var app = builder.Build();
Run the following command works to test key replacement:
dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6
The following code shows the key values for the replaced keys:
public class Test3Model : PageModel
{
private readonly IConfiguration Config;
public Test3Model(IConfiguration configuration)
{
Config = configuration;
}
public ContentResult OnGet()
{
return Content(
$"Key1: '{Config["Key1"]}'\n" +
$"Key2: '{Config["Key2"]}'\n" +
$"Key3: '{Config["Key3"]}'\n" +
$"Key4: '{Config["Key4"]}'\n" +
$"Key5: '{Config["Key5"]}'\n" +
$"Key6: '{Config["Key6"]}'");
}
}
For apps that use switch mappings, the call to CreateDefaultBuilder
shouldn't pass arguments. The CreateDefaultBuilder
method's AddCommandLine
call doesn't include mapped switches, and there's no way to pass the switch-mapping dictionary to CreateDefaultBuilder
. The solution isn't to pass the arguments to CreateDefaultBuilder
but instead to allow the ConfigurationBuilder
method's AddCommandLine
method to process both the arguments and the switch-mapping dictionary.
Environment and command-line arguments can be set in Visual Studio from the launch profiles dialog:
The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.
The sample download contains the following appsettings.json
file:
{
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
},
"MyKey": "My appsettings.json Value",
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
The following code from the sample download displays several of the configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The preferred way to read hierarchical configuration data is using the options pattern. For more information, see Bind hierarchical configuration data in this document.
GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. These methods are described later in GetSection, GetChildren, and Exists.
Warning
This article shows the use of connection strings. With a local database the user doesn't have to be authenticated, but in production, connection strings sometimes include a password to authenticate. A resource owner password credential (ROPC) is a security risk that should be avoided in production databases. Production apps should use the most secure authentication flow available. For more information on authentication for apps deployed to test or production environments, see Secure authentication flows.
Configuration keys:
ConnectionString
and connectionstring
are treated as equivalent keys.:
) works on all platforms.__
, is supported by all platforms and is automatically converted into a colon :
.--
as a separator. The Azure Key Vault configuration provider automatically replaces --
with a :
when the secrets are loaded into the app's configuration.Configuration values:
The following table shows the configuration providers available to ASP.NET Core apps.
Provider | Provides configuration from |
---|---|
Azure Key Vault configuration provider | Azure Key Vault |
Azure App configuration provider | Azure App Configuration |
Command-line configuration provider | Command-line parameters |
Custom configuration provider | Custom source |
Environment Variables configuration provider | Environment variables |
File configuration provider | INI, JSON, and XML files |
Key-per-file configuration provider | Directory files |
Memory configuration provider | In-memory collections |
User secrets | File in the user profile directory |
Configuration sources are read in the order that their configuration providers are specified. Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.
A typical sequence of configuration providers is:
appsettings.json
appsettings.{Environment}.json
A common practice is to add the Command-line configuration provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.
The preceding sequence of providers is used in the default configuration.
Warning
This article shows the use of connection strings. With a local database the user doesn't have to be authenticated, but in production, connection strings sometimes include a password to authenticate. A resource owner password credential (ROPC) is a security risk that should be avoided in production databases. Production apps should use the most secure authentication flow available. For more information on authentication for apps deployed to test or production environments, see Secure authentication flows.
The Configuration API has special processing rules for four connection string environment variables. These connection strings are involved in configuring Azure connection strings for the app environment. Environment variables with the prefixes shown in the table are loaded into the app with the default configuration or when no prefix is supplied to AddEnvironmentVariables
.
Connection string prefix | Provider |
---|---|
CUSTOMCONNSTR_ |
Custom provider |
MYSQLCONNSTR_ |
MySQL |
SQLAZURECONNSTR_ |
Azure SQL Database |
SQLCONNSTR_ |
SQL Server |
When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:
ConnectionStrings
).CUSTOMCONNSTR_
, which has no stated provider).Environment variable key | Converted configuration key | Provider configuration entry |
---|---|---|
CUSTOMCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Configuration entry not created. |
MYSQLCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: MySql.Data.MySqlClient |
SQLAZURECONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: System.Data.SqlClient |
SQLCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: System.Data.SqlClient |
FileConfigurationProvider is the base class for loading configuration from the file system. The following configuration providers derive from FileConfigurationProvider
:
The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.
The following code adds several configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
.AddIniFile($"MyIniConfig.{builder.Environment.EnvironmentName}.ini",
optional: true, reloadOnChange: true);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
In the preceding code, settings in the MyIniConfig.ini
and MyIniConfig.{Environment}.ini
files are overridden by settings in the:
The sample download contains the following MyIniConfig.ini
file:
MyKey="MyIniConfig.ini Value"
[Position]
Title="My INI Config title"
Name="My INI Config name"
[Logging:LogLevel]
Default=Information
Microsoft=Warning
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The JsonConfigurationProvider loads configuration from JSON file key-value pairs.
Overloads can specify:
Consider the following code:
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddJsonFile("MyConfig.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
The preceding code:
MyConfig.json
file with the following options:
optional: true
: The file is optional.reloadOnChange: true
: The file is reloaded when changes are saved.MyConfig.json
file. Settings in the MyConfig.json
file override setting in the default configuration providers, including the Environment variables configuration provider and the Command-line configuration provider.You typically don't want a custom JSON file overriding values set in the Environment variables configuration provider and the Command-line configuration provider.
The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.
The following code adds several configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
.AddXmlFile($"MyXMLFile.{builder.Environment.EnvironmentName}.xml",
optional: true, reloadOnChange: true);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
In the preceding code, settings in the MyXMLFile.xml
and MyXMLFile.{Environment}.xml
files are overridden by settings in the:
The sample download contains the following MyXMLFile.xml
file:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<MyKey>MyXMLFile Value</MyKey>
<Position>
<Title>Title from MyXMLFile</Title>
<Name>Name from MyXMLFile</Name>
</Position>
<Logging>
<LogLevel>
<Default>Information</Default>
<Microsoft>Warning</Microsoft>
</LogLevel>
</Logging>
</configuration>
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
Repeating elements that use the same element name work if the name
attribute is used to distinguish the elements:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<section name="section0">
<key name="key0">value 00</key>
<key name="key1">value 01</key>
</section>
<section name="section1">
<key name="key0">value 10</key>
<key name="key1">value 11</key>
</section>
</configuration>
The following code reads the previous configuration file and displays the keys and values:
public class IndexModel : PageModel
{
private readonly IConfiguration Configuration;
public IndexModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var key00 = "section:section0:key:key0";
var key01 = "section:section0:key:key1";
var key10 = "section:section1:key:key0";
var key11 = "section:section1:key:key1";
var val00 = Configuration[key00];
var val01 = Configuration[key01];
var val10 = Configuration[key10];
var val11 = Configuration[key11];
return Content($"{key00} value: {val00} \n" +
$"{key01} value: {val01} \n" +
$"{key10} value: {val10} \n" +
$"{key10} value: {val11} \n"
);
}
}
Attributes can be used to supply values:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<key attribute="value" />
<section>
<key attribute="value" />
</section>
</configuration>
The previous configuration file loads the following keys with value
:
The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. The key is the file name. The value contains the file's contents. The Key-per-file configuration provider is used in Docker hosting scenarios.
To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. The directoryPath
to the files must be an absolute path.
Overloads permit specifying:
Action<KeyPerFileConfigurationSource>
delegate that configures the source.The double-underscore (__
) is used as a configuration key delimiter in file names. For example, the file name Logging__LogLevel__System
produces the configuration key Logging:LogLevel:System
.
Call ConfigureAppConfiguration
when building the host to specify the app's configuration:
.ConfigureAppConfiguration((hostingContext, config) =>
{
var path = Path.Combine(
Directory.GetCurrentDirectory(), "path/to/files");
config.AddKeyPerFile(directoryPath: path, optional: true);
})
The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.
The following code adds a memory collection to the configuration system:
var builder = WebApplication.CreateBuilder(args);
var Dict = new Dictionary<string, string>
{
{"MyKey", "Dictionary MyKey Value"},
{"Position:Title", "Dictionary_Title"},
{"Position:Name", "Dictionary_Name" },
{"Logging:LogLevel:Default", "Warning"}
};
builder.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
The following code from the sample download displays the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
In the preceding code, config.AddInMemoryCollection(Dict)
is added after the default configuration providers. For an example of ordering the configuration providers, see JSON configuration provider.
See Bind an array for another example using MemoryConfigurationProvider
.
Kestrel specific endpoint configuration overrides all cross-server endpoint configurations. Cross-server endpoint configurations include:
--urls
on the command lineASPNETCORE_URLS
Consider the following appsettings.json
file used in an ASP.NET Core web app:
{
"Kestrel": {
"Endpoints": {
"Https": {
"Url": "https://localhost:9999"
}
}
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
When the preceding highlighted markup is used in an ASP.NET Core web app and the app is launched on the command line with the following cross-server endpoint configuration:
dotnet run --urls="https://localhost:7777"
Kestrel binds to the endpoint configured specifically for Kestrel in the appsettings.json
file (https://localhost:9999
) and not https://localhost:7777
.
Consider the Kestrel specific endpoint configured as an environment variable:
set Kestrel__Endpoints__Https__Url=https://localhost:8888
In the preceding environment variable, Https
is the name of the Kestrel specific endpoint. The preceding appsettings.json
file also defines a Kestrel specific endpoint named Https
. By default, environment variables using the Environment Variables configuration provider are read after appsettings.{Environment}.json
, therefore, the preceding environment variable is used for the Https
endpoint.
ConfigurationBinder.GetValue extracts a single value from configuration with a specified key and converts it to the specified type:
public class TestNumModel : PageModel
{
private readonly IConfiguration Configuration;
public TestNumModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var number = Configuration.GetValue<int>("NumberKey", 99);
return Content($"{number}");
}
}
In the preceding code, if NumberKey
isn't found in the configuration, the default value of 99
is used.
For the examples that follow, consider the following MySubsection.json
file:
{
"section0": {
"key0": "value00",
"key1": "value01"
},
"section1": {
"key0": "value10",
"key1": "value11"
},
"section2": {
"subsection0": {
"key0": "value200",
"key1": "value201"
},
"subsection1": {
"key0": "value210",
"key1": "value211"
}
}
}
The following code adds MySubsection.json
to the configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("MySubsection.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
IConfiguration.GetSection returns a configuration subsection with the specified subsection key.
The following code returns values for section1
:
public class TestSectionModel : PageModel
{
private readonly IConfiguration Config;
public TestSectionModel(IConfiguration configuration)
{
Config = configuration.GetSection("section1");
}
public ContentResult OnGet()
{
return Content(
$"section1:key0: '{Config["key0"]}'\n" +
$"section1:key1: '{Config["key1"]}'");
}
}
The following code returns values for section2:subsection0
:
public class TestSection2Model : PageModel
{
private readonly IConfiguration Config;
public TestSection2Model(IConfiguration configuration)
{
Config = configuration.GetSection("section2:subsection0");
}
public ContentResult OnGet()
{
return Content(
$"section2:subsection0:key0 '{Config["key0"]}'\n" +
$"section2:subsection0:key1:'{Config["key1"]}'");
}
}
GetSection
never returns null
. If a matching section isn't found, an empty IConfigurationSection
is returned.
When GetSection
returns a matching section, Value isn't populated. A Key and Path are returned when the section exists.
The following code calls IConfiguration.GetChildren and returns values for section2:subsection0
:
public class TestSection4Model : PageModel
{
private readonly IConfiguration Config;
public TestSection4Model(IConfiguration configuration)
{
Config = configuration;
}
public ContentResult OnGet()
{
string s = "";
var selection = Config.GetSection("section2");
if (!selection.Exists())
{
throw new Exception("section2 does not exist.");
}
var children = selection.GetChildren();
foreach (var subSection in children)
{
int i = 0;
var key1 = subSection.Key + ":key" + i++.ToString();
var key2 = subSection.Key + ":key" + i.ToString();
s += key1 + " value: " + selection[key1] + "\n";
s += key2 + " value: " + selection[key2] + "\n";
}
return Content(s);
}
}
The preceding code calls ConfigurationExtensions.Exists to verify the section exists:
The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.
Consider MyArray.json
from the sample download:
{
"array": {
"entries": {
"0": "value00",
"1": "value10",
"2": "value20",
"4": "value40",
"5": "value50"
}
}
}
The following code adds MyArray.json
to the configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("MyArray.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
The following code reads the configuration and displays the values:
public class ArrayModel : PageModel
{
private readonly IConfiguration Config;
public ArrayExample? _array { get; private set; }
public ArrayModel(IConfiguration config)
{
Config = config;
}
public ContentResult OnGet()
{
_array = Config.GetSection("array").Get<ArrayExample>();
if (_array == null)
{
throw new ArgumentNullException(nameof(_array));
}
string s = String.Empty;
for (int j = 0; j < _array.Entries.Length; j++)
{
s += $"Index: {j} Value: {_array.Entries[j]} \n";
}
return Content(s);
}
}
public class ArrayExample
{
public string[]? Entries { get; set; }
}
The preceding code returns the following output:
Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value40
Index: 4 Value: value50
In the preceding output, Index 3 has value value40
, corresponding to "4": "value40",
in MyArray.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.
The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).
The provider has the following characteristics:
ConfigurationBuilder
to supply the connection string from another configuration provider.Define an EFConfigurationValue
entity for storing configuration values in the database.
Models/EFConfigurationValue.cs
:
public class EFConfigurationValue
{
public string Id { get; set; } = String.Empty;
public string Value { get; set; } = String.Empty;
}
Add an EFConfigurationContext
to store and access the configured values.
EFConfigurationProvider/EFConfigurationContext.cs
:
public class EFConfigurationContext : DbContext
{
public EFConfigurationContext(DbContextOptions<EFConfigurationContext> options) : base(options)
{
}
public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}
Create a class that implements IConfigurationSource.
EFConfigurationProvider/EFConfigurationSource.cs
:
public class EFConfigurationSource : IConfigurationSource
{
private readonly Action<DbContextOptionsBuilder> _optionsAction;
public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => _optionsAction = optionsAction;
public IConfigurationProvider Build(IConfigurationBuilder builder) => new EFConfigurationProvider(_optionsAction);
}
Create the custom configuration provider by inheriting from ConfigurationProvider. The configuration provider initializes the database when it's empty. Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).
EFConfigurationProvider/EFConfigurationProvider.cs
:
public class EFConfigurationProvider : ConfigurationProvider
{
public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
{
OptionsAction = optionsAction;
}
Action<DbContextOptionsBuilder> OptionsAction { get; }
public override void Load()
{
var builder = new DbContextOptionsBuilder<EFConfigurationContext>();
OptionsAction(builder);
using (var dbContext = new EFConfigurationContext(builder.Options))
{
if (dbContext == null || dbContext.Values == null)
{
throw new Exception("Null DB context");
}
dbContext.Database.EnsureCreated();
Data = !dbContext.Values.Any()
? CreateAndSaveDefaultValues(dbContext)
: dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
}
}
private static IDictionary<string, string> CreateAndSaveDefaultValues(
EFConfigurationContext dbContext)
{
// Quotes (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity-2005
var configValues =
new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{
{ "quote1", "I aim to misbehave." },
{ "quote2", "I swallowed a bug." },
{ "quote3", "You can't stop the signal, Mal." }
};
if (dbContext == null || dbContext.Values == null)
{
throw new Exception("Null DB context");
}
dbContext.Values.AddRange(configValues
.Select(kvp => new EFConfigurationValue
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
dbContext.SaveChanges();
return configValues;
}
}
An AddEFConfiguration
extension method permits adding the configuration source to a ConfigurationBuilder
.
Extensions/EntityFrameworkExtensions.cs
:
public static class EntityFrameworkExtensions
{
public static IConfigurationBuilder AddEFConfiguration(
this IConfigurationBuilder builder,
Action<DbContextOptionsBuilder> optionsAction)
{
return builder.Add(new EFConfigurationSource(optionsAction));
}
}
The following code shows how to use the custom EFConfigurationProvider
in Program.cs
:
//using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddEFConfiguration(
opt => opt.UseInMemoryDatabase("InMemoryDb"));
var app = builder.Build();
app.Run();
Configuration can be injected into services using Dependency Injection (DI) by resolving the IConfiguration service:
public class Service
{
private readonly IConfiguration _config;
public Service(IConfiguration config) =>
_config = config;
public void DoSomething()
{
var configSettingValue = _config["ConfigSetting"];
// ...
}
}
For information on how to access values using IConfiguration
, see GetValue and GetSection, GetChildren, and Exists in this article.
The following code displays configuration data in a Razor Page:
@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
In the following code, MyOptions
is added to the service container with Configure and bound to configuration:
using SampleApp.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<MyOptions>(
builder.Configuration.GetSection("MyOptions"));
var app = builder.Build();
The following markup uses the @inject
Razor directive to resolve and display the options values:
@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor
<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>
The following code displays configuration data in a MVC view:
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
The following code accesses configuration in the Program.cs
file.
var builder = WebApplication.CreateBuilder(args);
var key1 = builder.Configuration.GetValue<string>("KeyOne");
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
var key2 = app.Configuration.GetValue<int>("KeyTwo");
var key3 = app.Configuration.GetValue<bool>("KeyThree");
app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);
app.Run();
In appsettings.json
for the preceding example:
{
...
"KeyOne": "Key One Value",
"KeyTwo": 1999,
"KeyThree": true
}
Options configured in a delegate override values set in the configuration providers.
In the following code, an IConfigureOptions<TOptions> service is added to the service container. It uses a delegate to configure values for MyOptions
:
using SampleApp.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<MyOptions>(myOptions =>
{
myOptions.Option1 = "Value configured in delegate";
myOptions.Option2 = 500;
});
var app = builder.Build();
The following code displays the options values:
public class Test2Model : PageModel
{
private readonly IOptions<MyOptions> _optionsDelegate;
public Test2Model(IOptions<MyOptions> optionsDelegate )
{
_optionsDelegate = optionsDelegate;
}
public ContentResult OnGet()
{
return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
$"Option2: {_optionsDelegate.Value.Option2}");
}
}
In the preceding example, the values of Option1
and Option2
are specified in appsettings.json
and then overridden by the configured delegate.
Before the app is configured and started, a host is configured and launched. The host is responsible for app startup and lifetime management. Both the app and the host are configured using the configuration providers described in this topic. Host configuration key-value pairs are also included in the app's configuration. For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see ASP.NET Core fundamentals overview.
For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.
DOTNET_
(for example, DOTNET_ENVIRONMENT
) using the Environment Variables configuration provider. The prefix (DOTNET_
) is stripped when the configuration key-value pairs are loaded.ConfigureWebHostDefaults
):
ASPNETCORE_FORWARDEDHEADERS_ENABLED
environment variable is set to true
.This topic only pertains to app configuration. Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:
launch.json
/launchSettings.json
are tooling configuration files for the Development environment, described:
web.config
is a server configuration file, described in the following topics:
Environment variables set in launchSettings.json
override those set in the system environment.
For more information on migrating app configuration from earlier versions of ASP.NET, see Update from ASP.NET to ASP.NET Core.
An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup
class. For more information, see Use hosting startup assemblies in ASP.NET Core.
The Configuration-binding source generator provides AOT and trim-friendly configuration. For more information, see Configuration-binding source generator.
Application configuration in ASP.NET Core is performed using one or more configuration providers. Configuration providers read configuration data from key-value pairs using a variety of configuration sources:
appsettings.json
This article provides information on configuration in ASP.NET Core. For information on using configuration in console apps, see .NET Configuration.
ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management. The ASP.NET Core templates create a WebApplicationBuilder which contains the host. While some configuration can be done in both the host and the application configuration providers, generally, only configuration that is necessary for the host should be done in host configuration.
Application configuration is the highest priority and is detailed in the next section. Host configuration follows application configuration, and is described in this article.
ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:
var builder = WebApplication.CreateBuilder(args);
WebApplication.CreateBuilder initializes a new instance of the WebApplicationBuilder class with preconfigured defaults. The initialized WebApplicationBuilder
(builder
) provides default configuration for the app in the following order, from highest to lowest priority:
Development
environment.appsettings.{Environment}.json
using the JSON configuration provider. For example, appsettings.Production.json
and appsettings.Development.json
.The following list contains the default host configuration sources from highest to lowest priority for WebApplicationBuilder:
DOTNET_
-prefixed environment variables using the Environment variables configuration provider.ASPNETCORE_
-prefixed environment variables using the Environment variables configuration provider.For the .NET Generic Host and Web Host, the default host configuration sources from highest to lowest priority is:
ASPNETCORE_
-prefixed environment variables using the Environment variables configuration provider.DOTNET_
-prefixed environment variables using the Environment variables configuration provider.When a configuration value is set in host and application configuration, the application configuration is used.
The following variables are locked in early when initializing the host builders and can't be influenced by application config:
Development
, Production
, and Staging
Every other host setting is read from application config instead of host config.
URLS
is one of the many common host settings that is not a bootstrap setting. Like every other host setting not in the previous list, URLS
is read later from application config. Host config is a fallback for application config, so host config can be used to set URLS
, but it will be overridden by any configuration source in application config like appsettings.json
.
For more information, see Change the content root, app name, and environment and Change the content root, app name, and environment by environment variables or command line
The remaining sections in this article refer to application configuration.
The following code displays the enabled configuration providers in the order they were added:
public class Index2Model : PageModel
{
private IConfigurationRoot ConfigRoot;
public Index2Model(IConfiguration configRoot)
{
ConfigRoot = (IConfigurationRoot)configRoot;
}
public ContentResult OnGet()
{
string str = "";
foreach (var provider in ConfigRoot.Providers.ToList())
{
str += provider.ToString() + "\n";
}
return Content(str);
}
}
The preceding list of highest to lowest priority default configuration sources shows the providers in the opposite order they are added to template generated application. For example, the JSON configuration provider is added before the Command-line configuration provider.
Configuration providers that are added later have higher priority and override previous key settings. For example, if MyKey
is set in both appsettings.json
and the environment, the environment value is used. Using the default configuration providers, the Command-line configuration provider overrides all other providers.
For more information on CreateBuilder
, see Default builder settings.
Consider the following appsettings.json
file:
{
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
},
"MyKey": "My appsettings.json Value",
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The default JsonConfigurationProvider loads configuration in the following order:
appsettings.json
appsettings.{Environment}.json
: For example, the appsettings.Production.json
and appsettings.Development.json
files. The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. For more information, see Use multiple environments in ASP.NET Core.appsettings.{Environment}.json
values override keys in appsettings.json
. For example, by default:
appsettings.Development.json
configuration overwrites values found in appsettings.json
.appsettings.Production.json
configuration overwrites values found in appsettings.json
. For example, when deploying the app to Azure.If a configuration value must be guaranteed, see GetValue. The preceding example only reads strings and doesn’t support a default value.
Using the default configuration, the appsettings.json
and appsettings.{Environment}.json
files are enabled with reloadOnChange: true. Changes made to the appsettings.json
and appsettings.{Environment}.json
file after the app starts are read by the JSON configuration provider.
Comments in appsettings.json
and appsettings.{Environment}.json
files are supported using JavaScript or C# style comments.
The preferred way to read related configuration values is using the options pattern. For example, to read the following configuration values:
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
}
Create the following PositionOptions
class:
public class PositionOptions
{
public const string Position = "Position";
public string Title { get; set; } = String.Empty;
public string Name { get; set; } = String.Empty;
}
An options class:
Position
is not bound. The Position
field is used so the string "Position"
doesn't need to be hard coded in the app when binding the class to a configuration provider.The following code:
PositionOptions
class to the Position
section.Position
configuration data.public class Test22Model : PageModel
{
private readonly IConfiguration Configuration;
public Test22Model(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var positionOptions = new PositionOptions();
Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);
return Content($"Title: {positionOptions.Title} \n" +
$"Name: {positionOptions.Name}");
}
}
In the preceding code, by default, changes to the JSON configuration file after the app has started are read.
ConfigurationBinder.Get<T>
binds and returns the specified type. ConfigurationBinder.Get<T>
may be more convenient than using ConfigurationBinder.Bind
. The following code shows how to use ConfigurationBinder.Get<T>
with the PositionOptions
class:
public class Test21Model : PageModel
{
private readonly IConfiguration Configuration;
public PositionOptions? positionOptions { get; private set; }
public Test21Model(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
positionOptions = Configuration.GetSection(PositionOptions.Position)
.Get<PositionOptions>();
return Content($"Title: {positionOptions.Title} \n" +
$"Name: {positionOptions.Name}");
}
}
In the preceding code, by default, changes to the JSON configuration file after the app has started are read.
An alternative approach when using the options pattern is to bind the Position
section and add it to the dependency injection service container. In the following code, PositionOptions
is added to the service container with Configure and bound to configuration:
using ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<PositionOptions>(
builder.Configuration.GetSection(PositionOptions.Position));
var app = builder.Build();
Using the preceding code, the following code reads the position options:
public class Test2Model : PageModel
{
private readonly PositionOptions _options;
public Test2Model(IOptions<PositionOptions> options)
{
_options = options.Value;
}
public ContentResult OnGet()
{
return Content($"Title: {_options.Title} \n" +
$"Name: {_options.Name}");
}
}
In the preceding code, changes to the JSON configuration file after the app has started are not read. To read changes after the app has started, use IOptionsSnapshot.
Using the default configuration, the appsettings.json
and appsettings.{Environment}.json
files are enabled with reloadOnChange: true. Changes made to the appsettings.json
and appsettings.{Environment}.json
file after the app starts are read by the JSON configuration provider.
See JSON configuration provider in this document for information on adding additional JSON configuration files.
Consider the following which registers services and configures options:
using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<PositionOptions>(
builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
builder.Configuration.GetSection(ColorOptions.Color));
builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();
var app = builder.Build();
Related groups of registrations can be moved to an extension method to register services. For example, the configuration services are added to the following class:
using ConfigSample.Options;
using Microsoft.Extensions.Configuration;
namespace Microsoft.Extensions.DependencyInjection
{
public static class MyConfigServiceCollectionExtensions
{
public static IServiceCollection AddConfig(
this IServiceCollection services, IConfiguration config)
{
services.Configure<PositionOptions>(
config.GetSection(PositionOptions.Position));
services.Configure<ColorOptions>(
config.GetSection(ColorOptions.Color));
return services;
}
public static IServiceCollection AddMyDependencyGroup(
this IServiceCollection services)
{
services.AddScoped<IMyDependency, MyDependency>();
services.AddScoped<IMyDependency2, MyDependency2>();
return services;
}
}
}
The remaining services are registered in a similar class. The following code uses the new extension methods to register the services:
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddConfig(builder.Configuration)
.AddMyDependencyGroup();
builder.Services.AddRazorPages();
var app = builder.Build();
Note: Each services.Add{GROUP_NAME}
extension method adds and potentially configures services. For example, AddControllersWithViews adds the services MVC controllers with views require, and AddRazorPages adds the services Razor Pages requires.
Configuration data guidelines:
By default, the user secrets configuration source is registered after the JSON configuration sources. Therefore, user secrets keys take precedence over keys in appsettings.json
and appsettings.{Environment}.json
.
For more information on storing passwords or other sensitive data:
Azure Key Vault safely stores app secrets for ASP.NET Core apps. For more information, see Azure Key Vault configuration provider in ASP.NET Core.
Non-prefixed environment variables are environment variables other than those prefixed by ASPNETCORE_
or DOTNET_
. For example, the ASP.NET Core web application templates set "ASPNETCORE_ENVIRONMENT": "Development"
in launchSettings.json
. For more information on ASPNETCORE_
and DOTNET_
environment variables, see:
ASPNETCORE_
-prefixed and DOTNETCORE_
-prefixed environment variables.DOTNET_
environment variables used outside of Microsoft.Extensions.Hosting.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json
, appsettings.{Environment}.json
, and user secrets. Therefore, key values read from the environment override values read from appsettings.json
, appsettings.{Environment}.json
, and user secrets.
The :
separator doesn't work with environment variable hierarchical keys on all platforms. For example, the :
separator is not supported by Bash. The double underscore, __
, is:
:
.The following set
commands:
dotnet run
command must be run in the project directory.set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run
The preceding environment settings:
The following setx commands can be used to set the environment keys and values on Windows. Unlike set
, setx
settings are persisted. /M
sets the variable in the system environment. If the /M
switch isn't used, a user environment variable is set.
setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M
To test that the preceding commands override appsettings.json
and appsettings.{Environment}.json
:
dotnet run
.Call AddEnvironmentVariables with a string to specify a prefix for environment variables:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
var app = builder.Build();
In the preceding code:
builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_")
is added after the default configuration providers. For an example of ordering the configuration providers, see JSON configuration provider.MyCustomPrefix_
prefix override the default configuration providers. This includes environment variables without the prefix.The prefix is stripped off when the configuration key-value pairs are read.
The following commands test the custom prefix:
set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run
The default configuration loads environment variables and command line arguments prefixed with DOTNET_
and ASPNETCORE_
. The DOTNET_
and ASPNETCORE_
prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. For more information on host and app configuration, see .NET Generic Host.
On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service application settings are:
For more information, see Azure Apps: Override app configuration using the Azure Portal.
See Connection string prefixes for information on Azure database connection strings.
Environment variable names reflect the structure of an appsettings.json
file. Each element in the hierarchy is separated by a double underscore (preferable) or a colon. When the element structure includes an array, the array index should be treated as an additional element name in this path. Consider the following appsettings.json
file and its equivalent values represented as environment variables.
appsettings.json
{
"SmtpServer": "smtp.example.com",
"Logging": [
{
"Name": "ToEmail",
"Level": "Critical",
"Args": {
"FromAddress": "MySystem@example.com",
"ToAddress": "SRE@example.com"
}
},
{
"Name": "ToConsole",
"Level": "Information"
}
]
}
environment variables
setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information
Environment variables set in launchSettings.json
override those set in the system environment. For example, the ASP.NET Core web templates generate a launchSettings.json
file that sets the endpoint configuration to:
"applicationUrl": "https://localhost:5001;http://localhost:5000"
Configuring the applicationUrl
sets the ASPNETCORE_URLS
environment variable and overrides values set in the environment.
On Linux, the value of URL environment variables must be escaped so systemd
can parse it. Use the linux tool systemd-escape
which yields http:--localhost:5001
groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001
The following code displays the environment variables and values on application startup, which can be helpful when debugging environment settings:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
foreach (var c in builder.Configuration.AsEnumerable())
{
Console.WriteLine(c.Key + " = " + c.Value);
}
Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:
appsettings.json
and appsettings.{Environment}.json
files.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.
The following command sets keys and values using =
:
dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick
The following command sets keys and values using /
:
dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick
The following command sets keys and values using --
:
dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick
The key value:
=
, or the key must have a prefix of --
or /
when the value follows a space.=
is used. For example, MySetting=
.Within the same command, don't mix command-line argument key-value pairs that use =
with key-value pairs that use a space.
Switch mappings allow key name replacement logic. Provide a dictionary of switch replacements to the AddCommandLine method.
When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. If the command-line key is found in the dictionary, the dictionary value is passed back to set the key-value pair into the app's configuration. A switch mapping is required for any command-line key prefixed with a single dash (-
).
Switch mappings dictionary key rules:
-
or --
.To use a switch mappings dictionary, pass it into the call to AddCommandLine
:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var switchMappings = new Dictionary<string, string>()
{
{ "-k1", "key1" },
{ "-k2", "key2" },
{ "--alt3", "key3" },
{ "--alt4", "key4" },
{ "--alt5", "key5" },
{ "--alt6", "key6" },
};
builder.Configuration.AddCommandLine(args, switchMappings);
var app = builder.Build();
Run the following command works to test key replacement:
dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6
The following code shows the key values for the replaced keys:
public class Test3Model : PageModel
{
private readonly IConfiguration Config;
public Test3Model(IConfiguration configuration)
{
Config = configuration;
}
public ContentResult OnGet()
{
return Content(
$"Key1: '{Config["Key1"]}'\n" +
$"Key2: '{Config["Key2"]}'\n" +
$"Key3: '{Config["Key3"]}'\n" +
$"Key4: '{Config["Key4"]}'\n" +
$"Key5: '{Config["Key5"]}'\n" +
$"Key6: '{Config["Key6"]}'");
}
}
For apps that use switch mappings, the call to CreateDefaultBuilder
shouldn't pass arguments. The CreateDefaultBuilder
method's AddCommandLine
call doesn't include mapped switches, and there's no way to pass the switch-mapping dictionary to CreateDefaultBuilder
. The solution isn't to pass the arguments to CreateDefaultBuilder
but instead to allow the ConfigurationBuilder
method's AddCommandLine
method to process both the arguments and the switch-mapping dictionary.
Environment and command-line arguments can be set in Visual Studio from the launch profiles dialog:
The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.
The sample download contains the following appsettings.json
file:
{
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
},
"MyKey": "My appsettings.json Value",
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
The following code from the sample download displays several of the configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The preferred way to read hierarchical configuration data is using the options pattern. For more information, see Bind hierarchical configuration data in this document.
GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. These methods are described later in GetSection, GetChildren, and Exists.
Warning
This article shows the use of connection strings. With a local database the user doesn't have to be authenticated, but in production, connection strings sometimes include a password to authenticate. A resource owner password credential (ROPC) is a security risk that should be avoided in production databases. Production apps should use the most secure authentication flow available. For more information on authentication for apps deployed to test or production environments, see Secure authentication flows.
Configuration keys:
ConnectionString
and connectionstring
are treated as equivalent keys.:
) works on all platforms.__
, is supported by all platforms and is automatically converted into a colon :
.--
as a separator. The Azure Key Vault configuration provider automatically replaces --
with a :
when the secrets are loaded into the app's configuration.Configuration values:
The following table shows the configuration providers available to ASP.NET Core apps.
Provider | Provides configuration from |
---|---|
Azure Key Vault configuration provider | Azure Key Vault |
Azure App configuration provider | Azure App Configuration |
Command-line configuration provider | Command-line parameters |
Custom configuration provider | Custom source |
Environment Variables configuration provider | Environment variables |
File configuration provider | INI, JSON, and XML files |
Key-per-file configuration provider | Directory files |
Memory configuration provider | In-memory collections |
User secrets | File in the user profile directory |
Configuration sources are read in the order that their configuration providers are specified. Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.
A typical sequence of configuration providers is:
appsettings.json
appsettings.{Environment}.json
A common practice is to add the Command-line configuration provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.
The preceding sequence of providers is used in the default configuration.
Warning
This article shows the use of connection strings. With a local database the user doesn't have to be authenticated, but in production, connection strings sometimes include a password to authenticate. A resource owner password credential (ROPC) is a security risk that should be avoided in production databases. Production apps should use the most secure authentication flow available. For more information on authentication for apps deployed to test or production environments, see Secure authentication flows.
The Configuration API has special processing rules for four connection string environment variables. These connection strings are involved in configuring Azure connection strings for the app environment. Environment variables with the prefixes shown in the table are loaded into the app with the default configuration or when no prefix is supplied to AddEnvironmentVariables
.
Connection string prefix | Provider |
---|---|
CUSTOMCONNSTR_ |
Custom provider |
MYSQLCONNSTR_ |
MySQL |
SQLAZURECONNSTR_ |
Azure SQL Database |
SQLCONNSTR_ |
SQL Server |
When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:
ConnectionStrings
).CUSTOMCONNSTR_
, which has no stated provider).Environment variable key | Converted configuration key | Provider configuration entry |
---|---|---|
CUSTOMCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Configuration entry not created. |
MYSQLCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: MySql.Data.MySqlClient |
SQLAZURECONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: System.Data.SqlClient |
SQLCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: System.Data.SqlClient |
FileConfigurationProvider is the base class for loading configuration from the file system. The following configuration providers derive from FileConfigurationProvider
:
The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.
The following code adds several configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
.AddIniFile($"MyIniConfig.{builder.Environment.EnvironmentName}.ini",
optional: true, reloadOnChange: true);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
In the preceding code, settings in the MyIniConfig.ini
and MyIniConfig.{Environment}.ini
files are overridden by settings in the:
The sample download contains the following MyIniConfig.ini
file:
MyKey="MyIniConfig.ini Value"
[Position]
Title="My INI Config title"
Name="My INI Config name"
[Logging:LogLevel]
Default=Information
Microsoft=Warning
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The JsonConfigurationProvider loads configuration from JSON file key-value pairs.
Overloads can specify:
Consider the following code:
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddJsonFile("MyConfig.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
The preceding code:
MyConfig.json
file with the following options:
optional: true
: The file is optional.reloadOnChange: true
: The file is reloaded when changes are saved.MyConfig.json
file. Settings in the MyConfig.json
file override setting in the default configuration providers, including the Environment variables configuration provider and the Command-line configuration provider.You typically don't want a custom JSON file overriding values set in the Environment variables configuration provider and the Command-line configuration provider.
The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.
The following code adds several configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
.AddXmlFile($"MyXMLFile.{builder.Environment.EnvironmentName}.xml",
optional: true, reloadOnChange: true);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
In the preceding code, settings in the MyXMLFile.xml
and MyXMLFile.{Environment}.xml
files are overridden by settings in the:
The sample download contains the following MyXMLFile.xml
file:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<MyKey>MyXMLFile Value</MyKey>
<Position>
<Title>Title from MyXMLFile</Title>
<Name>Name from MyXMLFile</Name>
</Position>
<Logging>
<LogLevel>
<Default>Information</Default>
<Microsoft>Warning</Microsoft>
</LogLevel>
</Logging>
</configuration>
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
Repeating elements that use the same element name work if the name
attribute is used to distinguish the elements:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<section name="section0">
<key name="key0">value 00</key>
<key name="key1">value 01</key>
</section>
<section name="section1">
<key name="key0">value 10</key>
<key name="key1">value 11</key>
</section>
</configuration>
The following code reads the previous configuration file and displays the keys and values:
public class IndexModel : PageModel
{
private readonly IConfiguration Configuration;
public IndexModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var key00 = "section:section0:key:key0";
var key01 = "section:section0:key:key1";
var key10 = "section:section1:key:key0";
var key11 = "section:section1:key:key1";
var val00 = Configuration[key00];
var val01 = Configuration[key01];
var val10 = Configuration[key10];
var val11 = Configuration[key11];
return Content($"{key00} value: {val00} \n" +
$"{key01} value: {val01} \n" +
$"{key10} value: {val10} \n" +
$"{key10} value: {val11} \n"
);
}
}
Attributes can be used to supply values:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<key attribute="value" />
<section>
<key attribute="value" />
</section>
</configuration>
The previous configuration file loads the following keys with value
:
The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. The key is the file name. The value contains the file's contents. The Key-per-file configuration provider is used in Docker hosting scenarios.
To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. The directoryPath
to the files must be an absolute path.
Overloads permit specifying:
Action<KeyPerFileConfigurationSource>
delegate that configures the source.The double-underscore (__
) is used as a configuration key delimiter in file names. For example, the file name Logging__LogLevel__System
produces the configuration key Logging:LogLevel:System
.
Call ConfigureAppConfiguration
when building the host to specify the app's configuration:
.ConfigureAppConfiguration((hostingContext, config) =>
{
var path = Path.Combine(
Directory.GetCurrentDirectory(), "path/to/files");
config.AddKeyPerFile(directoryPath: path, optional: true);
})
The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.
The following code adds a memory collection to the configuration system:
var builder = WebApplication.CreateBuilder(args);
var Dict = new Dictionary<string, string>
{
{"MyKey", "Dictionary MyKey Value"},
{"Position:Title", "Dictionary_Title"},
{"Position:Name", "Dictionary_Name" },
{"Logging:LogLevel:Default", "Warning"}
};
builder.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
The following code from the sample download displays the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
In the preceding code, config.AddInMemoryCollection(Dict)
is added after the default configuration providers. For an example of ordering the configuration providers, see JSON configuration provider.
See Bind an array for another example using MemoryConfigurationProvider
.
Kestrel specific endpoint configuration overrides all cross-server endpoint configurations. Cross-server endpoint configurations include:
--urls
on the command lineASPNETCORE_URLS
Consider the following appsettings.json
file used in an ASP.NET Core web app:
{
"Kestrel": {
"Endpoints": {
"Https": {
"Url": "https://localhost:9999"
}
}
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
When the preceding highlighted markup is used in an ASP.NET Core web app and the app is launched on the command line with the following cross-server endpoint configuration:
dotnet run --urls="https://localhost:7777"
Kestrel binds to the endpoint configured specifically for Kestrel in the appsettings.json
file (https://localhost:9999
) and not https://localhost:7777
.
Consider the Kestrel specific endpoint configured as an environment variable:
set Kestrel__Endpoints__Https__Url=https://localhost:8888
In the preceding environment variable, Https
is the name of the Kestrel specific endpoint. The preceding appsettings.json
file also defines a Kestrel specific endpoint named Https
. By default, environment variables using the Environment Variables configuration provider are read after appsettings.{Environment}.json
, therefore, the preceding environment variable is used for the Https
endpoint.
ConfigurationBinder.GetValue extracts a single value from configuration with a specified key and converts it to the specified type:
public class TestNumModel : PageModel
{
private readonly IConfiguration Configuration;
public TestNumModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var number = Configuration.GetValue<int>("NumberKey", 99);
return Content($"{number}");
}
}
In the preceding code, if NumberKey
isn't found in the configuration, the default value of 99
is used.
For the examples that follow, consider the following MySubsection.json
file:
{
"section0": {
"key0": "value00",
"key1": "value01"
},
"section1": {
"key0": "value10",
"key1": "value11"
},
"section2": {
"subsection0": {
"key0": "value200",
"key1": "value201"
},
"subsection1": {
"key0": "value210",
"key1": "value211"
}
}
}
The following code adds MySubsection.json
to the configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("MySubsection.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
IConfiguration.GetSection returns a configuration subsection with the specified subsection key.
The following code returns values for section1
:
public class TestSectionModel : PageModel
{
private readonly IConfiguration Config;
public TestSectionModel(IConfiguration configuration)
{
Config = configuration.GetSection("section1");
}
public ContentResult OnGet()
{
return Content(
$"section1:key0: '{Config["key0"]}'\n" +
$"section1:key1: '{Config["key1"]}'");
}
}
The following code returns values for section2:subsection0
:
public class TestSection2Model : PageModel
{
private readonly IConfiguration Config;
public TestSection2Model(IConfiguration configuration)
{
Config = configuration.GetSection("section2:subsection0");
}
public ContentResult OnGet()
{
return Content(
$"section2:subsection0:key0 '{Config["key0"]}'\n" +
$"section2:subsection0:key1:'{Config["key1"]}'");
}
}
GetSection
never returns null
. If a matching section isn't found, an empty IConfigurationSection
is returned.
When GetSection
returns a matching section, Value isn't populated. A Key and Path are returned when the section exists.
The following code calls IConfiguration.GetChildren and returns values for section2:subsection0
:
public class TestSection4Model : PageModel
{
private readonly IConfiguration Config;
public TestSection4Model(IConfiguration configuration)
{
Config = configuration;
}
public ContentResult OnGet()
{
string s = "";
var selection = Config.GetSection("section2");
if (!selection.Exists())
{
throw new Exception("section2 does not exist.");
}
var children = selection.GetChildren();
foreach (var subSection in children)
{
int i = 0;
var key1 = subSection.Key + ":key" + i++.ToString();
var key2 = subSection.Key + ":key" + i.ToString();
s += key1 + " value: " + selection[key1] + "\n";
s += key2 + " value: " + selection[key2] + "\n";
}
return Content(s);
}
}
The preceding code calls ConfigurationExtensions.Exists to verify the section exists:
The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.
Consider MyArray.json
from the sample download:
{
"array": {
"entries": {
"0": "value00",
"1": "value10",
"2": "value20",
"4": "value40",
"5": "value50"
}
}
}
The following code adds MyArray.json
to the configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("MyArray.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
The following code reads the configuration and displays the values:
public class ArrayModel : PageModel
{
private readonly IConfiguration Config;
public ArrayExample? _array { get; private set; }
public ArrayModel(IConfiguration config)
{
Config = config;
}
public ContentResult OnGet()
{
_array = Config.GetSection("array").Get<ArrayExample>();
if (_array == null)
{
throw new ArgumentNullException(nameof(_array));
}
string s = String.Empty;
for (int j = 0; j < _array.Entries.Length; j++)
{
s += $"Index: {j} Value: {_array.Entries[j]} \n";
}
return Content(s);
}
}
public class ArrayExample
{
public string[]? Entries { get; set; }
}
The preceding code returns the following output:
Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value40
Index: 4 Value: value50
In the preceding output, Index 3 has value value40
, corresponding to "4": "value40",
in MyArray.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.
The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).
The provider has the following characteristics:
ConfigurationBuilder
to supply the connection string from another configuration provider.Define an EFConfigurationValue
entity for storing configuration values in the database.
Models/EFConfigurationValue.cs
:
public class EFConfigurationValue
{
public string Id { get; set; } = String.Empty;
public string Value { get; set; } = String.Empty;
}
Add an EFConfigurationContext
to store and access the configured values.
EFConfigurationProvider/EFConfigurationContext.cs
:
public class EFConfigurationContext : DbContext
{
public EFConfigurationContext(DbContextOptions<EFConfigurationContext> options) : base(options)
{
}
public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}
Create a class that implements IConfigurationSource.
EFConfigurationProvider/EFConfigurationSource.cs
:
public class EFConfigurationSource : IConfigurationSource
{
private readonly Action<DbContextOptionsBuilder> _optionsAction;
public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => _optionsAction = optionsAction;
public IConfigurationProvider Build(IConfigurationBuilder builder) => new EFConfigurationProvider(_optionsAction);
}
Create the custom configuration provider by inheriting from ConfigurationProvider. The configuration provider initializes the database when it's empty. Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).
EFConfigurationProvider/EFConfigurationProvider.cs
:
public class EFConfigurationProvider : ConfigurationProvider
{
public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
{
OptionsAction = optionsAction;
}
Action<DbContextOptionsBuilder> OptionsAction { get; }
public override void Load()
{
var builder = new DbContextOptionsBuilder<EFConfigurationContext>();
OptionsAction(builder);
using (var dbContext = new EFConfigurationContext(builder.Options))
{
if (dbContext == null || dbContext.Values == null)
{
throw new Exception("Null DB context");
}
dbContext.Database.EnsureCreated();
Data = !dbContext.Values.Any()
? CreateAndSaveDefaultValues(dbContext)
: dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
}
}
private static IDictionary<string, string> CreateAndSaveDefaultValues(
EFConfigurationContext dbContext)
{
// Quotes (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity-2005
var configValues =
new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{
{ "quote1", "I aim to misbehave." },
{ "quote2", "I swallowed a bug." },
{ "quote3", "You can't stop the signal, Mal." }
};
if (dbContext == null || dbContext.Values == null)
{
throw new Exception("Null DB context");
}
dbContext.Values.AddRange(configValues
.Select(kvp => new EFConfigurationValue
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
dbContext.SaveChanges();
return configValues;
}
}
An AddEFConfiguration
extension method permits adding the configuration source to a ConfigurationBuilder
.
Extensions/EntityFrameworkExtensions.cs
:
public static class EntityFrameworkExtensions
{
public static IConfigurationBuilder AddEFConfiguration(
this IConfigurationBuilder builder,
Action<DbContextOptionsBuilder> optionsAction)
{
return builder.Add(new EFConfigurationSource(optionsAction));
}
}
The following code shows how to use the custom EFConfigurationProvider
in Program.cs
:
//using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddEFConfiguration(
opt => opt.UseInMemoryDatabase("InMemoryDb"));
var app = builder.Build();
app.Run();
Configuration can be injected into services using Dependency Injection (DI) by resolving the IConfiguration service:
public class Service
{
private readonly IConfiguration _config;
public Service(IConfiguration config) =>
_config = config;
public void DoSomething()
{
var configSettingValue = _config["ConfigSetting"];
// ...
}
}
For information on how to access values using IConfiguration
, see GetValue and GetSection, GetChildren, and Exists in this article.
The following code displays configuration data in a Razor Page:
@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
In the following code, MyOptions
is added to the service container with Configure and bound to configuration:
using SampleApp.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<MyOptions>(
builder.Configuration.GetSection("MyOptions"));
var app = builder.Build();
The following markup uses the @inject
Razor directive to resolve and display the options values:
@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor
<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>
The following code displays configuration data in a MVC view:
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
The following code accesses configuration in the Program.cs
file.
var builder = WebApplication.CreateBuilder(args);
var key1 = builder.Configuration.GetValue<string>("KeyOne");
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
var key2 = app.Configuration.GetValue<int>("KeyTwo");
var key3 = app.Configuration.GetValue<bool>("KeyThree");
app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);
app.Run();
In appsettings.json
for the preceding example:
{
...
"KeyOne": "Key One Value",
"KeyTwo": 1999,
"KeyThree": true
}
Options configured in a delegate override values set in the configuration providers.
In the following code, an IConfigureOptions<TOptions> service is added to the service container. It uses a delegate to configure values for MyOptions
:
using SampleApp.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<MyOptions>(myOptions =>
{
myOptions.Option1 = "Value configured in delegate";
myOptions.Option2 = 500;
});
var app = builder.Build();
The following code displays the options values:
public class Test2Model : PageModel
{
private readonly IOptions<MyOptions> _optionsDelegate;
public Test2Model(IOptions<MyOptions> optionsDelegate )
{
_optionsDelegate = optionsDelegate;
}
public ContentResult OnGet()
{
return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
$"Option2: {_optionsDelegate.Value.Option2}");
}
}
In the preceding example, the values of Option1
and Option2
are specified in appsettings.json
and then overridden by the configured delegate.
Before the app is configured and started, a host is configured and launched. The host is responsible for app startup and lifetime management. Both the app and the host are configured using the configuration providers described in this topic. Host configuration key-value pairs are also included in the app's configuration. For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see ASP.NET Core fundamentals overview.
For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.
DOTNET_
(for example, DOTNET_ENVIRONMENT
) using the Environment Variables configuration provider. The prefix (DOTNET_
) is stripped when the configuration key-value pairs are loaded.ConfigureWebHostDefaults
):
ASPNETCORE_FORWARDEDHEADERS_ENABLED
environment variable is set to true
.This topic only pertains to app configuration. Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:
launch.json
/launchSettings.json
are tooling configuration files for the Development environment, described:
web.config
is a server configuration file, described in the following topics:
Environment variables set in launchSettings.json
override those set in the system environment.
For more information on migrating app configuration from earlier versions of ASP.NET, see Update from ASP.NET to ASP.NET Core.
An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup
class. For more information, see Use hosting startup assemblies in ASP.NET Core.
Application configuration in ASP.NET Core is performed using one or more configuration providers. Configuration providers read configuration data from key-value pairs using a variety of configuration sources:
appsettings.json
This article provides information on configuration in ASP.NET Core. For information on using configuration in console apps, see .NET Configuration.
ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management. The ASP.NET Core templates create a WebApplicationBuilder which contains the host. While some configuration can be done in both the host and the application configuration providers, generally, only configuration that is necessary for the host should be done in host configuration.
Application configuration is the highest priority and is detailed in the next section. Host configuration follows application configuration, and is described in this article.
ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:
var builder = WebApplication.CreateBuilder(args);
WebApplication.CreateBuilder initializes a new instance of the WebApplicationBuilder class with preconfigured defaults. The initialized WebApplicationBuilder
(builder
) provides default configuration for the app in the following order, from highest to lowest priority:
Development
environment.appsettings.{Environment}.json
using the JSON configuration provider. For example, appsettings.Production.json
and appsettings.Development.json
.The following list contains the default host configuration sources from highest to lowest priority:
ASPNETCORE_
-prefixed environment variables using the Environment variables configuration provider.DOTNET_
-prefixed environment variables using the Environment variables configuration provider.When a configuration value is set in host and application configuration, the application configuration is used.
See Explanation in this GitHub comment for an explanation of why in host configuration, ASPNETCORE_
prefixed environment variables have higher priority than command-line arguments.
The following variables are locked in early when initializing the host builders and can't be influenced by application config:
Development
, Production
, and Staging
Every other host setting is read from application config instead of host config.
URLS
is one of the many common host settings that is not a bootstrap setting. Like every other host setting not in the previous list, URLS
is read later from application config. Host config is a fallback for application config, so host config can be used to set URLS
, but it will be overridden by any configuration source in application config like appsettings.json
.
For more information, see Change the content root, app name, and environment and Change the content root, app name, and environment by environment variables or command line
The remaining sections in this article refer to application configuration.
The following code displays the enabled configuration providers in the order they were added:
public class Index2Model : PageModel
{
private IConfigurationRoot ConfigRoot;
public Index2Model(IConfiguration configRoot)
{
ConfigRoot = (IConfigurationRoot)configRoot;
}
public ContentResult OnGet()
{
string str = "";
foreach (var provider in ConfigRoot.Providers.ToList())
{
str += provider.ToString() + "\n";
}
return Content(str);
}
}
The preceding list of highest to lowest priority default configuration sources shows the providers in the opposite order they are added to template generated application. For example, the JSON configuration provider is added before the Command-line configuration provider.
Configuration providers that are added later have higher priority and override previous key settings. For example, if MyKey
is set in both appsettings.json
and the environment, the environment value is used. Using the default configuration providers, the Command-line configuration provider overrides all other providers.
For more information on CreateBuilder
, see Default builder settings.
Consider the following appsettings.json
file:
{
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
},
"MyKey": "My appsettings.json Value",
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The default JsonConfigurationProvider loads configuration in the following order:
appsettings.json
appsettings.{Environment}.json
: For example, the appsettings.Production.json
and appsettings.Development.json
files. The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. For more information, see Use multiple environments in ASP.NET Core.appsettings.{Environment}.json
values override keys in appsettings.json
. For example, by default:
appsettings.Development.json
configuration overwrites values found in appsettings.json
.appsettings.Production.json
configuration overwrites values found in appsettings.json
. For example, when deploying the app to Azure.If a configuration value must be guaranteed, see GetValue. The preceding example only reads strings and doesn’t support a default value.
Using the default configuration, the appsettings.json
and appsettings.{Environment}.json
files are enabled with reloadOnChange: true. Changes made to the appsettings.json
and appsettings.{Environment}.json
file after the app starts are read by the JSON configuration provider.
The preferred way to read related configuration values is using the options pattern. For example, to read the following configuration values:
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
}
Create the following PositionOptions
class:
public class PositionOptions
{
public const string Position = "Position";
public string Title { get; set; } = String.Empty;
public string Name { get; set; } = String.Empty;
}
An options class:
Position
is not bound. The Position
field is used so the string "Position"
doesn't need to be hard coded in the app when binding the class to a configuration provider.The following code:
PositionOptions
class to the Position
section.Position
configuration data.public class Test22Model : PageModel
{
private readonly IConfiguration Configuration;
public Test22Model(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var positionOptions = new PositionOptions();
Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);
return Content($"Title: {positionOptions.Title} \n" +
$"Name: {positionOptions.Name}");
}
}
In the preceding code, by default, changes to the JSON configuration file after the app has started are read.
ConfigurationBinder.Get<T>
binds and returns the specified type. ConfigurationBinder.Get<T>
may be more convenient than using ConfigurationBinder.Bind
. The following code shows how to use ConfigurationBinder.Get<T>
with the PositionOptions
class:
public class Test21Model : PageModel
{
private readonly IConfiguration Configuration;
public PositionOptions? positionOptions { get; private set; }
public Test21Model(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
positionOptions = Configuration.GetSection(PositionOptions.Position)
.Get<PositionOptions>();
return Content($"Title: {positionOptions.Title} \n" +
$"Name: {positionOptions.Name}");
}
}
In the preceding code, by default, changes to the JSON configuration file after the app has started are read.
An alternative approach when using the options pattern is to bind the Position
section and add it to the dependency injection service container. In the following code, PositionOptions
is added to the service container with Configure and bound to configuration:
using ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<PositionOptions>(
builder.Configuration.GetSection(PositionOptions.Position));
var app = builder.Build();
Using the preceding code, the following code reads the position options:
public class Test2Model : PageModel
{
private readonly PositionOptions _options;
public Test2Model(IOptions<PositionOptions> options)
{
_options = options.Value;
}
public ContentResult OnGet()
{
return Content($"Title: {_options.Title} \n" +
$"Name: {_options.Name}");
}
}
In the preceding code, changes to the JSON configuration file after the app has started are not read. To read changes after the app has started, use IOptionsSnapshot.
Using the default configuration, the appsettings.json
and appsettings.{Environment}.json
files are enabled with reloadOnChange: true. Changes made to the appsettings.json
and appsettings.{Environment}.json
file after the app starts are read by the JSON configuration provider.
See JSON configuration provider in this document for information on adding additional JSON configuration files.
Consider the following which registers services and configures options:
using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<PositionOptions>(
builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
builder.Configuration.GetSection(ColorOptions.Color));
builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();
var app = builder.Build();
Related groups of registrations can be moved to an extension method to register services. For example, the configuration services are added to the following class:
using ConfigSample.Options;
using Microsoft.Extensions.Configuration;
namespace Microsoft.Extensions.DependencyInjection
{
public static class MyConfigServiceCollectionExtensions
{
public static IServiceCollection AddConfig(
this IServiceCollection services, IConfiguration config)
{
services.Configure<PositionOptions>(
config.GetSection(PositionOptions.Position));
services.Configure<ColorOptions>(
config.GetSection(ColorOptions.Color));
return services;
}
public static IServiceCollection AddMyDependencyGroup(
this IServiceCollection services)
{
services.AddScoped<IMyDependency, MyDependency>();
services.AddScoped<IMyDependency2, MyDependency2>();
return services;
}
}
}
The remaining services are registered in a similar class. The following code uses the new extension methods to register the services:
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddConfig(builder.Configuration)
.AddMyDependencyGroup();
builder.Services.AddRazorPages();
var app = builder.Build();
Note: Each services.Add{GROUP_NAME}
extension method adds and potentially configures services. For example, AddControllersWithViews adds the services MVC controllers with views require, and AddRazorPages adds the services Razor Pages requires.
Configuration data guidelines:
By default, the user secrets configuration source is registered after the JSON configuration sources. Therefore, user secrets keys take precedence over keys in appsettings.json
and appsettings.{Environment}.json
.
For more information on storing passwords or other sensitive data:
Azure Key Vault safely stores app secrets for ASP.NET Core apps. For more information, see Azure Key Vault configuration provider in ASP.NET Core.
Non-prefixed environment variables are environment variables other than those prefixed by ASPNETCORE_
or DOTNET_
. For example, the ASP.NET Core web application templates set "ASPNETCORE_ENVIRONMENT": "Development"
in launchSettings.json
. For more information on ASPNETCORE_
and DOTNET_
environment variables, see:
ASPNETCORE_
-prefixed and DOTNETCORE_
-prefixed environment variables.DOTNET_
environment variables used outside of Microsoft.Extensions.Hosting.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json
, appsettings.{Environment}.json
, and user secrets. Therefore, key values read from the environment override values read from appsettings.json
, appsettings.{Environment}.json
, and user secrets.
The :
separator doesn't work with environment variable hierarchical keys on all platforms. For example, the :
separator is not supported by Bash. The double underscore, __
, is:
:
.The following set
commands:
dotnet run
command must be run in the project directory.set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run
The preceding environment settings:
The following setx commands can be used to set the environment keys and values on Windows. Unlike set
, setx
settings are persisted. /M
sets the variable in the system environment. If the /M
switch isn't used, a user environment variable is set.
setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M
To test that the preceding commands override appsettings.json
and appsettings.{Environment}.json
:
dotnet run
.Call AddEnvironmentVariables with a string to specify a prefix for environment variables:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
var app = builder.Build();
In the preceding code:
builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_")
is added after the default configuration providers. For an example of ordering the configuration providers, see JSON configuration provider.MyCustomPrefix_
prefix override the default configuration providers. This includes environment variables without the prefix.The prefix is stripped off when the configuration key-value pairs are read.
The following commands test the custom prefix:
set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run
The default configuration loads environment variables and command line arguments prefixed with DOTNET_
and ASPNETCORE_
. The DOTNET_
and ASPNETCORE_
prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. For more information on host and app configuration, see .NET Generic Host.
On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service application settings are:
For more information, see Azure Apps: Override app configuration using the Azure Portal.
See Connection string prefixes for information on Azure database connection strings.
Environment variable names reflect the structure of an appsettings.json
file. Each element in the hierarchy is separated by a double underscore (preferable) or a colon. When the element structure includes an array, the array index should be treated as an additional element name in this path. Consider the following appsettings.json
file and its equivalent values represented as environment variables.
appsettings.json
{
"SmtpServer": "smtp.example.com",
"Logging": [
{
"Name": "ToEmail",
"Level": "Critical",
"Args": {
"FromAddress": "MySystem@example.com",
"ToAddress": "SRE@example.com"
}
},
{
"Name": "ToConsole",
"Level": "Information"
}
]
}
environment variables
setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information
Environment variables set in launchSettings.json
override those set in the system environment. For example, the ASP.NET Core web templates generate a launchSettings.json
file that sets the endpoint configuration to:
"applicationUrl": "https://localhost:5001;http://localhost:5000"
Configuring the applicationUrl
sets the ASPNETCORE_URLS
environment variable and overrides values set in the environment.
On Linux, the value of URL environment variables must be escaped so systemd
can parse it. Use the linux tool systemd-escape
which yields http:--localhost:5001
groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001
The following code displays the environment variables and values on application startup, which can be helpful when debugging environment settings:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
foreach (var c in builder.Configuration.AsEnumerable())
{
Console.WriteLine(c.Key + " = " + c.Value);
}
Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:
appsettings.json
and appsettings.{Environment}.json
files.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.
The following command sets keys and values using =
:
dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick
The following command sets keys and values using /
:
dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick
The following command sets keys and values using --
:
dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick
The key value:
=
, or the key must have a prefix of --
or /
when the value follows a space.=
is used. For example, MySetting=
.Within the same command, don't mix command-line argument key-value pairs that use =
with key-value pairs that use a space.
Switch mappings allow key name replacement logic. Provide a dictionary of switch replacements to the AddCommandLine method.
When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. If the command-line key is found in the dictionary, the dictionary value is passed back to set the key-value pair into the app's configuration. A switch mapping is required for any command-line key prefixed with a single dash (-
).
Switch mappings dictionary key rules:
-
or --
.To use a switch mappings dictionary, pass it into the call to AddCommandLine
:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var switchMappings = new Dictionary<string, string>()
{
{ "-k1", "key1" },
{ "-k2", "key2" },
{ "--alt3", "key3" },
{ "--alt4", "key4" },
{ "--alt5", "key5" },
{ "--alt6", "key6" },
};
builder.Configuration.AddCommandLine(args, switchMappings);
var app = builder.Build();
Run the following command works to test key replacement:
dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6
The following code shows the key values for the replaced keys:
public class Test3Model : PageModel
{
private readonly IConfiguration Config;
public Test3Model(IConfiguration configuration)
{
Config = configuration;
}
public ContentResult OnGet()
{
return Content(
$"Key1: '{Config["Key1"]}'\n" +
$"Key2: '{Config["Key2"]}'\n" +
$"Key3: '{Config["Key3"]}'\n" +
$"Key4: '{Config["Key4"]}'\n" +
$"Key5: '{Config["Key5"]}'\n" +
$"Key6: '{Config["Key6"]}'");
}
}
For apps that use switch mappings, the call to CreateDefaultBuilder
shouldn't pass arguments. The CreateDefaultBuilder
method's AddCommandLine
call doesn't include mapped switches, and there's no way to pass the switch-mapping dictionary to CreateDefaultBuilder
. The solution isn't to pass the arguments to CreateDefaultBuilder
but instead to allow the ConfigurationBuilder
method's AddCommandLine
method to process both the arguments and the switch-mapping dictionary.
Environment and command-line arguments can be set in Visual Studio from the launch profiles dialog:
The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.
The sample download contains the following appsettings.json
file:
{
"Position": {
"Title": "Editor",
"Name": "Joe Smith"
},
"MyKey": "My appsettings.json Value",
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
The following code from the sample download displays several of the configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The preferred way to read hierarchical configuration data is using the options pattern. For more information, see Bind hierarchical configuration data in this document.
GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. These methods are described later in GetSection, GetChildren, and Exists.
Warning
This article shows the use of connection strings. With a local database the user doesn't have to be authenticated, but in production, connection strings sometimes include a password to authenticate. A resource owner password credential (ROPC) is a security risk that should be avoided in production databases. Production apps should use the most secure authentication flow available. For more information on authentication for apps deployed to test or production environments, see Secure authentication flows.
Configuration keys:
ConnectionString
and connectionstring
are treated as equivalent keys.:
) works on all platforms.__
, is supported by all platforms and is automatically converted into a colon :
.--
as a separator. The Azure Key Vault configuration provider automatically replaces --
with a :
when the secrets are loaded into the app's configuration.Configuration values:
The following table shows the configuration providers available to ASP.NET Core apps.
Provider | Provides configuration from |
---|---|
Azure Key Vault configuration provider | Azure Key Vault |
Azure App configuration provider | Azure App Configuration |
Command-line configuration provider | Command-line parameters |
Custom configuration provider | Custom source |
Environment Variables configuration provider | Environment variables |
File configuration provider | INI, JSON, and XML files |
Key-per-file configuration provider | Directory files |
Memory configuration provider | In-memory collections |
User secrets | File in the user profile directory |
Configuration sources are read in the order that their configuration providers are specified. Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.
A typical sequence of configuration providers is:
appsettings.json
appsettings.{Environment}.json
A common practice is to add the Command-line configuration provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.
The preceding sequence of providers is used in the default configuration.
Warning
This article shows the use of connection strings. With a local database the user doesn't have to be authenticated, but in production, connection strings sometimes include a password to authenticate. A resource owner password credential (ROPC) is a security risk that should be avoided in production databases. Production apps should use the most secure authentication flow available. For more information on authentication for apps deployed to test or production environments, see Secure authentication flows.
The Configuration API has special processing rules for four connection string environment variables. These connection strings are involved in configuring Azure connection strings for the app environment. Environment variables with the prefixes shown in the table are loaded into the app with the default configuration or when no prefix is supplied to AddEnvironmentVariables
.
Connection string prefix | Provider |
---|---|
CUSTOMCONNSTR_ |
Custom provider |
MYSQLCONNSTR_ |
MySQL |
SQLAZURECONNSTR_ |
Azure SQL Database |
SQLCONNSTR_ |
SQL Server |
When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:
ConnectionStrings
).CUSTOMCONNSTR_
, which has no stated provider).Environment variable key | Converted configuration key | Provider configuration entry |
---|---|---|
CUSTOMCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Configuration entry not created. |
MYSQLCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: MySql.Data.MySqlClient |
SQLAZURECONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: System.Data.SqlClient |
SQLCONNSTR_{KEY} |
ConnectionStrings:{KEY} |
Key: ConnectionStrings:{KEY}_ProviderName :Value: System.Data.SqlClient |
FileConfigurationProvider is the base class for loading configuration from the file system. The following configuration providers derive from FileConfigurationProvider
:
The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.
The following code adds several configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
.AddIniFile($"MyIniConfig.{builder.Environment.EnvironmentName}.ini",
optional: true, reloadOnChange: true);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
In the preceding code, settings in the MyIniConfig.ini
and MyIniConfig.{Environment}.ini
files are overridden by settings in the:
The sample download contains the following MyIniConfig.ini
file:
MyKey="MyIniConfig.ini Value"
[Position]
Title="My INI Config title"
Name="My INI Config name"
[Logging:LogLevel]
Default=Information
Microsoft=Warning
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
The JsonConfigurationProvider loads configuration from JSON file key-value pairs.
Overloads can specify:
Consider the following code:
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddJsonFile("MyConfig.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
The preceding code:
MyConfig.json
file with the following options:
optional: true
: The file is optional.reloadOnChange: true
: The file is reloaded when changes are saved.MyConfig.json
file. Settings in the MyConfig.json
file override setting in the default configuration providers, including the Environment variables configuration provider and the Command-line configuration provider.You typically don't want a custom JSON file overriding values set in the Environment variables configuration provider and the Command-line configuration provider.
The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.
The following code adds several configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
.AddXmlFile($"MyXMLFile.{builder.Environment.EnvironmentName}.xml",
optional: true, reloadOnChange: true);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
In the preceding code, settings in the MyXMLFile.xml
and MyXMLFile.{Environment}.xml
files are overridden by settings in the:
The sample download contains the following MyXMLFile.xml
file:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<MyKey>MyXMLFile Value</MyKey>
<Position>
<Title>Title from MyXMLFile</Title>
<Name>Name from MyXMLFile</Name>
</Position>
<Logging>
<LogLevel>
<Default>Information</Default>
<Microsoft>Warning</Microsoft>
</LogLevel>
</Logging>
</configuration>
The following code from the sample download displays several of the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
Repeating elements that use the same element name work if the name
attribute is used to distinguish the elements:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<section name="section0">
<key name="key0">value 00</key>
<key name="key1">value 01</key>
</section>
<section name="section1">
<key name="key0">value 10</key>
<key name="key1">value 11</key>
</section>
</configuration>
The following code reads the previous configuration file and displays the keys and values:
public class IndexModel : PageModel
{
private readonly IConfiguration Configuration;
public IndexModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var key00 = "section:section0:key:key0";
var key01 = "section:section0:key:key1";
var key10 = "section:section1:key:key0";
var key11 = "section:section1:key:key1";
var val00 = Configuration[key00];
var val01 = Configuration[key01];
var val10 = Configuration[key10];
var val11 = Configuration[key11];
return Content($"{key00} value: {val00} \n" +
$"{key01} value: {val01} \n" +
$"{key10} value: {val10} \n" +
$"{key10} value: {val11} \n"
);
}
}
Attributes can be used to supply values:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<key attribute="value" />
<section>
<key attribute="value" />
</section>
</configuration>
The previous configuration file loads the following keys with value
:
The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. The key is the file name. The value contains the file's contents. The Key-per-file configuration provider is used in Docker hosting scenarios.
To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. The directoryPath
to the files must be an absolute path.
Overloads permit specifying:
Action<KeyPerFileConfigurationSource>
delegate that configures the source.The double-underscore (__
) is used as a configuration key delimiter in file names. For example, the file name Logging__LogLevel__System
produces the configuration key Logging:LogLevel:System
.
Call ConfigureAppConfiguration
when building the host to specify the app's configuration:
.ConfigureAppConfiguration((hostingContext, config) =>
{
var path = Path.Combine(
Directory.GetCurrentDirectory(), "path/to/files");
config.AddKeyPerFile(directoryPath: path, optional: true);
})
The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.
The following code adds a memory collection to the configuration system:
var builder = WebApplication.CreateBuilder(args);
var Dict = new Dictionary<string, string>
{
{"MyKey", "Dictionary MyKey Value"},
{"Position:Title", "Dictionary_Title"},
{"Position:Name", "Dictionary_Name" },
{"Logging:LogLevel:Default", "Warning"}
};
builder.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);
builder.Services.AddRazorPages();
var app = builder.Build();
The following code from the sample download displays the preceding configurations settings:
public class TestModel : PageModel
{
// requires using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public TestModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var myKeyValue = Configuration["MyKey"];
var title = Configuration["Position:Title"];
var name = Configuration["Position:Name"];
var defaultLogLevel = Configuration["Logging:LogLevel:Default"];
return Content($"MyKey value: {myKeyValue} \n" +
$"Title: {title} \n" +
$"Name: {name} \n" +
$"Default Log Level: {defaultLogLevel}");
}
}
In the preceding code, config.AddInMemoryCollection(Dict)
is added after the default configuration providers. For an example of ordering the configuration providers, see JSON configuration provider.
See Bind an array for another example using MemoryConfigurationProvider
.
Kestrel specific endpoint configuration overrides all cross-server endpoint configurations. Cross-server endpoint configurations include:
--urls
on the command lineASPNETCORE_URLS
Consider the following appsettings.json
file used in an ASP.NET Core web app:
{
"Kestrel": {
"Endpoints": {
"Https": {
"Url": "https://localhost:9999"
}
}
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
When the preceding highlighted markup is used in an ASP.NET Core web app and the app is launched on the command line with the following cross-server endpoint configuration:
dotnet run --urls="https://localhost:7777"
Kestrel binds to the endpoint configured specifically for Kestrel in the appsettings.json
file (https://localhost:9999
) and not https://localhost:7777
.
Consider the Kestrel specific endpoint configured as an environment variable:
set Kestrel__Endpoints__Https__Url=https://localhost:8888
In the preceding environment variable, Https
is the name of the Kestrel specific endpoint. The preceding appsettings.json
file also defines a Kestrel specific endpoint named Https
. By default, environment variables using the Environment Variables configuration provider are read after appsettings.{Environment}.json
, therefore, the preceding environment variable is used for the Https
endpoint.
ConfigurationBinder.GetValue extracts a single value from configuration with a specified key and converts it to the specified type:
public class TestNumModel : PageModel
{
private readonly IConfiguration Configuration;
public TestNumModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var number = Configuration.GetValue<int>("NumberKey", 99);
return Content($"{number}");
}
}
In the preceding code, if NumberKey
isn't found in the configuration, the default value of 99
is used.
For the examples that follow, consider the following MySubsection.json
file:
{
"section0": {
"key0": "value00",
"key1": "value01"
},
"section1": {
"key0": "value10",
"key1": "value11"
},
"section2": {
"subsection0": {
"key0": "value200",
"key1": "value201"
},
"subsection1": {
"key0": "value210",
"key1": "value211"
}
}
}
The following code adds MySubsection.json
to the configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("MySubsection.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
IConfiguration.GetSection returns a configuration subsection with the specified subsection key.
The following code returns values for section1
:
public class TestSectionModel : PageModel
{
private readonly IConfiguration Config;
public TestSectionModel(IConfiguration configuration)
{
Config = configuration.GetSection("section1");
}
public ContentResult OnGet()
{
return Content(
$"section1:key0: '{Config["key0"]}'\n" +
$"section1:key1: '{Config["key1"]}'");
}
}
The following code returns values for section2:subsection0
:
public class TestSection2Model : PageModel
{
private readonly IConfiguration Config;
public TestSection2Model(IConfiguration configuration)
{
Config = configuration.GetSection("section2:subsection0");
}
public ContentResult OnGet()
{
return Content(
$"section2:subsection0:key0 '{Config["key0"]}'\n" +
$"section2:subsection0:key1:'{Config["key1"]}'");
}
}
GetSection
never returns null
. If a matching section isn't found, an empty IConfigurationSection
is returned.
When GetSection
returns a matching section, Value isn't populated. A Key and Path are returned when the section exists.
The following code calls IConfiguration.GetChildren and returns values for section2:subsection0
:
public class TestSection4Model : PageModel
{
private readonly IConfiguration Config;
public TestSection4Model(IConfiguration configuration)
{
Config = configuration;
}
public ContentResult OnGet()
{
string s = "";
var selection = Config.GetSection("section2");
if (!selection.Exists())
{
throw new Exception("section2 does not exist.");
}
var children = selection.GetChildren();
foreach (var subSection in children)
{
int i = 0;
var key1 = subSection.Key + ":key" + i++.ToString();
var key2 = subSection.Key + ":key" + i.ToString();
s += key1 + " value: " + selection[key1] + "\n";
s += key2 + " value: " + selection[key2] + "\n";
}
return Content(s);
}
}
The preceding code calls ConfigurationExtensions.Exists to verify the section exists:
The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.
Consider MyArray.json
from the sample download:
{
"array": {
"entries": {
"0": "value00",
"1": "value10",
"2": "value20",
"4": "value40",
"5": "value50"
}
}
}
The following code adds MyArray.json
to the configuration providers:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("MyArray.json",
optional: true,
reloadOnChange: true);
builder.Services.AddRazorPages();
var app = builder.Build();
The following code reads the configuration and displays the values:
public class ArrayModel : PageModel
{
private readonly IConfiguration Config;
public ArrayExample? _array { get; private set; }
public ArrayModel(IConfiguration config)
{
Config = config;
}
public ContentResult OnGet()
{
_array = Config.GetSection("array").Get<ArrayExample>();
if (_array == null)
{
throw new ArgumentNullException(nameof(_array));
}
string s = String.Empty;
for (int j = 0; j < _array.Entries.Length; j++)
{
s += $"Index: {j} Value: {_array.Entries[j]} \n";
}
return Content(s);
}
}
public class ArrayExample
{
public string[]? Entries { get; set; }
}
The preceding code returns the following output:
Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value40
Index: 4 Value: value50
In the preceding output, Index 3 has value value40
, corresponding to "4": "value40",
in MyArray.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.
The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).
The provider has the following characteristics:
ConfigurationBuilder
to supply the connection string from another configuration provider.Define an EFConfigurationValue
entity for storing configuration values in the database.
Models/EFConfigurationValue.cs
:
public class EFConfigurationValue
{
public string Id { get; set; } = String.Empty;
public string Value { get; set; } = String.Empty;
}
Add an EFConfigurationContext
to store and access the configured values.
EFConfigurationProvider/EFConfigurationContext.cs
:
public class EFConfigurationContext : DbContext
{
public EFConfigurationContext(DbContextOptions<EFConfigurationContext> options) : base(options)
{
}
public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}
Create a class that implements IConfigurationSource.
EFConfigurationProvider/EFConfigurationSource.cs
:
public class EFConfigurationSource : IConfigurationSource
{
private readonly Action<DbContextOptionsBuilder> _optionsAction;
public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => _optionsAction = optionsAction;
public IConfigurationProvider Build(IConfigurationBuilder builder) => new EFConfigurationProvider(_optionsAction);
}
Create the custom configuration provider by inheriting from ConfigurationProvider. The configuration provider initializes the database when it's empty. Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).
EFConfigurationProvider/EFConfigurationProvider.cs
:
public class EFConfigurationProvider : ConfigurationProvider
{
public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
{
OptionsAction = optionsAction;
}
Action<DbContextOptionsBuilder> OptionsAction { get; }
public override void Load()
{
var builder = new DbContextOptionsBuilder<EFConfigurationContext>();
OptionsAction(builder);
using (var dbContext = new EFConfigurationContext(builder.Options))
{
if (dbContext == null || dbContext.Values == null)
{
throw new Exception("Null DB context");
}
dbContext.Database.EnsureCreated();
Data = !dbContext.Values.Any()
? CreateAndSaveDefaultValues(dbContext)
: dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
}
}
private static IDictionary<string, string> CreateAndSaveDefaultValues(
EFConfigurationContext dbContext)
{
// Quotes (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity-2005
var configValues =
new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{
{ "quote1", "I aim to misbehave." },
{ "quote2", "I swallowed a bug." },
{ "quote3", "You can't stop the signal, Mal." }
};
if (dbContext == null || dbContext.Values == null)
{
throw new Exception("Null DB context");
}
dbContext.Values.AddRange(configValues
.Select(kvp => new EFConfigurationValue
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
dbContext.SaveChanges();
return configValues;
}
}
An AddEFConfiguration
extension method permits adding the configuration source to a ConfigurationBuilder
.
Extensions/EntityFrameworkExtensions.cs
:
public static class EntityFrameworkExtensions
{
public static IConfigurationBuilder AddEFConfiguration(
this IConfigurationBuilder builder,
Action<DbContextOptionsBuilder> optionsAction)
{
return builder.Add(new EFConfigurationSource(optionsAction));
}
}
The following code shows how to use the custom EFConfigurationProvider
in Program.cs
:
//using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddEFConfiguration(
opt => opt.UseInMemoryDatabase("InMemoryDb"));
var app = builder.Build();
app.Run();
Configuration can be injected into services using Dependency Injection (DI) by resolving the IConfiguration service:
public class Service
{
private readonly IConfiguration _config;
public Service(IConfiguration config) =>
_config = config;
public void DoSomething()
{
var configSettingValue = _config["ConfigSetting"];
// ...
}
}
For information on how to access values using IConfiguration
, see GetValue and GetSection, GetChildren, and Exists in this article.
The following code displays configuration data in a Razor Page:
@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
In the following code, MyOptions
is added to the service container with Configure and bound to configuration:
using SampleApp.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<MyOptions>(
builder.Configuration.GetSection("MyOptions"));
var app = builder.Build();
The following markup uses the @inject
Razor directive to resolve and display the options values:
@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor
<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>
The following code displays configuration data in a MVC view:
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
The following code accesses configuration in the Program.cs
file.
var builder = WebApplication.CreateBuilder(args);
var key1 = builder.Configuration.GetValue<string>("KeyOne");
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
var key2 = app.Configuration.GetValue<int>("KeyTwo");
var key3 = app.Configuration.GetValue<bool>("KeyThree");
app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);
app.Run();
In appsettings.json
for the preceding example:
{
...
"KeyOne": "Key One Value",
"KeyTwo": 1999,
"KeyThree": true
}
Options configured in a delegate override values set in the configuration providers.
In the following code, an IConfigureOptions<TOptions> service is added to the service container. It uses a delegate to configure values for MyOptions
:
using SampleApp.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.Configure<MyOptions>(myOptions =>
{
myOptions.Option1 = "Value configured in delegate";
myOptions.Option2 = 500;
});
var app = builder.Build();
The following code displays the options values:
public class Test2Model : PageModel
{
private readonly IOptions<MyOptions> _optionsDelegate;
public Test2Model(IOptions<MyOptions> optionsDelegate )
{
_optionsDelegate = optionsDelegate;
}
public ContentResult OnGet()
{
return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
$"Option2: {_optionsDelegate.Value.Option2}");
}
}
In the preceding example, the values of Option1
and Option2
are specified in appsettings.json
and then overridden by the configured delegate.
Before the app is configured and started, a host is configured and launched. The host is responsible for app startup and lifetime management. Both the app and the host are configured using the configuration providers described in this topic. Host configuration key-value pairs are also included in the app's configuration. For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see ASP.NET Core fundamentals overview.
For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.
DOTNET_
(for example, DOTNET_ENVIRONMENT
) using the Environment Variables configuration provider. The prefix (DOTNET_
) is stripped when the configuration key-value pairs are loaded.ConfigureWebHostDefaults
):
ASPNETCORE_FORWARDEDHEADERS_ENABLED
environment variable is set to true
.This topic only pertains to app configuration. Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:
launch.json
/launchSettings.json
are tooling configuration files for the Development environment, described:
web.config
is a server configuration file, described in the following topics:
Environment variables set in launchSettings.json
override those set in the system environment.
For more information on migrating app configuration from earlier versions of ASP.NET, see Update from ASP.NET to ASP.NET Core.
An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup
class. For more information, see Use hosting startup assemblies in ASP.NET Core.
Kestrel specific endpoint configuration overrides all cross-server endpoint configurations. Cross-server endpoint configurations include:
--urls
on the command lineASPNETCORE_URLS
Consider the following appsettings.json
file used in an ASP.NET Core web app:
{
"Kestrel": {
"Endpoints": {
"Https": {
"Url": "https://localhost:9999"
}
}
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
When the preceding highlighted markup is used in an ASP.NET Core web app and the app is launched on the command line with the following cross-server endpoint configuration:
dotnet run --urls="https://localhost:7777"
Kestrel binds to the endpoint configured specifically for Kestrel in the appsettings.json
file (https://localhost:9999
) and not https://localhost:7777
.
Consider the Kestrel specific endpoint configured as an environment variable:
set Kestrel__Endpoints__Https__Url=https://localhost:8888
In the preceding environment variable, Https
is the name of the Kestrel specific endpoint. The preceding appsettings.json
file also defines a Kestrel specific endpoint named Https
. By default, environment variables using the Environment Variables configuration provider are read after appsettings.{Environment}.json
, therefore, the preceding environment variable is used for the Https
endpoint.
ConfigurationBinder.GetValue extracts a single value from configuration with a specified key and converts it to the specified type. This method is an extension method for IConfiguration:
public class TestNumModel : PageModel
{
private readonly IConfiguration Configuration;
public TestNumModel(IConfiguration configuration)
{
Configuration = configuration;
}
public ContentResult OnGet()
{
var number = Configuration.GetValue<int>("NumberKey", 99);
return Content($"{number}");
}
}
In the preceding code, if NumberKey
isn't found in the configuration, the default value of 99
is used.
For the examples that follow, consider the following MySubsection.json
file:
{
"section0": {
"key0": "value00",
"key1": "value01"
},
"section1": {
"key0": "value10",
"key1": "value11"
},
"section2": {
"subsection0": {
"key0": "value200",
"key1": "value201"
},
"subsection1": {
"key0": "value210",
"key1": "value211"
}
}
}
The following code adds MySubsection.json
to the configuration providers:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddJsonFile("MySubsection.json",
optional: true,
reloadOnChange: true);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
IConfiguration.GetSection returns a configuration subsection with the specified subsection key.
The following code returns values for section1
:
public class TestSectionModel : PageModel
{
private readonly IConfiguration Config;
public TestSectionModel(IConfiguration configuration)
{
Config = configuration.GetSection("section1");
}
public ContentResult OnGet()
{
return Content(
$"section1:key0: '{Config["key0"]}'\n" +
$"section1:key1: '{Config["key1"]}'");
}
}
The following code returns values for section2:subsection0
:
public class TestSection2Model : PageModel
{
private readonly IConfiguration Config;
public TestSection2Model(IConfiguration configuration)
{
Config = configuration.GetSection("section2:subsection0");
}
public ContentResult OnGet()
{
return Content(
$"section2:subsection0:key0 '{Config["key0"]}'\n" +
$"section2:subsection0:key1:'{Config["key1"]}'");
}
}
GetSection
never returns null
. If a matching section isn't found, an empty IConfigurationSection
is returned.
When GetSection
returns a matching section, Value isn't populated. A Key and Path are returned when the section exists.
The following code calls IConfiguration.GetChildren and returns values for section2:subsection0
:
public class TestSection4Model : PageModel
{
private readonly IConfiguration Config;
public TestSection4Model(IConfiguration configuration)
{
Config = configuration;
}
public ContentResult OnGet()
{
string s = null;
var selection = Config.GetSection("section2");
if (!selection.Exists())
{
throw new System.Exception("section2 does not exist.");
}
var children = selection.GetChildren();
foreach (var subSection in children)
{
int i = 0;
var key1 = subSection.Key + ":key" + i++.ToString();
var key2 = subSection.Key + ":key" + i.ToString();
s += key1 + " value: " + selection[key1] + "\n";
s += key2 + " value: " + selection[key2] + "\n";
}
return Content(s);
}
}
The preceding code calls ConfigurationExtensions.Exists to verify the section exists:
The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.
Consider MyArray.json
from the sample download:
{
"array": {
"entries": {
"0": "value00",
"1": "value10",
"2": "value20",
"4": "value40",
"5": "value50"
}
}
}
The following code adds MyArray.json
to the configuration providers:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddJsonFile("MyArray.json",
optional: true,
reloadOnChange: true);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
The following code reads the configuration and displays the values:
public class ArrayModel : PageModel
{
private readonly IConfiguration Config;
public ArrayExample _array { get; private set; }
public ArrayModel(IConfiguration config)
{
Config = config;
}
public ContentResult OnGet()
{
_array = Config.GetSection("array").Get<ArrayExample>();
string s = null;
for (int j = 0; j < _array.Entries.Length; j++)
{
s += $"Index: {j} Value: {_array.Entries[j]} \n";
}
return Content(s);
}
}
The preceding code returns the following output:
Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value40
Index: 4 Value: value50
In the preceding output, Index 3 has value value40
, corresponding to "4": "value40",
in MyArray.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
The following code loads the array:entries
configuration with the AddInMemoryCollection extension method:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args)
{
var arrayDict = new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
// 3 Skipped
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};
return Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddInMemoryCollection(arrayDict);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
}
The following code reads the configuration in the arrayDict
Dictionary
and displays the values:
public class ArrayModel : PageModel
{
private readonly IConfiguration Config;
public ArrayExample _array { get; private set; }
public ArrayModel(IConfiguration config)
{
Config = config;
}
public ContentResult OnGet()
{
_array = Config.GetSection("array").Get<ArrayExample>();
string s = null;
for (int j = 0; j < _array.Entries.Length; j++)
{
s += $"Index: {j} Value: {_array.Entries[j]} \n";
}
return Content(s);
}
}
The preceding code returns the following output:
Index: 0 Value: value0
Index: 1 Value: value1
Index: 2 Value: value2
Index: 3 Value: value4
Index: 4 Value: value5
Index #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.
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. Consider the following Value3.json
file from the sample download:
{
"array:entries:3": "value3"
}
The following code includes configuration for Value3.json
and the arrayDict
Dictionary
:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args)
{
var arrayDict = new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
// 3 Skipped
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};
return Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddInMemoryCollection(arrayDict);
config.AddJsonFile("Value3.json",
optional: false, reloadOnChange: false);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
}
The following code reads the preceding configuration and displays the values:
public class ArrayModel : PageModel
{
private readonly IConfiguration Config;
public ArrayExample _array { get; private set; }
public ArrayModel(IConfiguration config)
{
Config = config;
}
public ContentResult OnGet()
{
_array = Config.GetSection("array").Get<ArrayExample>();
string s = null;
for (int j = 0; j < _array.Entries.Length; j++)
{
s += $"Index: {j} Value: {_array.Entries[j]} \n";
}
return Content(s);
}
}
The preceding code returns the following output:
Index: 0 Value: value0
Index: 1 Value: value1
Index: 2 Value: value2
Index: 3 Value: value3
Index: 4 Value: value4
Index: 5 Value: value5
Custom configuration providers aren't required to implement array binding.
Warning
This article shows the use of connection strings. With a local database the user doesn't have to be authenticated, but in production, connection strings sometimes include a password to authenticate. A resource owner password credential (ROPC) is a security risk that should be avoided in production databases. Production apps should use the most secure authentication flow available. For more information on authentication for apps deployed to test or production environments, see Secure authentication flows.
The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).
The provider has the following characteristics:
ConfigurationBuilder
to supply the connection string from another configuration provider.Define an EFConfigurationValue
entity for storing configuration values in the database.
Models/EFConfigurationValue.cs
:
public class EFConfigurationValue
{
public string Id { get; set; }
public string Value { get; set; }
}
Add an EFConfigurationContext
to store and access the configured values.
EFConfigurationProvider/EFConfigurationContext.cs
:
// using Microsoft.EntityFrameworkCore;
public class EFConfigurationContext : DbContext
{
public EFConfigurationContext(DbContextOptions options) : base(options)
{
}
public DbSet<EFConfigurationValue> Values { get; set; }
}
Create a class that implements IConfigurationSource.
EFConfigurationProvider/EFConfigurationSource.cs
:
// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;
public class EFConfigurationSource : IConfigurationSource
{
private readonly Action<DbContextOptionsBuilder> _optionsAction;
public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)
{
_optionsAction = optionsAction;
}
public IConfigurationProvider Build(IConfigurationBuilder builder)
{
return new EFConfigurationProvider(_optionsAction);
}
}
Create the custom configuration provider by inheriting from ConfigurationProvider. The configuration provider initializes the database when it's empty. Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).
EFConfigurationProvider/EFConfigurationProvider.cs
:
// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;
public class EFConfigurationProvider : ConfigurationProvider
{
public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
{
OptionsAction = optionsAction;
}
Action<DbContextOptionsBuilder> OptionsAction { get; }
public override void Load()
{
var builder = new DbContextOptionsBuilder<EFConfigurationContext>();
OptionsAction(builder);
using (var dbContext = new EFConfigurationContext(builder.Options))
{
dbContext.Database.EnsureCreated();
Data = !dbContext.Values.Any()
? CreateAndSaveDefaultValues(dbContext)
: dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
}
}
private static IDictionary<string, string> CreateAndSaveDefaultValues(
EFConfigurationContext dbContext)
{
// Quotes (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity-2005
var configValues =
new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{
{ "quote1", "I aim to misbehave." },
{ "quote2", "I swallowed a bug." },
{ "quote3", "You can't stop the signal, Mal." }
};
dbContext.Values.AddRange(configValues
.Select(kvp => new EFConfigurationValue
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
dbContext.SaveChanges();
return configValues;
}
}
An AddEFConfiguration
extension method permits adding the configuration source to a ConfigurationBuilder
.
Extensions/EntityFrameworkExtensions.cs
:
// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;
public static class EntityFrameworkExtensions
{
public static IConfigurationBuilder AddEFConfiguration(
this IConfigurationBuilder builder,
Action<DbContextOptionsBuilder> optionsAction)
{
return builder.Add(new EFConfigurationSource(optionsAction));
}
}
The following code shows how to use the custom EFConfigurationProvider
in Program.cs
:
// using Microsoft.EntityFrameworkCore;
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddEFConfiguration(
options => options.UseInMemoryDatabase("InMemoryDb"));
})
The following code displays configuration data in Startup
methods:
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
Console.WriteLine($"MyKey : {Configuration["MyKey"]}");
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
Console.WriteLine($"Position:Title : {Configuration["Position:Title"]}");
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
}
For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.
The following code displays configuration data in a Razor Page:
@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
In the following code, MyOptions
is added to the service container with Configure and bound to configuration:
public void ConfigureServices(IServiceCollection services)
{
services.Configure<MyOptions>(Configuration.GetSection("MyOptions"));
services.AddRazorPages();
}
The following markup uses the @inject
Razor directive to resolve and display the options values:
@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@inject IOptions<MyOptions> optionsAccessor
<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>
The following code displays configuration data in a MVC view:
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Configuration value for 'MyKey': @Configuration["MyKey"]
Options configured in a delegate override values set in the configuration providers.
Configuring options with a delegate is demonstrated as Example 2 in the sample app.
In the following code, an IConfigureOptions<TOptions> service is added to the service container. It uses a delegate to configure values for MyOptions
:
public void ConfigureServices(IServiceCollection services)
{
services.Configure<MyOptions>(myOptions =>
{
myOptions.Option1 = "Value configured in delegate";
myOptions.Option2 = 500;
});
services.AddRazorPages();
}
The following code displays the options values:
public class Test2Model : PageModel
{
private readonly IOptions<MyOptions> _optionsDelegate;
public Test2Model(IOptions<MyOptions> optionsDelegate )
{
_optionsDelegate = optionsDelegate;
}
public ContentResult OnGet()
{
return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
$"Option2: {_optionsDelegate.Value.Option2}");
}
}
In the preceding example, the values of Option1
and Option2
are specified in appsettings.json
and then overridden by the configured delegate.
Before the app is configured and started, a host is configured and launched. The host is responsible for app startup and lifetime management. Both the app and the host are configured using the configuration providers described in this topic. Host configuration key-value pairs are also included in the app's configuration. For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see ASP.NET Core fundamentals overview.
For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.
DOTNET_
(for example, DOTNET_ENVIRONMENT
) using the Environment Variables configuration provider. The prefix (DOTNET_
) is stripped when the configuration key-value pairs are loaded.ConfigureWebHostDefaults
):
ASPNETCORE_FORWARDEDHEADERS_ENABLED
environment variable is set to true
.This topic only pertains to app configuration. Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:
launch.json
/launchSettings.json
are tooling configuration files for the Development environment, described:
web.config
is a server configuration file, described in the following topics:
Environment variables set in launchSettings.json
override those set in the system environment.
For more information on migrating app configuration from earlier versions of ASP.NET, see Update from ASP.NET to ASP.NET Core.
An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup
class. For more information, see Use hosting startup assemblies in ASP.NET Core.
ASP.NET Core feedback
ASP.NET Core is an open source project. Select a link to provide feedback:
Events
Nov 19, 11 PM - Nov 21, 11 PM
Join online sessions at Microsoft Ignite created to expand your skills and help you tackle today's complex issues.
Register nowTraining
Module
Externalize the configuration of an ASP.NET app by using an Azure key vault - Training
Learn how to use ConfigurationBuilder to dynamically configure an ASP.NET web app to retrieve secrets from an Azure key vault.