설정

Steve Smith, Daniel Roth

ASP.NET Core 에서는 다양한 설정 방법을 제공합니다. 어플리케이션 설정 데이터는 JSON 이나 XML, INI 형식의 파일이나 시스템 환경변수, 커맨드 라인 매개변수, 메모리 상의 컬렉션으로 저장할 수 있습니다. 또한 사용자 정의 설정 제공자 를 통해 여러분 만의 형식을 사용할 수도 있습니다.

샘플 코드를 확인하거나 다운로드 받으세요.

설정 상태를 얻거나 지정하기

ASP.NET Core 의 설정 시스템은 이전 버전의 ASP.NET 의 시스템을 재설계하여 제작되었습니다. 이전 버전에서는 System.Configuration 과 web.config 와 같은 XML 설정 파일에 의존하였습니다. 새 설정 시스템에서는 다양한 데이터 저장 형태를 지원하고 이를 통해 얻은 키-값 형태의 데이터에 대한 스트림라인 형태의 접근 방식을 제공합니다. 어플리케이션과 프레임워크에서 새로운 옵션 패턴 과 강력한 형 (strongly typed) 에 기반한 방식으로 설정에 접근할 수 있습니다.

여러분의 ASP.NET 어플리케이션에서 설정을 사용하려 하는 경우, Startup 클래스의 Configuration 을 생성하는 방법 권장합니다. 그리고 각각의 설정에 접근할 때는 옵션 패턴 을 사용하십시오.

At its simplest, Configuration is just a collection of sources, which provide the ability to read and write name/value pairs. If a name/value pair is written to Configuration, it is not persisted. This means that the written value will be lost when the sources are read again. 가장 간단한 방법으로는 Configuration

You must configure at least one source in order for Configuration to function correctly. The following sample shows how to test working with Configuration as a key/value store:

var builder = new ConfigurationBuilder();
builder.AddInMemoryCollection();
var config = builder.Build();
config["somekey"] = "somevalue";

// do some other work

var setting = config["somekey"]; // also returns "somevalue"

주석

You must set at least one configuration source.

It’s not unusual to store configuration values in a hierarchical structure, especially when using external files (e.g. JSON, XML, INI). In this case, configuration values can be retrieved using a : separated key, starting from the root of the hierarchy. For example, consider the following appsettings.json file:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=aspnet-WebApplication1-26e8893e-d7c0-4fc6-8aab-29b59971d622;Trusted_Connection=True;MultipleActiveResultSets=true"
  },
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

The application uses configuration to configure the right connection string. Access to the DefaultConnection setting is achieved through this key: ConnectionStrings:DefaultConnection, or by using the GetConnectionString extension method and passing in "DefaultConnection".

The settings required by your application and the mechanism used to specify those settings (configuration being one example) can be decoupled using the options pattern. To use the options pattern you create your own options class (probably several different classes, corresponding to different cohesive groups of settings) that you can inject into your application using an options service. You can then specify your settings using configuration or whatever mechanism you choose.

주석

You could store your Configuration instance as a service, but this would unnecessarily couple your application to a single configuration system and specific configuration keys. Instead, you can use the Options pattern to avoid these issues.

Using the built-in sources

The configuration framework has built-in support for JSON, XML, and INI configuration files, as well as support for in-memory configuration (directly setting values in code) and the ability to pull configuration from environment variables and command line parameters. Developers are not limited to using a single configuration source. In fact several may be set up together such that a default configuration is overridden by settings from another source if they are present.

Adding support for additional configuration sources is accomplished through extension methods. These methods can be called on a ConfigurationBuilder instance in a standalone fashion, or chained together as a fluent API. Both of these approaches are demonstrated in the sample below.

// work with with a builder using multiple calls
var builder = new ConfigurationBuilder();
builder.SetBasePath(Directory.GetCurrentDirectory());
builder.AddJsonFile("appsettings.json");
var connectionStringConfig = builder.Build();

// chain calls together as a fluent API
var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json")
    .AddEntityFrameworkConfig(options =>
        options.UseSqlServer(connectionStringConfig.GetConnectionString("DefaultConnection"))
    )
    .Build();

The order in which configuration sources are specified is important, as this establishes the precedence with which settings will be applied if they exist in multiple locations. In the example below, if the same setting exists in both appsettings.json and in an environment variable, the setting from the environment variable will be the one that is used. The last configuration source specified “wins” if a setting exists in more than one location. The ASP.NET team recommends specifying environment variables last, so that the local environment can override anything set in deployed configuration files.

주석

To override nested keys through environment variables in shells that don’t support : in variable names, replace them with __ (double underscore).

It can be useful to have environment-specific configuration files. This can be achieved using the following:

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

    if (env.IsDevelopment())
    {
        // For more details on using the user secret store see http://go.microsoft.com/fwlink/?LinkID=532709
        builder.AddUserSecrets();
    }

    builder.AddEnvironmentVariables();
    Configuration = builder.Build();
}

