ASP.NET Core의 구성Configuration in ASP.NET Core

Rick Anderson, 표시 Michaelis, Steve Smith, 김 Roth, 및 Luke LathamRick Anderson, Mark Michaelis, Steve Smith, Daniel Roth, and Luke Latham

구성 API 앱 이름-값 쌍의 목록에 따라 구성 하는 방법을 제공 합니다.The Configuration API provides a way of configuring an app based on a list of name-value pairs. 여러 원본에서 런타임에 구성 읽기입니다.Configuration is read at runtime from multiple sources. 여러 수준 계층에 이름-값 쌍을 그룹화 할 수 있습니다.The name-value pairs can be grouped into a multi-level hierarchy. 에 대 한 구성 공급자가 있습니다.There are configuration providers for:

  • 파일 형식 (INI, JSON 및 XML)File formats (INI, JSON, and XML)
  • 명령줄 인수Command-line arguments
  • 환경 변수Environment variables
  • 메모리 내.NET 개체In-memory .NET objects
  • 암호화 된 사용자 저장소An encrypted user store
  • Azure 주요 자격 증명 모음Azure Key Vault
  • 사용자 지정 공급자가 설치 또는 만들기Custom providers, which you install or create

각 구성 값 문자열 키에 매핑됩니다.Each configuration value maps to a string key. 사용자 지정 설정을 deserialize 하는 데 기본 바인딩인 지원은 POCO 개체 (속성이 있는 간단한.NET 클래스).There's built-in binding support to deserialize settings into a custom POCO object (a simple .NET class with properties).

보거나 다운로드 샘플 코드 (다운로드 하는 방법을)View or download sample code (how to download)

단순 구성Simple configuration

다음 콘솔 응용 프로그램의 JSON 구성 공급자를 사용합니다.The following console app uses the JSON configuration provider:

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

public class Program
{
    public static IConfigurationRoot Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        Configuration = builder.Build();

        Console.WriteLine($"option1 = {Configuration["option1"]}");
        Console.WriteLine($"option2 = {Configuration["option2"]}");
        Console.WriteLine(
            $"suboption1 = {Configuration["subsection:suboption1"]}");
        Console.WriteLine();

        Console.WriteLine("Wizards:");
        Console.Write($"{Configuration["wizards:0:Name"]}, ");
        Console.WriteLine($"age {Configuration["wizards:0:Age"]}");
        Console.Write($"{Configuration["wizards:1:Name"]}, ");
        Console.WriteLine($"age {Configuration["wizards:1:Age"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

응용 프로그램을 읽고 다음 구성 설정을 표시 합니다.The app reads and displays the following configuration settings:

{
  "option1": "value1_from_json",
  "option2": 2,

  "subsection": {
    "suboption1": "subvalue1_from_json"
  },
  "wizards": [
    {
      "Name": "Gandalf",
      "Age": "1000"
    },
    {
      "Name": "Harry",
      "Age": "17"
    }
  ]
}

구성 노드는 콜론으로 구분 하는 이름-값 쌍의 계층적 목록으로 구성 합니다.Configuration consists of a hierarchical list of name-value pairs in which the nodes are separated by a colon. 액세스 값을 검색 하는 Configuration 인덱서를 해당 항목의 키:To retrieve a value, access the Configuration indexer with the corresponding item's key:

Console.WriteLine($"option1 = {Configuration["subsection:suboption1"]}");

JSON 형식 구성 소스에서 배열 작업을 콜론으로 구분 된 문자열의 일부로 배열 인덱스를 사용 합니다.To work with arrays in JSON-formatted configuration sources, use a array index as part of the colon-separated string. 다음 예제에서는 앞의 첫 번째 항목의 이름을 가져옵니다 wizards 배열:The following example gets the name of the first item in the preceding wizards array:

Console.Write($"{Configuration["wizards:0:Name"]}, ");

하지만 기본 제공에 기록 하는 이름-값 쌍의 Configuration 공급자는 하지 유지 만들 수 있습니다 값을 저장 하는 사용자 지정 공급자입니다.Name-value pairs written to the built in Configuration providers are not persisted, however, you can create a custom provider that saves values. 참조 사용자 지정 구성 공급자합니다.See custom configuration provider.

앞에 나온 샘플 값을 읽을 구성 인덱서를 사용 합니다.The preceding sample uses the configuration indexer to read values. 외부 액세스 구성으로 Startup를 사용 하 여는 옵션 패턴합니다.To access configuration outside of Startup, use the options pattern. 옵션 패턴 이 문서의 뒷부분에 표시 됩니다.The options pattern is shown later in this article.

예를 들어, 개발, 테스트 및 프로덕션 환경에 대 한 서로 다른 구성 설정을 일반적이.It's typical to have different configuration settings for different environments, for example, development, test, and production. CreateDefaultBuilder ASP.NET Core 2.x 응용 프로그램의 확장 메서드 (또는 사용 하 여 AddJsonFileAddEnvironmentVariables ASP.NET Core 1.x 응용 프로그램에서 직접) JSON 파일 및 시스템 구성 소스 읽기에 대 한 구성 공급자를 추가 합니다.The CreateDefaultBuilder extension method in an ASP.NET Core 2.x app (or using AddJsonFile and AddEnvironmentVariables directly in an ASP.NET Core 1.x app) adds configuration providers for reading JSON files and system configuration sources:

  • appsettings.jsonappsettings.json
  • appsettings 합니다. <EnvironmentName >.jsonappsettings.<EnvironmentName>.json
  • 환경 변수environment variables

참조 AddJsonFile 에 대 한 설명은 매개 변수입니다.See AddJsonFile for an explanation of the parameters. reloadOnChangeASP.NET Core 1.1에서 이상 에서만 지원 됩니다.reloadOnChange is only supported in ASP.NET Core 1.1 and higher.

지정 된 순서 구성 소스를 읽습니다.Configuration sources are read in the order they are specified. 위의 코드에서 환경 변수 마지막 읽혀집니다.In the code above, the environment variables are read last. 두 이전 공급자에 설정 된 환경을 통해 설정 된 구성 값 바꾸어야 합니다.Any configuration values set through the environment would replace those set in the two previous providers.

환경 중 하나에 일반적으로 설정 되어 Development, Staging, 또는 Production합니다.The environment is typically set to one of Development, Staging, or Production. 참조 여러 환경 작업 자세한 정보에 대 한 합니다.See Working with Multiple Environments for more information.

구성 고려 사항:Configuration considerations:

  • IOptionsSnapshot변경 시 구성 데이터를 다시 로드할 수 있습니다.IOptionsSnapshot can reload configuration data when it changes. 사용 하 여 IOptionsSnapshot 구성 데이터를 다시 로드 하는 경우.Use IOptionsSnapshot if you need to reload configuration data. 참조 IOptionsSnapshot 자세한 정보에 대 한 합니다.See IOptionsSnapshot for more information.
  • 구성 키 대/소문자를 구분 합니다.Configuration keys are case insensitive.
  • 가장 좋은 방법은 로컬 환경에서 배포 된 구성 파일을 설정 하는 아무 것도 재정의할 수 있도록 마지막으로, 환경 변수를 지정 하는 것입니다.A best practice is to specify environment variables last, so that the local environment can override anything set in deployed configuration files.
  • 하지 구성 공급자 코드에 또는 일반 텍스트로 구성 파일에 암호 또는 기타 중요 한 데이터를 저장 합니다.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files. 테스트 환경 하거나 사용자가 개발에서 생산 암호를 사용 하지 마십시오.Don't use production secrets in your development or test environments. 대신 저장소로 실수로 커밋된 없습니다 하므로 프로젝트 트리 외부 암호를 지정 합니다.Instead, specify secrets outside the project tree, so they cannot be accidentally committed into your repository. 에 대 한 자세한 내용은 여러 환경 작업 및 관리 개발 하는 동안 앱 암호의 안전한 저장소합니다.Learn more about Working with Multiple Environments and managing safe storage of app secrets during development.
  • 경우 : 수 없습니다 시스템에서 환경 변수에서 사용 되는 대체 :__ (이중 밑줄).If : cannot be used in environment variables in your system, replace : with __ (double underscore).

<a name=options-config-objects>

옵션 및 구성 개체를 사용 하 여Using Options and configuration objects

옵션 패턴을 관련된 설정 그룹을 나타내는 사용자 지정 옵션 클래스를 사용 합니다.The options pattern uses custom options classes to represent a group of related settings. 앱 내에서 각 기능에 대해 분리 된 클래스를 만드는 것이 좋습니다.We recommended that you create decoupled classes for each feature within your app. 분리 된 클래스를 수행합니다.Decoupled classes follow:

옵션 클래스는 추상 이어야 합니다. 매개 변수가 없는 public 생성자를 사용 합니다.The options class must be non-abstract with a public parameterless constructor. 예:For example:

namespace UsingOptions.Models
{
    public class MyOptions
    {
        public MyOptions()
        {
            // Set default value.
            Option1 = "value1_from_ctor";
        }
        public string Option1 { get; set; }
        public int Option2 { get; set; } = 5;
    }
}

<a name=options-example>

다음 코드에서 JSON 구성 공급자가 사용 됩니다.In the following code, the JSON configuration provider is enabled. MyOptions 클래스는 서비스 컨테이너에 추가 되 고 구성에 연결 합니다.The MyOptions class is added to the service container and bound to configuration.

public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        // Set up configuration sources.
        var builder = new ConfigurationBuilder()
            .SetBasePath(env.ContentRootPath)
            .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true);