The IHostingEnvironment service is used to get the current environment. In the Development environment, the highlighted line of code above would look for a file named appsettings.Development.json and use its values, overriding any other values, if it’s present. Learn more about Working with Multiple Environments (류지형님).

When specifying files as configuration sources, you can optionally specify whether changes to the file should result in the settings being reloaded. This is configured by passing in a true value for the reloadOnChange parameter when calling AddJsonFile or similar file-based extension methods.

경고

You should never store passwords or other sensitive data in configuration provider code or in plain text configuration files. You also shouldn’t use production secrets in your development or test environments. Instead, such secrets should be specified outside the project tree, so they cannot be accidentally committed into the configuration provider repository. Learn more about Working with Multiple Environments (류지형님) and managing Safe storage of app secrets during development.

One way to leverage the order precedence of Configuration is to specify default values, which can be overridden. In the console application below, a default value for the username setting is specified in an in-memory collection, but this is overridden if a command line argument for username is passed to the application. You can see in the output how many different configuration sources are configured in the application at each stage of its execution.

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Configuration;

namespace ConfigConsole
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            var builder = new ConfigurationBuilder();
            Console.WriteLine("Initial Config Sources: " + builder.Sources.Count());

            builder.AddInMemoryCollection(new Dictionary<string, string>
            {
                { "username", "Guest" }
            });

            Console.WriteLine("Added Memory Source. Sources: " + builder.Sources.Count());

            builder.AddCommandLine(args);
            Console.WriteLine("Added Command Line Source. Sources: " + builder.Sources.Count());

            var config = builder.Build();
            string username = config["username"];

            Console.WriteLine($"Hello, {username}!");
        }
    }
}

When run, the program will display the default value unless a command line parameter overrides it.

Using Options and configuration objects

The options pattern enables using custom options classes to represent a group of related settings. A class needs to have a public read-write property for each setting and a constructor that does not take any parameters (e.g. a default constructor) in order to be used as an options class.

It’s recommended that you create well-factored settings objects that correspond to certain features within your application, thus following the Interface Segregation Principle (ISP) (classes depend only on the configuration settings they use) as well as Separation of Concerns (settings for disparate parts of your app are managed separately, and thus are less likely to negatively impact one another).

A simple MyOptions class is shown here:

public class MyOptions
{
    public string Option1 { get; set; }
    public int Option2 { get; set; }
}

Options can be injected into your application using the IOptions<TOptions> accessor service. For example, the following controller uses IOptions<MyOptions> to access the settings it needs to render the Index view:

public class HomeController : Controller
{
    private readonly IOptions<MyOptions> _optionsAccessor;

    public HomeController(IOptions<MyOptions> optionsAccessor)
    {
        _optionsAccessor = optionsAccessor;
    }

    // GET: /<controller>/
    public IActionResult Index() => View(_optionsAccessor.Value);
}

참고

Learn more about Dependency Injection.

To setup the IOptions<TOptions> service you call the AddOptions extension method during startup in your ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    // Setup options with DI
    services.AddOptions();

The Index view displays the configured options:

You configure options using the Configure<TOptions> extension method. You can configure options using a delegate or by binding your options to configuration:

public void ConfigureServices(IServiceCollection services)
{
    // Setup options with DI
    services.AddOptions();

    // Configure MyOptions using config by installing Microsoft.Extensions.Options.ConfigurationExtensions
    services.Configure<MyOptions>(Configuration);

    // Configure MyOptions using code
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "value1_from_action";
    });

    // Configure MySubOptions using a sub-section of the appsettings.json file
    services.Configure<MySubOptions>(Configuration.GetSection("subsection"));

    // Add framework services.
    services.AddMvc();
}

When you bind options to configuration, each property in your options type is bound to a configuration key of the form property:subproperty:.... For example, the MyOptions.Option1 property is bound to the key Option1, which is read from the option1 property in appsettings.json. Note that configuration keys are case insensitive.

Each call to Configure<TOptions> adds an IConfigureOptions<TOptions> service to the service container that is used by the IOptions<TOptions> service to provide the configured options to the application or framework. If you want to configure your options using objects that must be obtained from the service container (for example, to read settings from a database) you can use the AddSingleton<IConfigureOptions<TOptions>> extension method to register a custom IConfigureOptions<TOptions> service.

You can have multiple IConfigureOptions<TOptions> services for the same option type and they are all applied in order. In the example above, the values of Option1 and Option2 are both specified in appsettings.json, but the value of Option1 is overridden by the configured delegate with the value “value1_from_action”.

Writing custom providers

In addition to using the built-in configuration providers, you can also write your own. To do so, you simply implement the IConfigurationSource interface, which exposes a Build method. The build method configures and returns an IConfigurationProvider.