        Configuration = builder.Build();
    }

    public IConfigurationRoot Configuration { get; set; }

    public void ConfigureServices(IServiceCollection services)
    {
        // Adds services required for using options.
        services.AddOptions();

        // Register the IConfiguration instance which MyOptions binds against.
        services.Configure<MyOptions>(Configuration);

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

다음 컨트롤러 사용 하 여 생성자 종속성 주입 IOptions<TOptions> 설정에 액세스 하려면:The following controller uses constructor Dependency Injection on IOptions<TOptions> to access settings:

public class HomeController : Controller
{
    private readonly MyOptions _options;

    public HomeController(IOptions<MyOptions> optionsAccessor)
    {
        _options = optionsAccessor.Value;
    }

    public IActionResult Index()
    {
        var option1 = _options.Option1;
        var option2 = _options.Option2;
        return Content($"option1 = {option1}, option2 = {option2}");
    }
}

다음으로 appsettings.json 파일:With the following appsettings.json file:

{
  "option1": "value1_from_json",
  "option2": 2
}

HomeController.Index 메서드 반환 option1 = value1_from_json, option2 = 2합니다.The HomeController.Index method returns option1 = value1_from_json, option2 = 2.

일반적인 앱 단일 옵션 파일에 전체 구성을 바인딩 되지 않습니다.Typical apps won't bind the entire configuration to a single options file. 나중에 사용 하는 방법을 보여 드리 려 GetSection 섹션에 바인딩할 합니다.Later on I'll show how to use GetSection to bind to a section.

다음 코드에서 두 번째 IConfigureOptions<TOptions> 서비스를 서비스 컨테이너에 추가 합니다.In the following code, a second IConfigureOptions<TOptions> service is added to the service container. 대리자를 사용 하 여 바인딩을 구성 MyOptions합니다.It uses a delegate to configure the binding with MyOptions.

public void ConfigureServices(IServiceCollection services)
{
    // Adds services required for using options.
    services.AddOptions();

    // Register the ConfigurationBuilder instance which MyOptions binds against.
    services.Configure<MyOptions>(Configuration);

    // Registers the following lambda used to configure options.
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "value1_from_action";
    });

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

여러 구성 공급자를 추가할 수 있습니다.You can add multiple configuration providers. 구성 공급자는 NuGet 패키지에서 사용할 수 있습니다.Configuration providers are available in NuGet packages. 등록 된 순서에 적용 됩니다.They are applied in order they are registered.

호출할 때마다 Configure<TOptions> 추가 IConfigureOptions<TOptions> 서비스를 서비스 컨테이너입니다.Each call to Configure<TOptions> adds an IConfigureOptions<TOptions> service to the service container. 위의 예제에서는 값 Option1Option2 에 지정 된 appsettings.json -하지만의 값 Option1 구성 된 대리자가 재정의 됩니다.In the preceding example, the values of Option1 and Option2 are both specified in appsettings.json -- but the value of Option1 is overridden by the configured delegate.

둘 이상의 구성 서비스를 사용 하는 경우 마지막 구성 소스 지정 "wins" (구성 값을 설정).When more than one configuration service is enabled, the last configuration source specified "wins" (sets the configuration value). 위의 코드는 HomeController.Index 메서드 반환 option1 = value1_from_action, option2 = 2합니다.In the preceding code, the HomeController.Index method returns option1 = value1_from_action, option2 = 2.

각 속성에 옵션 유형 폼의 구성 키에 바인딩된 구성 옵션을 바인딩할 때 property[:sub-property:]합니다.When you bind options to configuration, each property in your options type is bound to a configuration key of the form property[:sub-property:]. 예를 들어는 MyOptions.Option1 속성의 키에 바인딩된 Option1에서 읽음는 option1 속성 appsettings.json합니다.For example, the MyOptions.Option1 property is bound to the key Option1, which is read from the option1 property in appsettings.json. 하위 속성 샘플은이 문서의 뒷부분에 표시 됩니다.A sub-property sample is shown later in this article.

다음 코드에서는 세 번째 IConfigureOptions<TOptions> 서비스를 서비스 컨테이너에 추가 합니다.In the following code, a third IConfigureOptions<TOptions> service is added to the service container. 바인딩할 MySubOptions 섹션 subsectionappsettings.json 파일:It binds MySubOptions to the section subsection of the appsettings.json file:

public void ConfigureServices(IServiceCollection services)
{
    // Adds services required for using options.
    services.AddOptions();

    // Configure with Microsoft.Extensions.Options.ConfigurationExtensions
    // Binding the whole configuration should be rare, subsections are more typical.
    services.Configure<MyOptions>(Configuration);

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

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

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

참고:이 확장 방법을 사용 하려면는 Microsoft.Extensions.Options.ConfigurationExtensions NuGet 패키지 합니다.Note: This extension method requires the Microsoft.Extensions.Options.ConfigurationExtensions NuGet package.

다음을 사용 하 여 appsettings.json 파일:Using the following appsettings.json file:

{
  "option1": "value1_from_json",
  "option2": -1,
  "subsection": {
    "suboption1": "subvalue1_from_json",
    "suboption2": 200
  }
}

MySubOptions 클래스:The MySubOptions class:

public class MySubOptions
{
    public MySubOptions()
    {
        // Set default values.
        SubOption1 = "value1_from_ctor";
        SubOption2 = 5;
    }
    public string SubOption1 { get; set; }
    public int SubOption2 { get; set; }
}

다음으로 Controller:With the following Controller:

public class HomeController : Controller
{
    private readonly MySubOptions _subOptions;

    public HomeController(IOptions<MySubOptions> subOptionsAccessor)
    {
        _subOptions = subOptionsAccessor.Value;
    }

    public IActionResult Index()
    {
        var subOption1 = _subOptions.SubOption1;
        var subOption2 = _subOptions.SubOption2;
        return Content($"subOption1 = {subOption1}, subOption2 = {subOption2}");
    }
}

subOption1 = subvalue1_from_json, subOption2 = 200이 반환 됩니다.subOption1 = subvalue1_from_json, subOption2 = 200 is returned.

옵션을 보기 모델에 제공 하거나 삽입할 수도 IOptions<TOptions> 보기에 직접:You can also supply options in a view model or inject IOptions<TOptions> directly into a view:

@using Microsoft.Extensions.Options
@using UsingOptions.Models
@model MyOptions
@inject IOptions<MyOptions> OptionsAccessor

<!DOCTYPE html>
<!-- This view works with HomeController3.cs -->
<html lang="en">
<head>
    <title>Using Options sample app</title>
</head>
<body>
    <h1>Options</h1>

    <h2>Options provided by the model</h2>
    <p><b>Option1:</b> @Model.Option1</p>
    <p><b>Option2:</b> @Model.Option2</p>

    <h2>Options injected into the view</h2>
    <p><b>Option1:</b> @OptionsAccessor.Value.Option1</p>
    <p><b>Option2:</b> @OptionsAccessor.Value.Option2</p>
</body>
</html>

<a name=in-memory-provider>

IOptionsSnapshotIOptionsSnapshot

ASP.NET Core 1.1 이상이 필요합니다.Requires ASP.NET Core 1.1 or higher.

IOptionsSnapshot구성 파일 변경 될 때 구성 데이터를 다시 로드를 지원 합니다.IOptionsSnapshot supports reloading configuration data when the configuration file has changed. 오버 헤드가 최소로 유지가 된 있습니다.It has minimal overhead. 사용 하 여 IOptionsSnapshotreloadOnChange: true, 옵션에 바인딩된 IConfiguration 변경 될 때 다시 로드 합니다.Using IOptionsSnapshot with reloadOnChange: true, the options are bound to IConfiguration and reloaded when changed.

다음 샘플에는 새로운 방법을 보여 줍니다 IOptionsSnapshot 후에 만들어진 config.json 변경 합니다.The following sample demonstrates how a new IOptionsSnapshot is created after config.json changes. 동일한 서버에 요청을 반환 합니다 시간 config.json하지 변경 합니다.Requests to the server will return the same time when config.json has not changed. 첫 번째 요청 이후 config.json 변경 시간을 표시 합니다.The first request after config.json changes will show a new time.

public class TimeOptions
{
    // Records the time when the options are created.
    public DateTime CreationTime { get; set; } = DateTime.Now;

    // Bound to config. Changes to the value of "Message"
    // in config.json will be reflected in this property.
    public string Message { get; set; }
}

public class Controller
{
    public readonly TimeOptions _options;

    public Controller(IOptionsSnapshot<TimeOptions> options)
    {
        _options = options.Value;
    }

    public Task DisplayTimeAsync(HttpContext context)
    {
        return context.Response.WriteAsync(_options.Message + _options.CreationTime);
    }
}

public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            // reloadOnChange: true is required for config changes to be detected.
            .AddJsonFile("config.json", optional: false, reloadOnChange: true)
            .AddEnvironmentVariables();
        Configuration = builder.Build();
    }

    public IConfigurationRoot Configuration { get; set; }

    public void Configure(IApplicationBuilder app)
    {
        // Simple mockup of a simple per request controller that writes
        // the creation time and message of TimeOptions.
        app.Run(DisplayTimeAsync);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        // Simple mockup of a simple per request controller.
        services.AddScoped<Controller>();

        // Binds config.json to the options and setups the change tracking.
        services.Configure<TimeOptions>(Configuration.GetSection("Time"));
    }

    public Task DisplayTimeAsync(HttpContext context)
    {
        context.Response.ContentType = "text/plain";
        return context.RequestServices.GetRequiredService<Controller>().DisplayTimeAsync(context);
    }

    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseIISIntegration()
            .UseStartup<Startup>()
            .Build();
        host.Run();
    }
}

다음 그림에서는 서버 출력을 보여 줍니다.The following image shows the server output:

이미지 표시 된 브라우저 "마지막 업데이트: 2016 년 11 월 22 일 오후 4시 43분"

메시지 값 또는 표시 된 시간이 변경 되지 않습니다 브라우저 새로 고침 (때 config.json 변경 되지 않은).Refreshing the browser doesn't change the message value or time displayed (when config.json has not changed).

변경 하 고 저장 된 config.json 후 브라우저를 새로 고칩니다.Change and save the config.json and then refresh the browser:

이미지 표시 된 브라우저 "마지막으로 업데이트를 e: 2016 년 11 월 22 일 오후 4시 53분"

메모리 내 공급자 및 POCO 클래스에 바인딩In-memory provider and binding to a POCO class

다음 샘플에는 클래스에 바인딩하고 메모리 내 공급자를 사용 하는 방법을 보여 줍니다.The following sample shows how to use the in-memory provider and bind to a class:

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