Example: Entity Framework Settings

You may wish to store some of your application’s settings in a database, and access them using Entity Framework Core (EF). There are many ways in which you could choose to store such values, ranging from a simple table with a column for the setting name and another column for the setting value, to having separate columns for each setting value. In this example, we’re going to create a simple configuration provider that reads name-value pairs from a database using EF.

To start off we’ll define a simple ConfigurationValue entity for storing configuration values in the database:

public class ConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

You need a ConfigurationContext to store and access the configured values using EF:

public class ConfigurationContext : DbContext
{
    public ConfigurationContext(DbContextOptions options) : base(options)
    {
    }

    public DbSet<ConfigurationValue> Values { get; set; }
}

Create an EntityFrameworkConfigurationSource that inherits from IConfigurationSource:

using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public class EntityFrameworkConfigurationSource : IConfigurationSource
    {
        private readonly Action<DbContextOptionsBuilder> _optionsAction;

        public EntityFrameworkConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)
        {
            _optionsAction = optionsAction;
        }

        public IConfigurationProvider Build(IConfigurationBuilder builder)
        {
            return new EntityFrameworkConfigurationProvider(_optionsAction);
        }
    }
}

Next, create the custom configuration provider by inheriting from ConfigurationProvider. The configuration data is loaded by overriding the Load method, which reads in all of the configuration data from the configured database. For demonstration purposes, the configuration provider also takes care of initializing the database if it hasn’t already been created and populated:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public class EntityFrameworkConfigurationProvider : ConfigurationProvider
    {
        public EntityFrameworkConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
        {
            OptionsAction = optionsAction;
        }

        Action<DbContextOptionsBuilder> OptionsAction { get; }

        public override void Load()
        {
            var builder = new DbContextOptionsBuilder<ConfigurationContext>();
            OptionsAction(builder);

            using (var dbContext = new ConfigurationContext(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(
            ConfigurationContext dbContext)
        {
            var configValues = new Dictionary<string, string>
                {
                    { "key1", "value_from_ef_1" },
                    { "key2", "value_from_ef_2" }
                };
            dbContext.Values.AddRange(configValues
                .Select(kvp => new ConfigurationValue { Id = kvp.Key, Value = kvp.Value })
                .ToArray());
            dbContext.SaveChanges();
            return configValues;
        }
    }
}

Note the values that are being stored in the database (“value_from_ef_1” and “value_from_ef_2”); these are displayed in the sample below to demonstrate the configuration is reading values from the database properly.

By convention you can also add an AddEntityFrameworkConfiguration extension method for adding the configuration source:

using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public static class EntityFrameworkExtensions
    {
        public static IConfigurationBuilder AddEntityFrameworkConfig(
            this IConfigurationBuilder builder, Action<DbContextOptionsBuilder> setup)
        {
            return builder.Add(new EntityFrameworkConfigurationSource(setup));
        }
    }
}

You can see an example of how to use this custom configuration provider in your application in the following example. Create a new ConfigurationBuilder to set up your configuration sources. To add the EntityFrameworkConfigurationProvider, you first need to specify the EF data provider and connection string. How should you configure the connection string? Using configuration of course! Add an appsettings.json file as a configuration source to bootstrap setting up the EntityFrameworkConfigurationProvider. By adding the database settings to an existing configuration with other sources specified, any settings specified in the database will override settings specified in appsettings.json:

using System;
using System.IO;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public static class Program
    {
        public static void Main()
        {
            // work with with a builder using multiple calls
            var builder = new ConfigurationBuilder();
            builder.SetBasePath(Directory.GetCurrentDirectory());
            builder.AddJsonFile("appsettings.json");
            var connectionStringConfig = builder.Build();

            // chain calls together as a fluent API
            var config = new ConfigurationBuilder()
                .SetBasePath(Directory.GetCurrentDirectory())
                .AddJsonFile("appsettings.json")
                .AddEntityFrameworkConfig(options =>
                    options.UseSqlServer(connectionStringConfig.GetConnectionString("DefaultConnection"))
                )
                .Build();

            Console.WriteLine("key1={0}", config["key1"]);
            Console.WriteLine("key2={0}", config["key2"]);
            Console.WriteLine("key3={0}", config["key3"]);
        }
    }
}

Run the application to see the configured values:

Summary

ASP.NET Core provides a very flexible configuration model that supports a number of different file-based options, as well as command-line, in-memory, and environment variables. It works seamlessly with the options model so that you can inject strongly typed settings into your application or framework. You can create your own custom configuration providers as well, which can work with or replace the built-in providers, allowing for extreme flexibility.

Is this page helpful?

Yes No

Is this page helpful?

Sorry this wasn't helpful. characters remaining Submit Skip this

✖

Sending feedback...

Thank you for your feedback!

Error during submission!

Show comments

---