public class Program
{   
    public static IConfigurationRoot Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "Rick"},
                {"App:MainWindow:Height", "11"},
                {"App:MainWindow:Width", "11"},
                {"App:MainWindow:Top", "11"},
                {"App:MainWindow:Left", "11"}
            };

        var builder = new ConfigurationBuilder();
        builder.AddInMemoryCollection(dict);

        Configuration = builder.Build();

        Console.WriteLine($"Hello {Configuration["Profile:MachineName"]}");

        var window = new MyWindow();
        Configuration.GetSection("App:MainWindow").Bind(window);
        Console.WriteLine($"Left {window.Left}");
        Console.WriteLine();

        Console.WriteLine("Press any key...");
        Console.ReadKey();
    }
}

구성 값을 문자열로 반환 됩니다 있지만 바인딩 개체의 생성을 사용 합니다.Configuration values are returned as strings, but binding enables the construction of objects. 바인딩은 POCO 개체 또는 전체 개체 그래프를 검색할 수 있습니다.Binding allows you to retrieve POCO objects or even entire object graphs. 다음 샘플에서는에 바인딩하는 방법을 보여 줍니다. MyWindow ASP.NET Core MVC 응용 프로그램으로 옵션 패턴을 사용 하 고 있습니다.The following sample shows how to bind to MyWindow and use the options pattern with a ASP.NET Core MVC app:

namespace WebConfigBind
{
    public class MyWindow
    {
        public int Height { get; set; }
        public int Width { get; set; }
        public int Top { get; set; }
        public int Left { get; set; }
    }
}
{
  "AppConfiguration": {
    "MainWindow": {
      "Height": "400",
      "Width": "600",
      "Top": "5",
      "Left": "11"
    }
  }
}

사용자 지정 클래스 바인딩 ConfigureServices 호스트를 작성할 때:Bind the custom class in ConfigureServices when building the host:

.ConfigureServices(services =>
{
    services.Configure<MyWindow>(
        Configuration.GetSection("AppConfiguration:MainWindow"));
    services.AddMvc();
})

설정을 표시는 HomeController:Display the settings from the HomeController:

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

namespace WebConfigBind
{
    public class HomeController : Controller
    {
        private readonly IOptions<MyWindow> _optionsAccessor;

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

        public IActionResult Index()
        {
            var height = _optionsAccessor.Value.Height;
            var width = _optionsAccessor.Value.Width;
            var left = _optionsAccessor.Value.Left;
            var top = _optionsAccessor.Value.Top;

            return Content($"height = {height}, width = {width}, " + 
                $"left = {left}, top = {top}");
        }
    }
}

GetValueGetValue

다음 샘플을 참조 하십시오.는 GetValue 확장 메서드:The following sample demonstrates the GetValue extension method:

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

public class Program
{   
    public static IConfigurationRoot Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "Rick"},
                {"App:MainWindow:Height", "11"},
                {"App:MainWindow:Width", "11"},
                {"App:MainWindow:Top", "11"},
                {"App:MainWindow:Left", "11"}
            };

        var builder = new ConfigurationBuilder();
        builder.AddInMemoryCollection(dict);

        Configuration = builder.Build();

        Console.WriteLine($"Hello {Configuration["Profile:MachineName"]}");

        // Show GetValue overload and set the default value to 80
        // Requires NuGet package "Microsoft.Extensions.Configuration.Binder"
        var left = Configuration.GetValue<int>("App:MainWindow:Left", 80);
        Console.WriteLine($"Left {left}");

        var window = new MyWindow();
        Configuration.GetSection("App:MainWindow").Bind(window);
        Console.WriteLine($"Left {window.Left}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

ConfigurationBinder GetValue<T> 메서드 기본값 (이 샘플에는 80)을 지정할 수 있습니다.The ConfigurationBinder's GetValue<T> method allows you to specify a default value (80 in the sample). GetValue<T>간단한 시나리오 되며 전체 섹션에 바인딩되지 않습니다.GetValue<T> is for simple scenarios and does not bind to entire sections. GetValue<T>스칼라 값을 가져옵니다 GetSection(key).Value 특정 형식으로 변환 합니다.GetValue<T> gets scalar values from GetSection(key).Value converted to a specific type.

개체 그래프에 바인딩Binding to an object graph

클래스의 각 개체를 재귀적으로 바인딩할을 수 있습니다.You can recursively bind to each object in a class. 다음 사항을 고려 AppOptions 클래스:Consider the following AppOptions class:

public class AppOptions
{
    public Window Window { get; set; }
    public Connection Connection { get; set; }
    public Profile Profile { get; set; }
}

public class Window
{
    public int Height { get; set; }
    public int Width { get; set; }
}

public class Connection
{
    public string Value { get; set; }
}

public class Profile
{
    public string Machine { get; set; }
}

다음 샘플에 바인딩하는 AppOptions 클래스:The following sample binds to the AppOptions class:

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

public class Program
{
    public static void Main(string[] args = null)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        var config = builder.Build();

        var appConfig = new AppOptions();
        config.GetSection("App").Bind(appConfig);

        Console.WriteLine($"Height {appConfig.Window.Height}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

ASP.NET Core 1.1 및 이상을 사용 하 여 Get<T>, 전체 섹션와 함께 작업 하 합니다.ASP.NET Core 1.1 and higher can use Get<T>, which works with entire sections. Get<T>사용 하 여 보다 자세한 convienent 수 Bind합니다.Get<T> can be more convienent than using Bind. 다음 코드를 사용 하는 방법을 보여 줍니다 Get<T> 위의 샘플:The following code shows how to use Get<T> with the sample above:

var appConfig = config.GetSection("App").Get<AppOptions>();

다음을 사용 하 여 appsettings.json 파일:Using the following appsettings.json file:

{
  "App": {
    "Profile": {
      "Machine": "Rick"
    },
    "Connection": {
      "Value": "connectionstring"
    },
    "Window": {
      "Height": "11",
      "Width": "11"
    }
  }
}

프로그램은 표시 Height 11합니다.The program displays Height 11.

다음 코드를 장치에 사용할 수 구성을 테스트 합니다.The following code can be used to unit test the configuration:

[Fact]
public void CanBindObjectTree()
{
    var dict = new Dictionary<string, string>
        {
            {"App:Profile:Machine", "Rick"},
            {"App:Connection:Value", "connectionstring"},
            {"App:Window:Height", "11"},
            {"App:Window:Width", "11"}
        };
    var builder = new ConfigurationBuilder();
    builder.AddInMemoryCollection(dict);
    var config = builder.Build();

    var options = new AppOptions();
    config.GetSection("App").Bind(options);

    Assert.Equal("Rick", options.Profile.Machine);
    Assert.Equal(11, options.Window.Height);
    Assert.Equal(11, options.Window.Width);
    Assert.Equal("connectionstring", options.Connection.Value);
}

<a name=custom-config-providers>

Entity Framework 사용자 지정 공급자의 기본 샘플Basic sample of Entity Framework custom provider

이 섹션에서는 EF를 사용 하 여 데이터베이스에서 이름-값 쌍을 읽을 수 있는 기본 구성 공급자가 만들어집니다.In this section, a basic configuration provider that reads name-value pairs from a database using EF is created.

정의 ConfigurationValue 데이터베이스의 구성 값을 저장 하기 위한 엔터티:Define a ConfigurationValue entity for storing configuration values in the database:

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

추가 ConfigurationContext 저장 하 고 구성된 된 값에 액세스 합니다.Add a ConfigurationContext to store and access the configured values:

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

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

구현 하는 클래스를 만드는 IConfigurationSource:Create an class that implements IConfigurationSource:

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

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

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

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

상속 하 여 사용자 지정 구성 공급자를 만들기 ConfigurationProvider합니다.Create the custom configuration provider by inheriting from ConfigurationProvider. 구성 공급자는 비어 있는 경우 데이터베이스를 초기화 합니다.The configuration provider initializes the database when it's empty:

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

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

        Action<DbContextOptionsBuilder> OptionsAction { get; }

        // Load config data from EF DB.
        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;
        }
    }
}

("Value_from_ef_1" 및 "value_from_ef_2")은 데이터베이스의 강조 표시 된 값은 샘플 실행 될 때 표시 됩니다.The highlighted values from the database ("value_from_ef_1" and "value_from_ef_2") are displayed when the sample is run.

추가할 수는 EFConfigSource 구성 소스를 추가 하기 위한 확장 메서드:You can add an EFConfigSource 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 EFConfigSource(setup));
        }
    }
}

다음 코드에서는 사용자 지정을 사용 하는 방법을 보여 줍니다. EFConfigProvider:The following code shows how to use the custom EFConfigProvider:

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

public static class Program
{
    public static void Main()
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        var connectionStringConfig = builder.Build();

        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            // Add "appsettings.json" to bootstrap EF config.
            .AddJsonFile("appsettings.json")
            // Add the EF configuration provider, which will override any
            // config made with the JSON provider.
            .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"]);
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

사용자 지정을 추가 하는 샘플 참고 EFConfigProvider JSON 공급자 이므로 데이터베이스의 모든 설정의 설정을 재정의 합니다에서 appsettings.json 파일입니다.Note the sample adds the custom EFConfigProvider after the JSON provider, so any settings from the database will override settings from the appsettings.json file.

다음을 사용 하 여 appsettings.json 파일:Using the following appsettings.json file:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=CustomConfigurationProvider;Trusted_Connection=True;MultipleActiveResultSets=true"
  },
  "key1": "value_from_json_1",
  "key2": "value_from_json_2",
  "key3": "value_from_json_3"
}

다음이 표시됩니다.The following is displayed:

key1=value_from_ef_1
key2=value_from_ef_2
key3=value_from_json_3

명령줄 구성 공급자CommandLine configuration provider

CommandLine 구성 공급자 런타임에 구성에 대 한 키-값 쌍 명령줄 인수를 받습니다.The CommandLine configuration provider receives command-line argument key-value pairs for configuration at runtime.

보기 또는 CommandLine 구성 샘플 다운로드View or download the CommandLine configuration sample

공급자를 설정합니다.Setting up the provider

명령줄 구성을 활성화 하려면 호출는 AddCommandLine 인스턴스의 확장 메서드 ConfigurationBuilder:To activate command-line configuration, call the AddCommandLine extension method on an instance of ConfigurationBuilder:

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

public class Program
{
    public static IConfigurationRoot Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "MairaPC"},
                {"App:MainWindow:Left", "1980"}
            };

        var builder = new ConfigurationBuilder();

        builder.AddInMemoryCollection(dict)
            .AddCommandLine(args);

        Configuration = builder.Build();

        Console.WriteLine($"MachineName: {Configuration["Profile:MachineName"]}");
        Console.WriteLine($"Left: {Configuration["App:MainWindow:Left"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

코드를 실행 다음과 같은 출력이 표시 됩니다.Running the code, the following output is displayed:

MachineName: MairaPC
Left: 1980

값을 변경 하는 명령줄에 키-값 쌍 인수를 전달 Profile:MachineNameApp:MainWindow:Left:Passing argument key-value pairs on the command line changes the values of Profile:MachineName and App:MainWindow:Left:

dotnet run Profile:MachineName=BartPC App:MainWindow:Left=1979

콘솔 창에 표시 됩니다.The console window displays:

MachineName: BartPC
Left: 1979

명령줄 구성의 다른 구성 공급자가 제공 되는 구성을 재정의 하려면 AddCommandLine 마지막에 ConfigurationBuilder:To override configuration provided by other configuration providers with command-line configuration, call AddCommandLine last on ConfigurationBuilder:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
    .AddEnvironmentVariables()
    .AddCommandLine(args)
    .Build();

인수Arguments

명령줄에 전달 된 인수는 다음 표에 표시 된 두 형식 중 하나를 따라야 합니다.Arguments passed on the command line must conform to one of two formats shown in the following table.

인수 형식Argument format 예제Example
단일 인수: 등호로 구분 된 키-값 쌍 (=)Single argument: a key-value pair separated by an equals sign (=) key1=value
두 개의 인수 순서: 공백으로 구분 되는 키-값 쌍Sequence of two arguments: a key-value pair separated by a space /key1 value1

단일 인수Single argument

값은 등호 따라야 합니다. (=).The value must follow an equals sign (=). 값은 null 일 수 있습니다 (예를 들어 mykey=).The value can be null (for example, mykey=).

키 접두사가 있을 수 있습니다.The key may have a prefix.

키 접두사Key prefix 예제Example
접두사 없음No prefix key1=value1
단일 대시 (-) †Single dash (-)† -key2=value2
대시 두 개 (--)Two dashes (--) --key3=value3
슬래시 (/)Forward slash (/) /key4=value4

† 단일 대시 접두사를 사용 하 여 키 (-) 제공 되어야 매핑 전환, 아래에서 설명 합니다.†A key with a single dash prefix (-) must be provided in switch mappings, described below.

예제 명령입니다.Example command:

dotnet run key1=value1 -key2=value2 --key3=value3 /key4=value4

참고: 경우 -key1 에 존재 하지는 매핑 전환 구성 공급자에 게 제공는 FormatException throw 됩니다.Note: If -key1 isn't present in the switch mappings given to the configuration provider, a FormatException is thrown.

두 인수 중 시퀀스Sequence of two arguments

값은 null 일 수 없으며 공백으로 구분 하 여 키를 수행 해야 합니다.The value can't be null and must follow the key separated by a space.

키에 접두사가 있어야 합니다.The key must have a prefix.

키 접두사Key prefix 예제Example
단일 대시 (-) †Single dash (-)† -key1 value1
대시 두 개 (--)Two dashes (--) --key2 value2
슬래시 (/)Forward slash (/) /key3 value3

† 단일 대시 접두사를 사용 하 여 키 (-) 제공 되어야 매핑 전환, 아래에서 설명 합니다.†A key with a single dash prefix (-) must be provided in switch mappings, described below.

예제 명령입니다.Example command:

dotnet run -key1 value1 --key2 value2 /key3 value3

참고: 경우 -key1 에 존재 하지는 매핑 전환 구성 공급자에 게 제공는 FormatException throw 됩니다.Note: If -key1 isn't present in the switch mappings given to the configuration provider, a FormatException is thrown.

중복 키Duplicate keys

중복 키가 제공 하는 경우 마지막 키-값 쌍이 사용 됩니다.If duplicate keys are provided, the last key-value pair is used.

스위치 매핑Switch mappings

사용 하 여 구성을 수동으로 작성할 때 ConfigurationBuilder, 스위치 매핑 사전에 선택적으로 제공할 수는 AddCommandLine 메서드.When manually building configuration with ConfigurationBuilder, you can optionally provide a switch mappings dictionary to the AddCommandLine method. 스위치 매핑을 통해 키 이름을 교체 논리를 제공할 수 있습니다.Switch mappings allow you to provide key name replacement logic.

스위치 매핑 사전을 사용 되는 경우 명령줄 인수에 의해 제공 된 키와 일치 하는 키에 대 한 사전을 확인 됩니다.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 (the key replacement) is passed back to set the configuration. 스위치 매핑이 단일에 대시가 접두사로 명령줄 키 필요 (-).A switch mapping is required for any command-line key prefixed with a single dash (-).

매핑 사전 키 규칙을 전환 합니다.Switch mappings dictionary key rules:

  • 스위치 대시로 시작 해야 합니다 (-) 나 더블 대시 (--).Switches must start with a dash (-) or double-dash (--).
  • 스위치 매핑 사전에 중복 키를 사용할 수 없습니다.The switch mappings dictionary must not contain duplicate keys.

다음 예제에서는 GetSwitchMappings 메서드를 사용 하면 단일 대시를 사용 하 여 명령줄 인수 (-) 접두사를 입력 하 고 선행 하위 키 접두사를 방지 합니다.In the following example, the GetSwitchMappings method allows your command-line arguments to use a single dash (-) key prefix and avoid leading subkey prefixes.

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

public class Program
{
    public static IConfigurationRoot Configuration { get; set; }

    public static Dictionary<string, string> GetSwitchMappings(
        IReadOnlyDictionary<string, string> configurationStrings)
    {
        return configurationStrings.Select(item =>
            new KeyValuePair<string, string>(
                "-" + item.Key.Substring(item.Key.LastIndexOf(':') + 1),
                item.Key))
                .ToDictionary(
                    item => item.Key, item => item.Value);
    }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "RickPC"},
                {"App:MainWindow:Left", "1980"}
            };

        var builder = new ConfigurationBuilder();

        builder.AddInMemoryCollection(dict)
            .AddCommandLine(args, GetSwitchMappings(dict));

        Configuration = builder.Build();

        Console.WriteLine($"MachineName: {Configuration["Profile:MachineName"]}");
        Console.WriteLine($"Left: {Configuration["App:MainWindow:Left"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

사전 제공 된 명령줄 인수를 제공 하지 않고 AddInMemoryCollection 구성 값을 설정 합니다.Without providing command-line arguments, the dictionary provided to AddInMemoryCollection sets the configuration values. 다음 명령을 사용 하 여 응용 프로그램을 실행 합니다.Run the app with the following command:

dotnet run

콘솔 창에 표시 됩니다.The console window displays:

MachineName: RickPC
Left: 1980

구성 설정에 전달 하려면 다음을 사용 합니다.Use the following to pass in configuration settings:

dotnet run /Profile:MachineName=DahliaPC /App:MainWindow:Left=1984

콘솔 창에 표시 됩니다.The console window displays:

MachineName: DahliaPC
Left: 1984

스위치 매핑 사전을 만든 후 다음 표에 표시 되는 데이터를 포함 합니다.After the switch mappings dictionary is created, it contains the data shown in the following table.

KeyKey Value
-MachineName Profile:MachineName
-Left App:MainWindow:Left

키 전환 사전을 사용을 보여 주기 위해 다음 명령을 실행 합니다.To demonstrate key switching using the dictionary, run the following command:

dotnet run -MachineName=ChadPC -Left=1988

명령줄 키 바뀝니다.The command-line keys are swapped. 콘솔 창에 대 한 구성 값을 표시 Profile:MachineNameApp:MainWindow:Left:The console window displays the configuration values for Profile:MachineName and App:MainWindow:Left:

MachineName: ChadPC
Left: 1988

Web.config 파일The web.config file

A web.config 파일은 IIS 또는 IIS Express에서 응용 프로그램을 호스팅하는 경우에 필요 합니다.A web.config file is required when you host the app in IIS or IIS-Express. web.config AspNetCoreModule IIS에서 앱을 시작 하도록 설정 합니다.web.config turns on the AspNetCoreModule in IIS to launch your app. 설정 web.config AspNetCoreModule iis 응용 프로그램을 시작 하 고 다른 IIS 설정 및 모듈 구성에 사용 하도록 설정 합니다.Settings in web.config enable the AspNetCoreModule in IIS to launch your app and configure other IIS settings and modules. Visual Studio를 사용 하는 경우 삭제 web.config, Visual Studio는 새 이름을 만듭니다.If you are using Visual Studio and delete web.config, Visual Studio will create a new one.

추가 참고 사항Additional notes

  • DI (dependency Injection) 후 까지의 설정 되지 않은 ConfigureServices 가 호출 됩니다.Dependency Injection (DI) is not set up until after ConfigureServices is invoked.
  • 구성 시스템이 DI 인식 되지 않습니다.The configuration system is not DI aware.
  • IConfiguration두 가지 특수화에 있습니다.IConfiguration has two specializations:
    • IConfigurationRoot루트 노드에 대해 사용 합니다.IConfigurationRoot Used for the root node. 다시 로드를 트리거할 수 있습니다.Can trigger a reload.
    • IConfigurationSection구성 값의 섹션을 나타냅니다.IConfigurationSection Represents a section of configuration values. GetSectionGetChildren 메서드는 반환 된 IConfigurationSection합니다.The GetSection and GetChildren methods return an IConfigurationSection.

추가 리소스Additional resources