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

작성자: Rick AndersonKirk LarkinBy Rick Anderson and Kirk Larkin

ASP.NET Core에서 구성은 하나 이상의 구성 공급자를 사용하여 수행합니다.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 )Settings files, such as appsettings.json
  • 환경 변수Environment variables
  • Azure Key VaultAzure Key Vault
  • Azure App ConfigurationAzure App Configuration
  • 명령줄 인수Command-line arguments
  • 설치되거나 만들어진 사용자 지정 공급자Custom providers, installed or created
  • 디렉터리 파일Directory files
  • 메모리 내 .NET 개체In-memory .NET objects

이 항목에서는 ASP.NET Core의 구성에 대한 정보를 제공합니다.This topic provides information on configuration in ASP.NET Core. 콘솔 앱에서 구성을 사용하는 방법에 대한 자세한 내용은 .NET 구성을 참조하세요.For information on using configuration in console apps, see .NET Configuration.

예제 코드 살펴보기 및 다운로드 (다운로드 방법)View or download sample code (how to download)

기본 구성Default configuration

dotnet new 또는 Visual Studio를 사용하여 만든 ASP.NET Core 웹앱은 다음 코드를 생성합니다.ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder는 다음 순서로 앱에 대한 기본 구성을 제공합니다.CreateDefaultBuilder provides default configuration for the app in the following order:

  1. ChainedConfigurationProvider: 기존 IConfiguration을 소스로 추가합니다.ChainedConfigurationProvider : Adds an existing IConfiguration as a source. 기본 구성 사례에서는 호스트 구성을 추가하고 앱 구성의 첫 번째 소스로 설정합니다.In the default configuration case, adds the host configuration and setting it as the first source for the app configuration.
  2. JSON 구성 공급자를 사용하는 appsettings.json.appsettings.json using the JSON configuration provider.
  3. JSON 구성 공급자를 사용하는 appsettings. Environment .json.appsettings.Environment.json using the JSON configuration provider. 예: appsettings.Production**_._jsonappsettings.***Development _.json*.For example, appsettings.***Production**._json* and appsettings.***Development** _._json*.
  4. 앱이 Development 환경에서 실행되는 경우 앱 비밀App secrets when the app runs in the Development environment.
  5. 환경 변수 구성 공급자를 사용하는 환경 변수Environment variables using the Environment Variables configuration provider.
  6. 명령줄 구성 공급자를 사용하는 명령줄 인수Command-line arguments using the Command-line configuration provider.

나중에 추가된 구성 공급자는 이전 키 설정을 재정의합니다.Configuration providers that are added later override previous key settings. 예를 들어 MyKeyappsettings.json 과 환경 모두에서 설정된 경우 환경 값이 사용됩니다.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.

CreateDefaultBuilder에 대한 자세한 내용은 기본 작성기 설정을 참조하세요.For more information on CreateDefaultBuilder, see Default builder settings.

다음 코드는 추가된 순서대로 사용하도록 설정된 구성 공급자를 표시합니다.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);
    }
}

appsettings.json

다음 appsettings.json 파일을 살펴보세요.Consider the following appsettings.json file:

{
    "Position": {
        "Title": "편집기",
        "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}");
    }
}

기본 JsonConfigurationProvider는 다음과 같은 순서로 구성을 로드합니다.The default JsonConfigurationProvider loads configuration in the following order:

  1. appsettings.json
  2. appsettings. Environment .json: 예: appsettings.Production**_._jsonappsettings.***Development _.json* 파일.appsettings.Environment.json : For example, the appsettings.***Production**._json* and appsettings.***Development** _._json* files. 파일의 환경 버전은 IHostingEnvironment.EnvironmentName을 기반으로 합니다.The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. 자세한 내용은 ASP.NET Core에서 여러 환경 사용를 참조하세요.For more information, see ASP.NET Core에서 여러 환경 사용.

appsettings.Environment.json 값은 appsettings.json 의 키를 재정의합니다.appsettings.Environment.json values override keys in appsettings.json. 예를 들어 기본적으로 다음과 같습니다.For example, by default:

  • 개발 환경에서는 appsettings.Development _._json 구성이 appsettings.json 에서 찾은 값을 덮어씁니다.In development, appsettings.Development _._json configuration overwrites values found in appsettings.json.
  • 프로덕션 환경에서는 appsettings.Production _._json 구성이 appsettings.json 에서 찾은 값을 덮어씁니다.In production, appsettings.Production _._json configuration overwrites values found in appsettings.json. Azure에 앱을 배포하는 경우를 예로 들 수 있습니다.For example, when deploying the app to Azure.

구성 값을 보장해야 하는 경우 GetValue를 참조 하십시오.If a configuration value must be guaranteed, see GetValue. 위의 예제에서는 문자열만 읽고 기본값을 지원하지 않습니다.The preceding example only reads strings and doesn’t support a default value

옵션 패턴을 사용하여 계층적 구성 데이터 바인딩Bind hierarchical configuration data using the options pattern

관련 구성 값을 읽는 기본 방법은 옵션 패턴를 사용하는 것입니다.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"
  }

다음 PositionOptions 클래스를 만듭니다.Create the following PositionOptions class:

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; }
    public string Name { get; set; }
}

옵션 클래스:An options class:

  • 매개 변수가 없는 public 생성자를 사용하는 비추상이어야 합니다.Must be non-abstract with a public parameterless constructor.
  • 형식의 모든 공용 읽기-쓰기 속성이 바인딩됩니다.All public read-write properties of the type are bound.
  • 필드가 바인딩되지 않았습니다.Fields are not bound. 위 코드에서 Position은 바운딩되지 않습니다.In the preceding code, Position is not bound. Position 속성을 사용하므로 클래스를 구성 공급자에 바인딩할 때 문자열 "Position"을 앱에서 하드 코딩하지 않아도 됩니다.The Position property 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:

  • ConfigurationBinder.Bind를 호출하여 PositionOptions 클래스를 Position 섹션에 바인딩합니다.Calls ConfigurationBinder.Bind to bind the PositionOptions class to the Position section.
  • Position 구성 데이터를 표시합니다.Displays the 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}");
    }
}

위 코드에서는 기본적으로 앱을 시작한 후의 JSON 구성 파일의 변경 사항을 읽습니다.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

ConfigurationBinder.Get<T>는 지정된 형식을 바인딩하고 반환합니다.ConfigurationBinder.Get<T> binds and returns the specified type. ConfigurationBinder.Get<T>ConfigurationBinder.Bind를 사용하는 것보다 편리할 수 있습니다.ConfigurationBinder.Get<T> may be more convenient than using ConfigurationBinder.Bind. 다음 코드에서는 ConfigurationBinder.Get<T>PositionOptions 클래스를 함께 사용하는 방법을 보여 줍니다.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}");
    }
}

위 코드에서는 기본적으로 앱을 시작한 후의 JSON 구성 파일의 변경 사항을 읽습니다.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

옵션 패턴 을 사용하는 경우 대체 방법은 Position 섹션을 바인딩하고 종속성 주입 서비스 컨테이너에 추가하는 것입니다.An alternative approach when using the *options pattern _ is to bind the Position section and add it to the dependency injection service container. 다음 코드에서 PositionOptions는 <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_>를 통해 서비스 컨테이너에 추가되고 구성에 바인딩됩니다.In the following code, PositionOptions is added to the service container with <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> and bound to configuration:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

위의 코드를 사용하여 다음 코드는 위치 옵션을 읽습니다.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}");
    }
}

위 코드에서는 앱을 시작한 후의 JSON 구성 파일의 변경 사항을 읽지 않습니다.In the preceding code, changes to the JSON configuration file after the app has started are not read. 앱을 시작한 후의 변경 사항을 읽으려면 IOptionsSnapshot을 사용합니다.To read changes after the app has started, use IOptionsSnapshot.

기본 구성을 사용하여 appsettings.jsonappsettings. Environment .json 파일은 reloadOnChange: true를 통해 사용하도록 설정됩니다.Using the default configuration, the appsettings.json and appsettings.Environment.json files are enabled with reloadOnChange: true. 앱이 시작된 이후 appsettings.jsonappsettings. Environment .json 파일에 대한 변경 내용은 JSON 구성 공급자에서 읽습니다.Changes made to the appsettings.json and appsettings.Environment.json file after the app starts are read by the JSON configuration provider.

추가 JSON 구성 파일 추가에 대한 자세한 내용은 이 문서의 JSON 구성 공급자를 참조하세요.See JSON configuration provider in this document for information on adding additional JSON configuration files.

서비스 컬렉션 결합Combining service collection

서비스를 등록하고 옵션을 구성하는 다음 ConfigureServices 메서드를 고려합니다.Consider the following ConfigureServices method, which registers services and configures options:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(
        Configuration.GetSection(PositionOptions.Position));
    services.Configure<ColorOptions>(
        Configuration.GetSection(ColorOptions.Color));

    services.AddScoped<IMyDependency, MyDependency>();
    services.AddScoped<IMyDependency2, MyDependency2>();

    services.AddRazorPages();
}

관련 등록 그룹을 확장 메서드로 이동하여 서비스를 등록할 수 있습니다.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;
        }
    }
}

나머지 서비스는 유사한 클래스에 등록됩니다.The remaining services are registered in a similar class. 다음 ConfigureServices 메서드는 새 확장 메서드를 사용하여 서비스를 등록합니다.The following ConfigureServices method uses the new extension methods to register the services:

public void ConfigureServices(IServiceCollection services)
{
    services.AddConfig(Configuration)
            .AddMyDependencyGroup();

    services.AddRazorPages();
}

참고:services.Add{GROUP_NAME} 확장 메서드는 서비스를 추가하고 잠재적으로 구성합니다.Note: Each services.Add{GROUP_NAME} extension method adds and potentially configures services. 예를 들어 AddControllersWithViews는 보기에 필요한 서비스 MVC 컨트롤러를 추가하고 AddRazorPages는 Razor Pages에 필요한 서비스를 추가합니다.For example, AddControllersWithViews adds the services MVC controllers with views require, and AddRazorPages adds the services Razor Pages requires. 앱에서 이 명명 규칙을 따르는 것이 좋습니다.We recommended that apps follow this naming convention. 확장 메서드를 Microsoft.Extensions.DependencyInjection 네임스페이스에 배치하여 서비스 등록 그룹을 캡슐화합니다.Place extension methods in the Microsoft.Extensions.DependencyInjection namespace to encapsulate groups of service registrations.

보안 및 사용자 비밀Security and user secrets

구성 데이터 지침:Configuration data guidelines:

  • 구성 공급자 코드 또는 일반 텍스트 구성 파일에 암호 또는 기타 중요한 데이터를 절대 저장하지 마세요.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files. 비밀 관리자 도구를 사용하여 개발에 사용되는 비밀을 저장할 수 있습니다.The Secret Manager tool can be used to store secrets in development.
  • 개발 또는 테스트 환경에서 프로덕션 비밀을 사용하지 마세요.Don't use production secrets in development or test environments.
  • 의도치 않게 소스 코드 리포지토리에 커밋되는 일이 없도록 프로젝트 외부에서 비밀을 지정하세요.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

기본적으로, 사용자 비밀 구성 소스는 JSON 구성 소스 뒤에 등록됩니다.By default, the user secrets configuration source is registered after the JSON configuration sources. 따라서 사용자 비밀 키가 appsettings.jsonappsettings. Environment .json 의 키보다 우선합니다.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가 ASP.NET Core 앱에 대한 앱 비밀을 안전하게 저장합니다.Azure Key Vault safely stores app secrets for ASP.NET Core apps. 자세한 내용은 ASP.NET Core의 Azure Key Vault 구성 공급자를 참조하세요.For more information, see ASP.NET Core의 Azure Key Vault 구성 공급자.

환경 변수Environment variables

기본 구성을 사용하여 EnvironmentVariablesConfigurationProviderappsettings.json , appsettings. Environment .json, 사용자 비밀을 읽은 후 환경 변수 키-값 쌍에서 구성을 로드합니다.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json, appsettings.Environment.json, and user secrets. 따라서 환경에서 읽은 키 값이 appsettings.json , appsettings. Environment .json 및 사용자 비밀에서 읽은 값을 재정의합니다.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. 이중 밑줄 __은 다음과 같습니다.__, the double underscore, is:

  • 모든 플랫폼에서 지원됩니다.Supported by all platforms. 예를 들어 : 구분 기호는 Bash에서 지원되지 않지만 __은 지원됩니다.For example, the : separator is not supported by Bash, but __ is.
  • 자동으로 :으로 대체Automatically replaced by a :

다음 set 명령은,The following set commands:

  • Windows에서 위의 예제에 나오는 환경 키 및 값을 설정합니다.Set the environment keys and values of the preceding example on Windows.
  • 샘플 다운로드를 사용하는 경우 설정을 테스트합니다.Test the settings when using the sample download. dotnet run 명령은 프로젝트 디렉터리에서 실행해야 합니다.The 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:

  • 설정된 명령 창에서 시작된 프로세스에서만 설정됩니다.Are only set in processes launched from the command window they were set in.
  • Visual Studio에서 시작된 브라우저에서는 읽을 수 없습니다.Won't be read by browsers launched with Visual Studio.

다음 setx 명령을 사용하여 Windows에서 환경 키 및 값을 설정할 수 있습니다.The following setx commands can be used to set the environment keys and values on Windows. set와 달리, setx 설정은 유지됩니다.Unlike set, setx settings are persisted. /M은 시스템 환경에서 변수를 설정합니다./M sets the variable in the system environment. /M 스위치를 사용하지 않으면 사용자 환경 변수가 설정됩니다.If the /M switch isn't used, a user environment variable is set.

setx MyKey "My key from setx Environment" /M
setx Position__Title Setx_Environment_Editor /M
setx Position__Name Environment_Rick /M

위의 명령이 appsettings.jsonappsettings. Environment .json 을 재정의하는지 테스트하려면:To test that the preceding commands override appsettings.json and appsettings.Environment.json:

  • Visual Studio를 사용하는 경우: Visual Studio를 종료했다가 다시 시작합니다.With Visual Studio: Exit and restart Visual Studio.
  • CLI를 사용하는 경우: 새 명령 창을 시작하고 dotnet run을 입력합니다.With the CLI: Start a new command window and enter dotnet run.

환경 변수의 접두사를 지정하는 문자열을 사용하여 AddEnvironmentVariables를 호출합니다.Call AddEnvironmentVariables with a string to specify a prefix for environment variables:

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.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

위의 코드에서In the preceding code:

구성 키-값 쌍을 읽으면 접두사는 제거됩니다.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

기본 구성DOTNET_ASPNETCORE_ 접두사가 붙은 환경 변수 및 명령줄 인수를 로드합니다.The default configuration loads environment variables and command line arguments prefixed with DOTNET_ and ASPNETCORE_. DOTNET_ASPNETCORE_ 접두사는 ASP.NET Core에서 호스트 및 앱 구성에 사용되지만, 사용자 구성에는 사용되지 않습니다.The DOTNET_ and ASPNETCORE_ prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. 호스트 및 앱 구성에 대한 자세한 내용은 .NET 제네릭 호스트를 참조하세요.For more information on host and app configuration, see .NET Generic Host.

Azure App Service설정 > 구성 페이지에서 새 애플리케이션 설정 을 선택합니다.On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service 애플리케이션 설정은,Azure App Service application settings are:

  • 미사용 시 암호화되고 암호화된 채널을 통해 전송됩니다.Encrypted at rest and transmitted over an encrypted channel.
  • 환경 변수로 노출됩니다.Exposed as environment variables.

자세한 내용은 Azure 앱: Azure Portal을 사용하여 앱 구성 재정의 편을 참조하세요.For more information, see Azure Apps: Override app configuration using the Azure Portal.

Azure 데이터베이스 연결 문자열에 대한 자세한 내용은 연결 문자열 접두사를 참조하세요.See Connection string prefixes for information on Azure database connection strings.

환경 변수 명명Naming of environment variables

환경 변수의 이름은 appsettings.json 파일의 구조를 반영합니다.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. 다음 appsettings.json 파일 및 환경 변수라고 표시된 해당 값을 살펴보세요.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

생성된 launchSettings.json에 설정된 환경 변수Environment variables set in generated launchSettings.json

launchSettings.json 에 설정된 환경 변수는 시스템 환경에 설정된 변수를 재정의합니다.Environment variables set in launchSettings.json override those set in the system environment. 예를 들어 ASP.NET Core 웹 템플릿은 엔드포인트 구성을 다음으로 설정하는 launchSettings.json 파일을 생성합니다.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"

applicationUrl 구성은 ASPNETCORE_URLS 환경 변수를 설정하고 환경에 설정된 값을 재정의합니다.Configuring the applicationUrl sets the ASPNETCORE_URLS environment variable and overrides values set in the environment.

Linux에서 환경 변수 이스케이프Escape environment variables on Linux

Linux에서는 URL 환경 변수의 값을 이스케이프 처리하여 systemd가 구문 분석을 할 수 있도록 해야 합니다.On Linux, the value of URL environment variables must be escaped so systemd can parse it. http:--localhost:5001을 생성하는 Linux 도구 systemd-escape를 사용하세요.Use the linux tool systemd-escape which yields http:--localhost:5001

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

환경 변수 표시Display environment variables

다음 코드는 애플리케이션 시작 시 환경 설정을 디버그할 때 도움이 될 수 있는 환경 변수 및 값을 표시합니다.The following code displays the environment variables and values on application startup, which can be helpful when debugging environment settings:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var config = host.Services.GetRequiredService<IConfiguration>();

    foreach (var c in config.AsEnumerable())
    {
        Console.WriteLine(c.Key + " = " + c.Value);
    }
    host.Run();
}

명령줄Command-line

기본 구성을 사용하여 CommandLineConfigurationProvider는 다음 구성 소스 뒤에 명령줄 인수 키-값 쌍에서 구성을 로드합니다.Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:

  • appsettings.jsonappsettings.Environment.json 파일.appsettings.json and appsettings.Environment.json files.
  • 개발 환경의 앱 비밀.App secrets in the Development environment.
  • 환경 변수.Environment variables.

기본적으로, 명령줄에 설정된 구성 값은 다른 모든 구성 공급자를 사용하여 설정된 구성 값을 재정의합니다.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.

명령줄 인수Command-line arguments

다음 명령은 =을 사용하여 키 및 값을 설정합니다.The following command sets keys and values using =:

dotnet run MyKey="My key from command line" 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:

  • = 다음에 와야 합니다. 또는 값이 공백에 다음에 오는 경우 키에 -- 또는 / 접두사가 있어야 합니다.Must follow =, or the key must have a prefix of -- or / when the value follows a space.
  • =이 사용된 경우 필요하지 않습니다.Isn't required if = is used. 예: MySetting=.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

스위치 매핑은 이름 교체 논리를 지원합니다.Switch mappings allow key name replacement logic. AddCommandLine 메서드에 스위치 교체 사전을 제공합니다.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:

  • 스위치는 - 또는 --으로 시작해야 합니다.Switches must start with - or --.
  • 스위치 매핑 사전이 중복 키를 포함하면 안 됩니다.The switch mappings dictionary must not contain duplicate keys.

스위치 매핑 사전을 사용하려면 AddCommandLine에 대한 호출에 전달합니다.To use a switch mappings dictionary, pass it into the call to AddCommandLine:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

다음 코드는 교체된 키의 키 값을 보여 줍니다.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"]}'");
    }
}

다음 명령은 작동하여 키 교체를 테스트합니다.The following command works to test key replacement:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

스위치 매핑을 사용하는 앱의 경우 CreateDefaultBuilder에 대한 호출은 인수를 전달하지 않아야 합니다.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. CreateDefaultBuilder 메서드의 AddCommandLine 호출에는 매핑된 스위치가 포함되지 않으며 CreateDefaultBuilder에 스위치 매핑 사전을 전달할 방법은 없습니다.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch-mapping dictionary to CreateDefaultBuilder. 해결 방법으로 CreateDefaultBuilder에 인수를 전달하지 않고 대신 ConfigurationBuilder 메서드의 AddCommandLine 메서드에서 인수와 스위치 매핑 사전을 모두 처리하도록 할 수 있습니다.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.

계층적 구성 데이터Hierarchical configuration data

구성 API는 구성 키에 구분 기호를 사용해 계층적 데이터를 평면화하여 계층적 구성 데이터를 읽습니다.The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

샘플 다운로드에는 다음 appsettings.json 파일이 포함되어 있습니다.The sample download contains the following appsettings.json file:

{
    "Position": {
        "Title": "편집기",
        "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.

구성 데이터에서는 GetSectionGetChildren 메서드를 사용하여 섹션과 섹션의 자식을 격리할 수 있습니다.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. 이러한 메서드에 대해서는 나중에 GetSection, GetChildren 및 Exists에서 설명합니다.These methods are described later in GetSection, GetChildren, and Exists.

구성 키 및 값Configuration keys and values

구성 키는,Configuration keys:

  • 대/소문자를 구분하지 않습니다.Are case-insensitive. 예를 들어 ConnectionStringconnectionstring은 동일한 키로 처리됩니다.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • 두 개 이상의 구성 공급자에 키와 값이 설정되어 있으면 추가된 마지막 공급자의 값이 사용됩니다.If a key and value is set in more than one configuration providers, the value from the last provider added is used. 자세한 내용은 기본 구성을 참조하세요.For more information, see Default configuration.
  • 계층적 키Hierarchical keys
    • 구성 API 내에서는 콜론 구분 기호(:)가 모든 플랫폼에 적용됩니다.Within the Configuration API, a colon separator (:) works on all platforms.
    • 환경 변수에서는 콜론 구분 기호가 일부 플랫폼에 적용되지 않을 수 있습니다.In environment variables, a colon separator may not work on all platforms. 두 개의 밑줄(__)은 모든 플랫폼에서 지원되며 콜론(:)으로 자동 변환됩니다.A double underscore, __, is supported by all platforms and is automatically converted into a colon :.
    • Azure Key Vault에서 계층적 키는 --를 구분 기호로 사용합니다.In Azure Key Vault, hierarchical keys use -- as a separator. Azure Key Vault 구성 공급자는 암호를 앱의 구성으로 로드할 때 --를 자동으로 :으로 바꿉니다.The Azure Key Vault configuration provider automatically replaces -- with a : when the secrets are loaded into the app's configuration.
  • ConfigurationBinder는 구성 키에 배열 인덱스를 사용하여 배열을 개체에 바인딩하는 것을 지원합니다.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. 배열 바인딩에 대해서는 클래스에 배열 바인딩 섹션에서 설명합니다.Array binding is described in the Bind an array to a class section.

구성 값은,Configuration values:

  • 문자열입니다.Are strings.
  • Null 값은 구성에 저장하거나 개체에 바인딩할 수 없습니다.Null values can't be stored in configuration or bound to objects.

구성 공급자Configuration providers

다음 표에서는 ASP.NET Core 앱에서 사용할 수 있는 구성 공급자를 보여 줍니다.The following table shows the configuration providers available to ASP.NET Core apps.

공급자Provider 다음에서 구성 제공Provides configuration from
Azure Key Vault 구성 공급자Azure Key Vault configuration provider Azure Key VaultAzure Key Vault
Azure 앱 구성 공급자Azure App configuration provider Azure App ConfigurationAzure 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 및 XML 파일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:

  1. appsettings.json
  2. appsettings.Environment.jsonappsettings.Environment.json
  3. 사용자 비밀User secrets
  4. 환경 변수 구성 공급자를 사용하는 환경 변수Environment variables using the Environment Variables configuration provider.
  5. 명령줄 구성 공급자를 사용하는 명령줄 인수Command-line arguments using the Command-line configuration provider.

일반적인 방식은 명령줄 구성 공급자를 일련의 공급자에서 마지막에 추가하는 것이므로, 다른 공급자에서 설정한 구성을 명령줄 인수로 재정의할 수 있습니다.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.

연결 문자열 접두사Connection string prefixes

구성 API에는 네 개의 연결 문자열 환경 변수에 대한 특별한 처리 규칙이 있습니다.The Configuration API has special processing rules for four connection string environment variables. 해당 연결 문자열은 앱 환경의 Azure 연결 문자열을 구성하는 데 관련됩니다.These connection strings are involved in configuring Azure connection strings for the app environment. 기본 구성을 사용하거나 AddEnvironmentVariables에 제공된 접두사가 없는 경우 표에 표시된 접두사가 붙은 환경 변수가 앱에 로드됩니다.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_ MySQLMySQL
SQLAZURECONNSTR_ Azure SQL DatabaseAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

표에 표시된 네 개 접두사 중 하나가 붙은 환경 변수가 검색되어 구성으로 로드되면 다음과 같이 됩니다.When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • 환경 변수 접두사를 제거하고 구성 키 섹션(ConnectionStrings)을 추가하여 구성 키가 생성됩니다.The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • 데이터베이스 연결 제공자(지정된 공급자가 없는 CUSTOMCONNSTR_ 제외)를 나타내는 새 구성 키-값 쌍이 생성됩니다.A new configuration key-value pair is created that represents the database connection provider (except for 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} 키: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
값: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} 키: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
값: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} 키: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
값: System.Data.SqlClientValue: System.Data.SqlClient

파일 구성 공급자File configuration provider

FileConfigurationProvider는 파일 시스템에서 구성을 로드하기 위한 기본 클래스입니다.FileConfigurationProvider is the base class for loading configuration from the file system. 다음 구성 공급자는 FileConfigurationProvider에서 파생됩니다.The following configuration providers derive from FileConfigurationProvider:

INI 구성 공급자INI configuration provider

IniConfigurationProvider는 런타임에 INI 파일 키-값 쌍에서 구성을 로드합니다.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

다음 코드는 모든 구성 공급자를 지우고 여러 구성 공급자를 추가합니다.The following code clears all the configuration providers and adds several 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.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

위의 코드에서 MyIniConfig.iniMyIniConfig.Environment.ini 파일의 설정은 다음의 설정에 의해 재정의됩니다.In the preceding code, settings in the MyIniConfig.ini and MyIniConfig.Environment.ini files are overridden by settings in the:

샘플 다운로드에는 다음 MyIniConfig.ini 파일이 포함되어 있습니다.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}");
    }
}

JSON 구성 공급자JSON configuration provider

JsonConfigurationProvider는 JSON 파일 키-값 쌍에서 구성을 로드합니다.The JsonConfigurationProvider loads configuration from JSON file key-value pairs.

오버로드는 다음을 지정할 수 있습니다.Overloads can specify:

  • 파일이 선택 사항인지 여부Whether the file is optional.
  • 파일이 변경되면 구성을 다시 로드하는지 여부Whether the configuration is reloaded if the file changes.

다음 코드를 살펴보세요.Consider the following code:

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("MyConfig.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

위의 코드는The preceding code:

  • 다음 옵션을 사용하여 MyConfig.json 파일을 로드하도록 JSON 구성 공급자를 구성합니다.Configures the JSON configuration provider to load the MyConfig.json file with the following options:
    • optional: true: 파일은 선택 사항입니다.optional: true: The file is optional.
    • reloadOnChange: true은: 변경 내용이 저장되면 파일이 다시 로드됩니다.reloadOnChange: true : The file is reloaded when changes are saved.
  • MyConfig.json 파일 전에 기본 구성 공급자를 읽습니다.Reads the default configuration providers before the MyConfig.json file. MyConfig.json 파일의 설정은 환경 변수 구성 공급자명령줄 구성 공급자를 비롯한 기본 구성 공급자의 설정을 재정의합니다.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.

일반적으로 사용자 지정 JSON 파일이 환경 변수 구성 공급자명령줄 구성 공급자에 설정된 값을 재정의하기를 원치 않습니다.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 following code clears all the configuration providers and adds several 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.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                                     optional: true, reloadOnChange: true);

                config.AddJsonFile("MyConfig.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"MyConfig.{env.EnvironmentName}.json",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

위의 코드에서 MyConfig.jsonMyConfig.Environment.json 파일의 설정은,In the preceding code, settings in the MyConfig.json and MyConfig.Environment.json files:

샘플 다운로드에는 다음 MyConfig.json 파일이 포함되어 있습니다.The sample download contains the following MyConfig.json file:

{
    "Position": {
        "Title": "내 구성 제목",
        "Name": "My Config Smith"
    },
    "MyKey": "MyConfig.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}");
    }
}

XML 구성 공급자XML configuration provider

XmlConfigurationProvider는 런타임에 XML 파일 키-값 쌍에서 구성을 로드합니다.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

다음 코드는 모든 구성 공급자를 지우고 여러 구성 공급자를 추가합니다.The following code clears all the configuration providers and adds several 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.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
                      .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

위의 코드에서 MyXMLFile.xmlMyXMLFile.Environment.xml 파일의 설정은 다음의 설정에 의해 재정의됩니다.In the preceding code, settings in the MyXMLFile.xml and MyXMLFile.Environment.xml files are overridden by settings in the:

샘플 다운로드에는 다음 MyXMLFile.xml 파일이 포함되어 있습니다.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}");
    }
}

같은 요소 이름을 사용하는 반복 요소는 다음과 같이 name 특성을 사용하여 요소를 구분하면 작동합니다.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>

이전 구성 파일은 value와 함께 다음 키를 로드합니다.The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

파일별 키 구성 공급자Key-per-file configuration provider

KeyPerFileConfigurationProvider는 디렉터리의 파일을 구성 키-값 쌍으로 사용합니다.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. 파일별 키 구성 공급자는 Docker 호스팅 시나리오에서 사용됩니다.The Key-per-file configuration provider is used in Docker hosting scenarios.

파일별 키 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddKeyPerFile 확장 메서드를 호출합니다.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. 파일의 directoryPath는 절대 경로여야 합니다.The directoryPath to the files must be an absolute path.

오버로드에서는 다음을 지정할 수 있습니다.Overloads permit specifying:

  • 소스를 구성하는 Action<KeyPerFileConfigurationSource> 대리자An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • 디렉터리가 선택 사항인지 여부와 디렉터리의 경로Whether the directory is optional and the path to the directory.

두 개의 밑줄(__)은 파일 이름에서 구성 키 구분 기호로 사용됩니다.The double-underscore (__) is used as a configuration key delimiter in file names. 예를 들어, 파일 이름 Logging__LogLevel__System은 구성 키 Logging:LogLevel:System을 생성합니다.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

호스트를 빌드할 때 ConfigureAppConfiguration을 호출하여 앱의 구성을 지정합니다.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);
})

메모리 구성 공급자Memory configuration provider

MemoryConfigurationProvider는 메모리 내 컬렉션을 구성 키-값 쌍으로 사용합니다.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

다음 코드는 구성 시스템에 메모리 컬렉션을 추가합니다.The following code adds a memory collection to the configuration system:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(Dict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

샘플 다운로드의 다음 코드는 위의 구성 설정을 표시합니다.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}");
    }
}

위의 코드에서 config.AddInMemoryCollection(Dict)기본 구성 공급자 뒤에 추가됩니다.In the preceding code, config.AddInMemoryCollection(Dict) is added after the default configuration providers. 구성 공급자 순서 지정 예제는 JSON 구성 공급자를 참조하세요.For an example of ordering the configuration providers, see JSON configuration provider.

MemoryConfigurationProvider를 사용하는 또 다른 예제는 배열 바인딩을 참조하세요.See Bind an array for another example using MemoryConfigurationProvider.

Kestrel 엔드포인트 구성Kestrel endpoint configuration

Kestrel 관련 엔드포인트 구성은 모든 서버 간 엔드포인트 구성을 재정의합니다.Kestrel specific endpoint configuration overrides all cross-server endpoint configurations. 서버 간 엔드포인트 구성에는 다음이 포함됩니다.Cross-server endpoint configurations include:

ASP.NET Core 웹 앱에서 사용되는 다음 appsettings.json 파일을 고려합니다.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": "*"
} 

위에 강조 표시된 마크업을 ASP.NET Core 웹 앱에 사용 하면서 다음과 같은 서버 간 엔드포인트 구성을 사용하여 명령줄에서 앱을 시작하는 경우,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은 appsettings.json 파일(https://localhost:9999)에서 Kestrel용으로 특별히 구성된 엔드포인트에 바인딩됩니다(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.

환경 변수로 구성된 Kestrel 관련 엔드포인트를 고려합니다.Consider the Kestrel specific endpoint configured as an environment variable:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

위 환경 변수에서 Https는 Kestrel 관련 엔드포인트의 이름입니다.In the preceding environment variable, Https is the name of the Kestrel specific endpoint. 또한 위 appsettings.json 파일은 Https라는 Kestrel 관련 엔드포인트를 정의합니다.The preceding appsettings.json file also defines a Kestrel specific endpoint named Https. 기본적으로 환경 변수 구성 공급자를 사용하는 환경 변수는 appsettings. Environment .json 이후에 읽혀지므로 위 환경 변수는 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.

GetValueGetValue

ConfigurationBinder.GetValue<T>는 지정된 키를 사용하여 구성에서 단일 값을 추출하고 해당 값을 지정된 형식으로 변환합니다.ConfigurationBinder.GetValue<T> 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}");
    }
}

위의 코드에서 구성에 NumberKey가 없는 경우 기본값 99가 사용됩니다.In the preceding code, if NumberKey isn't found in the configuration, the default value of 99 is used.

GetSection, GetChildren 및 ExistsGetSection, GetChildren, and Exists

이어지는 예제에서는 다음 MySubsection.json 파일을 고려하세요.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"
    }
  }
}

다음 코드는 구성 공급자에 MySubsection.json 을 추가합니다.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>();
            });
}

GetSectionGetSection

IConfiguration.GetSection은 지정된 하위 섹션 키를 사용하여 구성 하위 섹션을 반환합니다.IConfiguration.GetSection returns a configuration subsection with the specified subsection key.

다음 코드는 section1의 값을 반환합니다.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"]}'");
    }
}

다음 코드는 section2:subsection0의 값을 반환합니다.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"]}'");
    }
}

GetSectionnull을 반환하지 않습니다.GetSection never returns null. 일치하는 섹션을 찾을 수 없으면 빈 IConfigurationSection이 반환됩니다.If a matching section isn't found, an empty IConfigurationSection is returned.

GetSection이 일치하는 섹션을 반환할 때 Value는 채워지지 않습니다.When GetSection returns a matching section, Value isn't populated. 섹션이 존재하면 KeyPath가 반환됩니다.A Key and Path are returned when the section exists.

GetChildren 및 ExistsGetChildren and Exists

다음 코드는 IConfiguration.GetChildren을 호출하고 section2:subsection0의 값을 반환합니다.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);
    }
}

위의 코드는 ConfigurationExtensions.Exists를 호출하여 섹션이 있는지 확인합니다.The preceding code calls ConfigurationExtensions.Exists to verify the section exists:

배열 바인딩Bind an array

ConfigurationBinder.Bind는 구성 키에서 배열 인덱스를 사용하여 배열을 개체에 바인딩할 수 있도록 지원합니다.The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. 숫자 키 세그먼트를 노출하는 모든 배열 형식은 POCO 클래스 배열에 배열을 바인딩할 수 있습니다.Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.

샘플 다운로드MyArray.json 을 고려하세요.Consider MyArray.json from the sample download:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

다음 코드는 구성 공급자에 MyArray.json 을 추가합니다.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

위의 출력에서 Index 3은 MyArray.json"4": "value40",에 해당하는 value40 값을 가집니다.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. 구성 바인더는 null 값을 바인딩하거나 바인딩된 개체에 null 항목을 만들 수 없습니다.The configuration binder isn't capable of binding null values or creating null entries in bound objects

다음 코드는 AddInMemoryCollection 확장 메서드를 사용하여 array:entries 구성을 로드합니다.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>();
            });
    }
}

다음 코드는 arrayDict Dictionary의 구성을 읽고 값을 표시합니다.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

바인딩된 개체의 인덱스 #3은 array:4 구성 키에 대한 구성 데이터와 value4의 값을 포함합니다.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. 구성 데이터에 null 값을 유지할 수 없으며, 구성 키의 배열에서 하나 이상의 인덱스를 건너뛰더라도 바인딩된 개체에 null 값 항목이 생성되지 않습니다.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.

Index #3에 대한 누락된 구성 항목은 Index #3 키/값 쌍을 읽는 모든 구성 공급자에서 ArrayExample 인스턴스에 바인딩하기 전에 제공할 수 있습니다.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. 샘플 다운로드의 다음 Value3.json 파일을 고려하세요.Consider the following Value3.json file from the sample download:

{
  "array:entries:3": "value3"
}

다음 코드에는 Value3.jsonarrayDict Dictionary의 구성이 포함되어 있습니다.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.

사용자 지정 구성 공급자Custom configuration provider

샘플 앱에서는 EF(Entity Framework)를 사용하여 데이터베이스에서 구성 키-값 쌍을 읽는 기본 구성 공급자를 만드는 방법을 보여 줍니다.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:

  • 데모용으로 EF 메모리 내 데이터베이스를 사용합니다.The EF in-memory database is used for demonstration purposes. 연결 문자열이 필요한 데이터베이스를 사용하려면 보조 ConfigurationBuilder를 구현하여 다른 구성 공급자에서 연결 문자열을 제공하세요.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • 이 공급자는 시작 시 데이터베이스 테이블을 구성으로 읽어 들입니다.The provider reads a database table into configuration at startup. 이 공급자는 키별 기준으로 데이터베이스를 쿼리하지 않습니다.The provider doesn't query the database on a per-key basis.
  • 변경 시 다시 로드가 구현되지 않으므로 앱 시작 후 데이터베이스를 업데이트해도 앱 구성에 영향을 주지 않습니다.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

데이터베이스에 구성 값을 저장하는 EFConfigurationValue 엔터티를 정의합니다.Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

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

구성된 값을 저장 및 액세스하는 EFConfigurationContext를 추가합니다.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

// using Microsoft.EntityFrameworkCore;

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

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

IConfigurationSource를 구현하는 클래스를 만듭니다.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs: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);
    }
}

ConfigurationProvider에서 상속하여 사용자 지정 구성 공급자를 만듭니다.Create the custom configuration provider by inheriting from ConfigurationProvider. 구성 공급자는 비어 있는 데이터베이스를 초기화합니다.The configuration provider initializes the database when it's empty. 구성 키는 대/소문자를구분하지 않으므로 데이터베이스를 초기화하는 데 사용되는 사전은 대/소문자를 구분하지 않는 비교자(StringComparer.OrdinalIgnoreCase)를 사용하여 생성됩니다.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: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
        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;
    }
}

AddEFConfiguration 확장 메서드를 사용하여 구성 소스를 ConfigurationBuilder에 추가할 수 있습니다.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs: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));
    }
}

다음 코드는 Program.cs 에서 사용자 지정 EFConfigurationProvider를 사용하는 방법을 보여 줍니다.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"));
        })

시작 시 구성 액세스Access configuration in Startup

다음 코드는 Startup 메서드의 구성 데이터를 표시합니다.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.

Razor Pages의 구성 액세스Access configuration in Razor Pages

다음 코드는 Razor 페이지의 구성 데이터를 표시합니다.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"]

다음 코드에서 MyOptionsConfigure를 통해 서비스 컨테이너에 추가되고 구성에 바인딩됩니다.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();
}

다음 표시는 @inject Razor 지시문을 사용하여 옵션 값을 확인하고 표시합니다.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>

MVC 뷰 파일의 구성 액세스Access configuration in a MVC view file

다음 코드는 MVC 뷰의 구성 데이터를 표시합니다.The following code displays configuration data in a MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

대리자로 옵션 구성Configure options with a delegate

대리자에서 구성된 옵션은 구성 공급자에 설정된 값을 재정의합니다.Options configured in a delegate override values set in the configuration providers.

대리자를 사용한 옵션 구성은 샘플 앱에 예제 2로 설명되어 있습니다.Configuring options with a delegate is demonstrated as Example 2 in the sample app.

다음 코드에서 IConfigureOptions<TOptions> 서비스가 서비스 컨테이너에 추가됩니다.In the following code, an IConfigureOptions<TOptions> service is added to the service container. MyOptions의 값을 구성하는 데 대리자를 사용합니다.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}");
    }
}

위의 예제에서 Option1Option2의 값은 모두 appsettings.json 에서 지정되고 구성된 대리자에 의해 재정의됩니다.In the preceding example, the values of Option1 and Option2 are specified in appsettings.json and then overridden by the configured delegate.

호스트 대 앱 구성Host versus app configuration

앱을 구성하고 시작하기 전에 호스트 를 구성하고 시작합니다.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. 호스트를 빌드할 때 구성 공급자를 사용하는 방법과 구성 소스가 호스트 구성에 미치는 영향에 대한 자세한 내용은 ASP.NET Core 기본 사항를 참조하세요.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 기본 사항.

기본 호스트 구성Default host configuration

웹 호스트를 사용하는 경우 기본 구성에 대한 자세한 내용은 이 항목의 ASP.NET Core 2.2 버전을 참조하세요.For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

  • 호스트 구성은 다음에 의해 제공됩니다.Host configuration is provided from:
  • 웹 호스트 기본 구성이 설정됩니다(ConfigureWebHostDefaults).Web Host default configuration is established (ConfigureWebHostDefaults):
    • Kestrel은 웹 서버로 사용되며 앱의 구성 공급자를 사용하여 구성됩니다.Kestrel is used as the web server and configured using the app's configuration providers.
    • 호스트 필터링 미들웨어를 추가합니다.Add Host Filtering Middleware.
    • ASPNETCORE_FORWARDEDHEADERS_ENABLED 환경 변수가 true로 설정된 경우 전달된 헤더 미들웨어를 추가합니다.Add Forwarded Headers Middleware if the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true.
    • IIS 통합을 사용하도록 설정합니다.Enable IIS integration.

기타 구성Other configuration

이 항목에서는 앱 구성 에 관련된 내용만 다룹니다.This topic only pertains to app configuration. ASP.NET Core 앱을 실행하고 호스팅하는 다른 요소는 이 항목에서 다루지 않는 구성 파일을 사용하여 구성됩니다.Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.json/launchSettings.json 은 다음에 설명된 개발 환경에 대한 도구 구성 파일입니다.launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config 는 다음 항목에 설명된 서버 구성 파일입니다.web.config is a server configuration file, described in the following topics:

launchSettings.json 에 설정된 환경 변수는 시스템 환경에 설정된 변수를 재정의합니다.Environment variables set in launchSettings.json override those set in the system environment.

이전 버전의 ASP.NET에서 앱 구성을 마이그레이션하는 방법에 대한 자세한 정보는 ASP.NET에서 ASP.NET Core로 마이그레이션를 참조하세요.For more information on migrating app configuration from earlier versions of ASP.NET, see ASP.NET에서 ASP.NET Core로 마이그레이션.

외부 어셈블리의 구성 추가Add configuration from an external assembly

IHostingStartup 구현은 시작 시 앱의 Startup 클래스 외부에 있는 외부 어셈블리에서 앱에 향상된 기능을 추가할 수 있습니다.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. 자세한 내용은 ASP.NET Core에서 호스팅 시작 어셈블리 사용를 참조하세요.For more information, see ASP.NET Core에서 호스팅 시작 어셈블리 사용.

추가 자료Additional resources

ASP.NET Core의 앱 구성은 ‘구성 공급자’가 설정한 키-값 쌍을 기반으로 합니다.App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. 구성 공급자는 다양한 구성 소스에서 구성 데이터를 키-값 쌍으로 읽어 들입니다.Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Azure Key VaultAzure Key Vault
  • Azure App ConfigurationAzure App Configuration
  • 명령줄 인수Command-line arguments
  • 사용자 지정 공급자(설치 또는 생성된)Custom providers (installed or created)
  • 디렉터리 파일Directory files
  • 환경 변수Environment variables
  • 메모리 내 .NET 개체In-memory .NET objects
  • 설정 파일Settings files

일반적인 구성 공급자 시나리오에 대한 구성 패키지(Microsoft.Extensions.Configuration)는 Microsoft.AspNetCore.App 메타패키지에 포함됩니다.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included in the Microsoft.AspNetCore.App metapackage.

샘플 앱에서 Microsoft.Extensions.Configuration 네임스페이스를 사용하는 다음 코드 예제:Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

‘옵션 패턴’은 이 항목에 설명된 구성 개념의 확장입니다.The options pattern is an extension of the configuration concepts described in this topic. 옵션은 클래스를 사용하여 관련 설정 그룹을 나타냅니다.Options use classes to represent groups of related settings. 자세한 내용은 ASP.NET Core의 옵션 패턴를 참조하세요.For more information, see ASP.NET Core의 옵션 패턴.

예제 코드 살펴보기 및 다운로드 (다운로드 방법)View or download sample code (how to download)

호스트 대 앱 구성Host versus app configuration

앱을 구성하고 시작하기 전에 호스트 를 구성하고 시작합니다.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. 호스트를 빌드할 때 구성 공급자를 사용하는 방법과 구성 소스가 호스트 구성에 미치는 영향에 대한 자세한 내용은 ASP.NET Core 기본 사항를 참조하세요.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 기본 사항.

기타 구성Other configuration

이 항목에서는 앱 구성 에 관련된 내용만 다룹니다.This topic only pertains to app configuration. ASP.NET Core 앱을 실행하고 호스팅하는 다른 요소는 이 항목에서 다루지 않는 구성 파일을 사용하여 구성됩니다.Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.json/launchSettings.json 은 다음에 설명된 개발 환경에 대한 도구 구성 파일입니다.launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config 는 다음 항목에 설명된 서버 구성 파일입니다.web.config is a server configuration file, described in the following topics:

이전 버전의 ASP.NET에서 앱 구성을 마이그레이션하는 방법에 대한 자세한 정보는 ASP.NET에서 ASP.NET Core로 마이그레이션를 참조하세요.For more information on migrating app configuration from earlier versions of ASP.NET, see ASP.NET에서 ASP.NET Core로 마이그레이션.

기본 구성Default configuration

호스트를 빌드할 때 ASP.NET Core dotnet new 템플릿을 기반으로 하는 웹앱은 CreateDefaultBuilder를 호출합니다.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder는 다음 순서로 앱에 대한 기본 구성을 제공합니다.CreateDefaultBuilder provides default configuration for the app in the following order:

웹호스트를 사용하는 앱에는 다음이 적용됩니다.The following applies to apps using the Web Host. 제네릭 호스트 사용 시 기본 구성에 대한 자세한 내용은 이 토픽의 최신 버전을 참조하세요.For details on the default configuration when using the Generic Host, see the latest version of this topic.

보안Security

중요한 구성 데이터를 보호하려면 다음 방법을 채택합니다.Adopt the following practices to secure sensitive configuration data:

  • 구성 공급자 코드 또는 일반 텍스트 구성 파일에 암호 또는 기타 중요한 데이터를 절대 저장하지 마세요.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • 개발 또는 테스트 환경에서 프로덕션 비밀을 사용하지 마세요.Don't use production secrets in development or test environments.
  • 의도치 않게 소스 코드 리포지토리에 커밋되는 일이 없도록 프로젝트 외부에서 비밀을 지정하세요.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

자세한 내용은 다음 항목을 참조하세요.For more information, see the following topics:

Azure Key Vault가 ASP.NET Core 앱에 대한 앱 비밀을 안전하게 저장합니다.Azure Key Vault safely stores app secrets for ASP.NET Core apps. 자세한 내용은 ASP.NET Core의 Azure Key Vault 구성 공급자를 참조하세요.For more information, see ASP.NET Core의 Azure Key Vault 구성 공급자.

계층적 구성 데이터Hierarchical configuration data

구성 API에서는 구성 키에 구분 기호를 사용해 계층적 데이터를 평면화하여 계층적 구성 데이터를 유지 관리할 수 있습니다.The Configuration API is capable of maintaining hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

다음 JSON 파일에서는 두 섹션으로 이루어진 구조적 계층에 네 개의 키가 있습니다.In the following JSON file, four keys exist in a structured hierarchy of two sections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

파일을 구성으로 읽어 들이면 구성 소스의 원래 계층적 데이터 구조를 유지하기 위해 고유 키가 생성됩니다.When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. 콜론(:)을 사용해 섹션과 키를 평면화하여 원래 구조를 유지합니다.The sections and keys are flattened with the use of a colon (:) to maintain the original structure:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

구성 데이터에서는 GetSectionGetChildren 메서드를 사용하여 섹션과 섹션의 자식을 격리할 수 있습니다.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. 이러한 메서드에 대해서는 나중에 GetSection, GetChildren 및 Exists에서 설명합니다.These methods are described later in GetSection, GetChildren, and Exists.

규칙Conventions

소스 및 공급자Sources and providers

앱 시작 시 구성 공급자에서 지정한 순서로 구성 소스를 읽습니다.At app startup, configuration sources are read in the order that their configuration providers are specified.

변경 검색을 구현하는 구성 공급자는 기본 설정 파일이 변경되면 구성을 다시 로드할 수 있습니다.Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. 예를 들어 파일 구성 공급자(이 항목의 뒷부분에서 설명됨) 및 Azure Key Vault 구성 공급자는 변경 검색을 구현합니다.For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

IConfiguration은 앱의 DI(종속성 주입) 컨테이너에서 사용할 수 있습니다.IConfiguration is available in the app's dependency injection (DI) container. IConfiguration을 Razor Pages PageModel 또는 MVC Controller에 삽입하여 클래스에 대한 구성을 가져올 수 있습니다.IConfiguration can be injected into a Razor Pages PageModel or MVC Controller to obtain configuration for the class.

다음 예제에서는 _config 필드가 구성 값에 액세스하는 데 사용됩니다.In the following examples, the _config field is used to access configuration values:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }
}
public class HomeController : Controller
{
    private readonly IConfiguration _config;

    public HomeController(IConfiguration config)
    {
        _config = config;
    }
}

구성 공급자는 호스트에서 설정될 때 DI가 제공되지 않으므로 DI를 활용할 수 없습니다.Configuration providers can't utilize DI, as it's not available when they're set up by the host.

Keys

구성키는 다음 규칙을 따릅니다.Configuration keys adopt the following conventions:

  • 키는 대/소문자를 구분하지 않습니다.Keys are case-insensitive. 예를 들어 ConnectionStringconnectionstring은 동일한 키로 처리됩니다.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • 같은 키의 값을 같거나 다른 여러 구성 공급자에서 설정하는 경우 키에 설정된 마지막 값이 사용되는 값입니다.If a value for the same key is set by the same or different configuration providers, the last value set on the key is the value used. 중복 JSON 키에 대한 자세한 내용은 이 GitHub 문제를 참조하세요.For more information on duplicate JSON keys, see this GitHub issue.
  • 계층적 키Hierarchical keys
    • 구성 API 내에서는 콜론 구분 기호(:)가 모든 플랫폼에 적용됩니다.Within the Configuration API, a colon separator (:) works on all platforms.
    • 환경 변수에서는 콜론 구분 기호가 일부 플랫폼에 적용되지 않을 수 있습니다.In environment variables, a colon separator may not work on all platforms. 두 개의 밑줄(__)은 모든 플랫폼에서 지원되며 콜론으로 자동 변환됩니다.A double underscore (__) is supported by all platforms and is automatically converted into a colon.
    • Azure Key Vault에서 계층적 키는 --(두 개의 대시)를 구분 기호로 사용합니다.In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. 비밀을 앱의 구성으로 로드할 때 대시를 콜론으로 바꾸는 코드를 작성하세요.Write code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • ConfigurationBinder는 구성 키에 배열 인덱스를 사용하여 배열을 개체에 바인딩하는 것을 지원합니다.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. 배열 바인딩에 대해서는 클래스에 배열 바인딩 섹션에서 설명합니다.Array binding is described in the Bind an array to a class section.

Values

구성 값은 다음 규칙을 따릅니다.Configuration values adopt the following conventions:

  • 값은 문자열입니다.Values are strings.
  • Null 값은 구성에 저장하거나 개체에 바인딩할 수 없습니다.Null values can't be stored in configuration or bound to objects.

공급자Providers

다음 표에서는 ASP.NET Core 앱에서 사용할 수 있는 구성 공급자를 보여 줍니다.The following table shows the configuration providers available to ASP.NET Core apps.

공급자Provider 다음에서 구성 제공…Provides configuration from…
Azure Key Vault 구성 공급자(‘보안’ 항목)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
Azure App Configuration 공급자(Azure 설명서)Azure App Configuration Provider (Azure documentation) Azure App ConfigurationAzure 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, XML)Files (INI, JSON, XML)
파일별 키 구성 공급자Key-per-file Configuration Provider 디렉터리 파일Directory files
메모리 구성 공급자Memory Configuration Provider 메모리 내 컬렉션In-memory collections
사용자 비밀(보안 항목)User secrets (Security topics) 사용자 프로필 디렉터리의 파일File in the user profile directory

시작 시 구성 공급자에서 지정한 순서로 구성 소스를 읽습니다.Configuration sources are read in the order that their configuration providers are specified at startup. 이 항목의 구성 공급자는 코드에서 정렬하는 순서가 아니라 사전 순으로 설명되어 있습니다.The configuration providers described in this topic are described in alphabetical order, not in the order that the code arranges them. 앱에 필요한 기본 구성 소스에 대한 우선 순위에 맞게 구성 공급자를 코드에 정렬하세요.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:

  1. 파일( appsettings.json , appsettings.{Environment}.json, 여기서 {Environment}는 앱의 현재 호스팅 환경)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Azure Key VaultAzure Key Vault
  3. 사용자 암호(개발 환경에만 해당)User secrets (Development environment only)
  4. 환경 변수Environment variables
  5. 명령줄 인수Command-line arguments

일반적인 방식은 명령줄 구성 공급자를 일련의 공급자에서 마지막에 배치하는 것이므로, 다른 공급자에서 설정한 구성을 명령줄 인수로 재정의할 수 있습니다.A common practice is to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

CreateDefaultBuilder로 새 호스트 작성기가 초기화될 때 이전 공급자 시퀀스가 사용됩니다.The preceding sequence of providers is used when a new host builder is initialized with CreateDefaultBuilder. 자세한 내용은 기본 구성 섹션을 참조하세요.For more information, see the Default configuration section.

UseConfiguration을 사용하여 호스트 작성기 구성Configure the host builder with UseConfiguration

호스트 작성기를 구성하려면 구성과 함께 호스트 작성기에서 UseConfiguration을 호출합니다.To configure the host builder, call UseConfiguration on the host builder with the configuration.

public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
    var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

    var config = new ConfigurationBuilder()
        .AddInMemoryCollection(dict)
        .Build();

    return WebHost.CreateDefaultBuilder(args)
        .UseConfiguration(config)
        .UseStartup<Startup>();
}

ConfigureAppConfigurationConfigureAppConfiguration

호스트를 빌드할 때 ConfigureAppConfiguration을 호출하여 CreateDefaultBuilder에 의해 자동으로 추가된 구성 공급자 외에도 앱의 구성 공급자를 지정합니다.Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

명령줄 인수를 사용하여 이전 구성 재정의Override previous configuration with command-line arguments

명령줄 인수를 사용하여 재정의할 수 있는 앱 구성을 제공하려면 마지막으로 AddCommandLine을 호출합니다.To provide app configuration that can be overridden with command-line arguments, call AddCommandLine last:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

CreateDefaultBuilder에 의해 추가된 공급자 제거Remove providers added by CreateDefaultBuilder

CreateDefaultBuilder에 의해 추가된 공급자를 제거하려면 먼저 IConfigurationBuilder에서 Clear를 호출합니다.To remove the providers added by CreateDefaultBuilder, call Clear on the IConfigurationBuilder.Sources first:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();
    // Add providers here
})

앱 시작 중 구성 사용Consume configuration during app startup

Startup.ConfigureServices를 포함하여 ConfigureAppConfiguration에서 앱에 제공되는 구성은 앱을 시작하는 동안 사용할 수 있습니다.Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. 자세한 내용은 시작하는 동안 구성에 액세스 섹션을 참조하세요.For more information, see the Access configuration during startup section.

명령줄 구성 공급자Command-line Configuration Provider

CommandLineConfigurationProvider은 런타임 시 명령줄 인수 키-값 쌍에서 구성을 로드합니다.The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

명령줄 구성을 활성화하기 위해 ConfigurationBuilder 인스턴스에서 AddCommandLine 확장 메서드가 호출됩니다.To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

CreateDefaultBuilder(string [])가 호출되면 AddCommandLine도 자동으로 호출됩니다.AddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. 자세한 내용은 기본 구성 섹션을 참조하세요.For more information, see the Default configuration section.

CreateDefaultBuilder는 다음 항목도 로드합니다.CreateDefaultBuilder also loads:

  • appsettings.jsonappsettings.{Environment}.json 파일에서 선택적 구성.Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • 개발 환경의 사용자 비밀.User secrets in the Development environment.
  • 환경 변수.Environment variables.

CreateDefaultBuilder는 명령줄 구성 공급자를 마지막에 추가합니다.CreateDefaultBuilder adds the Command-line Configuration Provider last. 따라서 런타임에 전달된 명령줄 인수가 다른 공급자에서 설정한 구성을 재정의합니다.Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder는 호스트를 생성할 때 작동합니다.CreateDefaultBuilder acts when the host is constructed. 따라서 CreateDefaultBuilder에서 활성화한 명령줄 구성이 호스트 생성 방식에 영향을 줄 수 있습니다.Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

ASP.NET Core 템플릿을 기반으로 하는 앱의 경우 AddCommandLineCreateDefaultBuilder에서 이미 호출되었습니다.For apps based on the ASP.NET Core templates, AddCommandLine has already been called by CreateDefaultBuilder. 추가 구성 공급자를 추가하고 명령줄 인수를 사용하여 해당 공급자의 구성을 재정의하는 기능을 유지하려면 ConfigureAppConfiguration에서 앱의 추가 공급자를 호출하고 마지막으로 AddCommandLine을 호출합니다.To add additional configuration providers and maintain the ability to override configuration from those providers with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

예제Example

샘플 앱은 정적 편의 메서드 CreateDefaultBuilder를 활용하여 호스트를 빌드하며, AddCommandLine 호출도 포함합니다.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

  1. 프로젝트의 디렉터리에서 명령 프롬프트를 엽니다.Open a command prompt in the project's directory.
  2. dotnet run 명령에 명령줄 인수를 제공합니다(dotnet run CommandLineKey=CommandLineValue).Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. 앱이 실행되면 브라우저를 열어 http://localhost:5000의 앱으로 이동합니다.After the app is running, open a browser to the app at http://localhost:5000.
  4. dotnet run에 제공한 구성 명령줄 인수에 대한 키-값 쌍이 출력에 포함되어 있는지 확인합니다.Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

인수Arguments

값은 등호(=) 다음에 와야 합니다. 또는 값이 공백 다음에 오는 경우 키에 접두사(-- 또는 /)가 있어야 합니다.The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. 등호를 사용하는 경우 값이 필요하지 않습니다(예: CommandLineKey=).The value isn't required if an equals sign is used (for example, CommandLineKey=).

키 접두사Key prefix 예제Example
접두사 없음No prefix CommandLineKey1=value1
대시 2개(--)Two dashes (--) --CommandLineKey2=value2, --CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
슬래시(/)Forward slash (/) /CommandLineKey3=value3, /CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

같은 명령 내에서 등호를 사용하는 명령줄 인수 키-값 쌍을 공백을 사용하는 키-값 쌍과 함께 사용하지 마세요.Within the same command, don't mix command-line argument key-value pairs that use an equals sign with key-value pairs that use a space.

명령 예:Example commands:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2

스위치 매핑Switch mappings

스위치 매핑은 키 이름 교체 논리를 지원합니다.Switch mappings allow key name replacement logic. ConfigurationBuilder를 사용하여 구성을 수동으로 빌드하는 경우에는 AddCommandLine 메서드에 대체 스위치를 포함하는 사전을 제공하세요.When manually building configuration with a ConfigurationBuilder, 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 (the key replacement) 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:

  • 스위치는 단일 대시(-) 또는 이중 대시(--)로 시작해야 합니다.Switches must start with a dash (-) or double-dash (--).
  • 스위치 매핑 사전이 중복 키를 포함하면 안 됩니다.The switch mappings dictionary must not contain duplicate keys.

스위치 매핑 사전을 만듭니다.Create a switch mappings dictionary. 다음 예에서는 두 개의 스위치 매핑이 만들어집니다.In the following example, two switch mappings are created:

public static readonly Dictionary<string, string> _switchMappings = 
    new Dictionary<string, string>
    {
        { "-CLKey1", "CommandLineKey1" },
        { "-CLKey2", "CommandLineKey2" }
    };

호스트가 빌드될 때 스위치 매핑 사전과 함께 AddCommandLine을 호출합니다.When the host is built, call AddCommandLine with the switch mappings dictionary:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddCommandLine(args, _switchMappings);
})

스위치 매핑을 사용하는 앱의 경우 CreateDefaultBuilder에 대한 호출은 인수를 전달하지 않아야 합니다.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. CreateDefaultBuilder 메서드의 AddCommandLine 호출에는 매핑된 스위치가 포함되지 않으며 CreateDefaultBuilder에 스위치 매핑 사전을 전달할 방법은 없습니다.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. 해결 방법으로 CreateDefaultBuilder에 인수를 전달하지 않고 대신 ConfigurationBuilder 메서드의 AddCommandLine 메서드에서 인수와 스위치 매핑 사전을 모두 처리하도록 할 수 있습니다.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.

생성된 스위치 매핑 사전은 다음 표의 데이터를 포함합니다.After the switch mappings dictionary is created, it contains the data shown in the following table.

KeyKey Value
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

앱을 시작할 때 스위치 매핑된 키가 사용되는 경우 구성은 사전에서 제공하는 키의 구성 값을 수신합니다.If the switch-mapped keys are used when starting the app, configuration receives the configuration value on the key supplied by the dictionary:

dotnet run -CLKey1=value1 -CLKey2=value2

앞의 명령을 실행한 후 구성에는 다음 표에 표시된 값이 포함됩니다.After running the preceding command, configuration contains the values shown in the following table.

KeyKey Value
CommandLineKey1 value1
CommandLineKey2 value2

환경 변수 구성 공급자Environment Variables Configuration Provider

EnvironmentVariablesConfigurationProvider는 런타임에 환경 변수 키-값 쌍에서 구성을 로드합니다.The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

환경 변수 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddEnvironmentVariables 확장 메서드를 호출합니다.To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

: 구분 기호는 모든 플랫폼의 환경 변수 계층적 키에서 작동하지 않습니다.The : separator doesn't work with environment variable hierarchical keys on all platforms. 이중 밑줄 __은 다음과 같습니다.__, the double underscore, is:

  • 모든 플랫폼에서 지원됩니다.Supported by all platforms. 예를 들어 : 구분 기호는 Bash에서 지원되지 않지만 __은 지원됩니다.For example, the : separator is not supported by Bash, but __ is.
  • 자동으로 :으로 대체Automatically replaced by a :

Azure App Service를 사용하면 Azure Portal에서 환경 변수를 설정할 수 있으므로 환경 변수 구성 공급자를 사용한 앱 구성을 재정의할 수 있습니다.Azure App Service permits setting environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. 자세한 내용은 Azure 앱: Azure Portal을 사용하여 앱 구성 재정의 편을 참조하세요.For more information, see Azure Apps: Override app configuration using the Azure Portal.

새 호스트 작성기가 웹 호스트로 초기화되고 CreateDefaultBuilder가 호출될 때 AddEnvironmentVariables호스트 구성에 대해 접두사가 ASPNETCORE_인 환경 변수를 로드하는 데 사용됩니다.AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new host builder is initialized with the Web Host and CreateDefaultBuilder is called. 자세한 내용은 기본 구성 섹션을 참조하세요.For more information, see the Default configuration section.

CreateDefaultBuilder는 다음 항목도 로드합니다.CreateDefaultBuilder also loads:

  • 접두사가 없는 AddEnvironmentVariables의 호출을 통한 접두사가 없는 환경 변수의 앱 구성App configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • appsettings.jsonappsettings.{Environment}.json 파일에서 선택적 구성.Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • 개발 환경의 사용자 비밀.User secrets in the Development environment.
  • 명령줄 인수.Command-line arguments.

사용자 비밀 및 appsettings 파일을 통해 구성을 설정한 후 환경 변수 구성 공급자를 호출합니다.The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. 이 위치에서 공급자를 호출하면 런타임에 환경 변수를 읽어 들여 사용자 비밀 및 appsettings 파일로 설정한 구성을 재정의할 수 있습니다.Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

추가 환경 변수에서 앱 구성을 제공하려면 ConfigureAppConfiguration에서 앱의 추가 공급자를 호출하고 접두사가 있는 AddEnvironmentVariables를 호출합니다.To provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})

지정된 접두사를 포함하는 환경 변수에서 다른 공급자의 값을 재정의할 수 있도록 하려면 AddEnvironmentVariables를 마지막으로 호출합니다.Call AddEnvironmentVariables last to allow environment variables with the given prefix to override values from other providers.

예제Example

샘플 앱은 정적 편의 메서드 CreateDefaultBuilder를 활용하여 호스트를 빌드하며, AddEnvironmentVariables 호출도 포함합니다.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

  1. 샘플 앱을 실행합니다.Run the sample app. 브라우저를 열어 http://localhost:5000의 앱으로 이동합니다.Open a browser to the app at http://localhost:5000.
  2. 환경 변수 ENVIRONMENT에 대한 키-값 쌍이 출력에 포함되는지 확인합니다.Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. 이 값은 앱이 실행 중인 환경을 나타내며, 로컬에서 실행 중이면 일반적으로 Development 입니다.The value reflects the environment in which the app is running, typically Development when running locally.

앱은 렌더링하는 환경 변수 목록을 짧게 유지하기 위해 환경 변수를 필터링합니다.To keep the list of environment variables rendered by the app short, the app filters environment variables. 샘플 앱의 Pages/Index.cshtml.cs 파일을 참조하세요.See the sample app's Pages/Index.cshtml.cs file.

앱에서 사용할 수 있는 모든 환경 변수를 표시하려면 Pages/Index.cshtml.cs 에서 FilteredConfiguration을 다음으로 변경합니다.To expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

접두사Prefixes

AddEnvironmentVariables 메서드에 접두사를 제공하면 앱의 구성에 로드된 환경 변수가 필터링됩니다.Environment variables loaded into the app's configuration are filtered when supplying a prefix to the AddEnvironmentVariables method. 예를 들어 환경 변수를 CUSTOM_ 접두사로 필터링하려면 구성 공급자에 이 접두사를 제공합니다.For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables("CUSTOM_")
    .Build();

구성 키-값 쌍이 생성되면 접두사는 제거됩니다.The prefix is stripped off when the configuration key-value pairs are created.

호스트 작성기를 만들 때 환경 변수에서 호스트 구성을 제공합니다.When the host builder is created, host configuration is provided by environment variables. 환경 변수에 사용되는 접두사에 대한 자세한 내용은 기본 구성 섹션을 참조하세요.For more information on the prefix used for these environment variables, see the Default configuration section.

연결 문자열 접두사Connection string prefixes

구성 API에는 앱 환경에 대한 Azure 연결 문자열 구성과 관련된 네 개의 연결 문자열 환경 변수에 대한 특별한 처리 규칙이 있습니다.The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. 즉, AddEnvironmentVariables에 접두사를 제공하지 않으면 표에 표시된 접두사가 붙은 환경 변수가 앱으로 로드됩니다.Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

연결 문자열 접두사Connection string prefix 공급자Provider
CUSTOMCONNSTR_ 사용자 지정 공급자Custom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Azure SQL DatabaseAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

표에 표시된 네 개 접두사 중 하나가 붙은 환경 변수가 검색되어 구성으로 로드되면 다음과 같이 됩니다.When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • 환경 변수 접두사를 제거하고 구성 키 섹션(ConnectionStrings)을 추가하여 구성 키가 생성됩니다.The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • 데이터베이스 연결 제공자(지정된 공급자가 없는 CUSTOMCONNSTR_ 제외)를 나타내는 새 구성 키-값 쌍이 생성됩니다.A new configuration key-value pair is created that represents the database connection provider (except for 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} 키: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
값: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} 키: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
값: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} 키: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
값: System.Data.SqlClientValue: System.Data.SqlClient

예제Example

서버에 사용자 지정 연결 문자열 환경 변수가 만들어집니다.A custom connection string environment variable is created on the server:

  • 이름: CUSTOMCONNSTR_ReleaseDBName: CUSTOMCONNSTR_ReleaseDB
  • 값: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=TrueValue: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True

IConfiguration이 삽입되고 _config라는 필드에 할당된 경우 값을 읽습니다.If IConfiguration is injected and assigned to a field named _config, read the value:

_config["ConnectionStrings:ReleaseDB"]

파일 구성 공급자File Configuration Provider

FileConfigurationProvider는 파일 시스템에서 구성을 로드하기 위한 기본 클래스입니다.FileConfigurationProvider is the base class for loading configuration from the file system. 다음 구성 공급자는 특정 파일 형식 전용입니다.The following configuration providers are dedicated to specific file types:

INI 구성 공급자INI Configuration Provider

IniConfigurationProvider는 런타임에 INI 파일 키-값 쌍에서 구성을 로드합니다.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

INI 파일 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddIniFile 확장 메서드를 호출합니다.To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

콜론은 INI 파일 구성에서 콜론을 섹션 구분 기호로 사용할 수 있습니다.The colon can be used to as a section delimiter in INI file configuration.

오버로드에서는 다음을 지정할 수 있습니다.Overloads permit specifying:

  • 파일이 선택 사항인지 여부Whether the file is optional.
  • 파일이 변경되면 구성을 다시 로드하는지 여부Whether the configuration is reloaded if the file changes.
  • 파일에 액세스하는 데 사용되는 IFileProviderThe IFileProvider used to access the file.

호스트를 빌드할 때 ConfigureAppConfiguration을 호출하여 앱의 구성을 지정합니다.Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddIniFile(
        "config.ini", optional: true, reloadOnChange: true);
})

INI 구성 파일의 일반적인 예:A generic example of an INI configuration file:

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

이전 구성 파일은 value와 함께 다음 키를 로드합니다.The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:subsection:keysection1:subsection:key
  • section2:subsection0:keysection2:subsection0:key
  • section2:subsection1:keysection2:subsection1:key

JSON 구성 공급자JSON Configuration Provider

JsonConfigurationProvider는 런타임에 JSON 파일 키-값 쌍에서 구성을 로드합니다.The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

JSON 파일 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddJsonFile 확장 메서드를 호출합니다.To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

오버로드에서는 다음을 지정할 수 있습니다.Overloads permit specifying:

  • 파일이 선택 사항인지 여부Whether the file is optional.
  • 파일이 변경되면 구성을 다시 로드하는지 여부Whether the configuration is reloaded if the file changes.
  • 파일에 액세스하는 데 사용되는 IFileProviderThe IFileProvider used to access the file.

CreateDefaultBuilder를 사용하여 새 호스트 작성기를 초기화할 때 AddJsonFile이 자동으로 두 번 호출됩니다.AddJsonFile is automatically called twice when a new host builder is initialized with CreateDefaultBuilder. 이 메서드는 호출되면 다음에서 구성을 로드합니다.The method is called to load configuration from:

  • appsettings.json : 이 파일을 먼저 읽었습니다.appsettings.json: This file is read first. 파일의 환경 버전이 appsettings.json 파일에서 제공한 값을 재정의할 수 있습니다.The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json: 파일의 환경 버전은 IHostingEnvironment.EnvironmentName을 기반으로 합니다.appsettings.{Environment}.json: The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

자세한 내용은 기본 구성 섹션을 참조하세요.For more information, see the Default configuration section.

CreateDefaultBuilder는 다음 항목도 로드합니다.CreateDefaultBuilder also loads:

  • 환경 변수.Environment variables.
  • 개발 환경의 사용자 비밀.User secrets in the Development environment.
  • 명령줄 인수.Command-line arguments.

JSON 구성 공급자를 먼저 설정합니다.The JSON Configuration Provider is established first. 따라서 사용자 비밀, 환경 변수 및 명령줄 인수가 appsettings 파일에서 설정한 구성을 재정의할 수 있습니다.Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

appsettings.jsonappsettings.{Environment}.json 이외의 파일에 대한 앱 구성을 지정하도록 호스트를 빌드할 때 ConfigureAppConfiguration을 호출합니다.Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile(
        "config.json", optional: true, reloadOnChange: true);
})

예제Example

샘플 앱은 정적 편의 메서드 CreateDefaultBuilder를 활용하여 호스트를 빌드하며, AddJsonFile 두 번 호출도 포함합니다.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile:

  • AddJsonFile에 대한 첫 번째 호출은 appsettings.json 에서 구성을 로드합니다.The first call to AddJsonFile loads configuration from appsettings.json:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    
  • AddJsonFile에 대한 두 번째 호출은 appsettings.{Environment}.json 에서 구성을 로드합니다.The second call to AddJsonFile loads configuration from appsettings.{Environment}.json. 샘플 앱의 appsettings.Development.json 의 경우 다음 파일이 로드됩니다.For appsettings.Development.json in the sample app, the following file is loaded:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Debug",
          "System": "Information",
          "Microsoft": "Information"
        }
      }
    }
    
  1. 샘플 앱을 실행합니다.Run the sample app. 브라우저를 열어 http://localhost:5000의 앱으로 이동합니다.Open a browser to the app at http://localhost:5000.
  2. 출력에는 앱 환경을 기반으로 하는 구성에 대한 키 값 쌍이 포함되어 있습니다.The output contains key-value pairs for the configuration based on the app's environment. 개발 환경에서 앱을 실행할 때 Logging:LogLevel:Default 키의 로그 수준은 Debug입니다.The log level for the key Logging:LogLevel:Default is Debug when running the app in the Development environment.
  3. 프로덕션 환경에서 샘플 앱을 다시 실행합니다.Run the sample app again in the Production environment:
    1. Properties/launchSettings.json 파일을 엽니다.Open the Properties/launchSettings.json file.
    2. ConfigurationSample 프로필에서 ASPNETCORE_ENVIRONMENT 환경 변수의 값을 Production으로 변경합니다.In the ConfigurationSample profile, change the value of the ASPNETCORE_ENVIRONMENT environment variable to Production.
    3. 파일을 저장하고 명령 셸에서 dotnet run를 사용하여 앱을 실행합니다.Save the file and run the app with dotnet run in a command shell.
  4. appsettings.Development.json 의 설정에서 더 이상 appsettings.json 의 설정을 재정의하지 않습니다.The settings in the appsettings.Development.json no longer override the settings in appsettings.json. Logging:LogLevel:Default 키의 로그 수준은 Warning입니다.The log level for the key Logging:LogLevel:Default is Warning.

XML 구성 공급자XML Configuration Provider

XmlConfigurationProvider는 런타임에 XML 파일 키-값 쌍에서 구성을 로드합니다.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

XML 파일 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddXmlFile 확장 메서드를 호출합니다.To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

오버로드에서는 다음을 지정할 수 있습니다.Overloads permit specifying:

  • 파일이 선택 사항인지 여부Whether the file is optional.
  • 파일이 변경되면 구성을 다시 로드하는지 여부Whether the configuration is reloaded if the file changes.
  • 파일에 액세스하는 데 사용되는 IFileProviderThe IFileProvider used to access the file.

구성 키-값 쌍이 생성되면 구성 파일의 루트 노드는 무시됩니다.The root node of the configuration file is ignored when the configuration key-value pairs are created. 파일에 DTD(문서 종류 정의)나 네임스페이스는 지정하지 마세요.Don't specify a Document Type Definition (DTD) or namespace in the file.

호스트를 빌드할 때 ConfigureAppConfiguration을 호출하여 앱의 구성을 지정합니다.Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddXmlFile(
        "config.xml", optional: true, reloadOnChange: true);
})

XML 구성 파일에서는 반복 섹션에 고유 요소 이름을 사용할 수 있습니다.XML configuration files can use distinct element names for repeating sections:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section0>
    <key0>value</key0>
    <key1>value</key1>
  </section0>
  <section1>
    <key0>value</key0>
    <key1>value</key1>
  </section1>
</configuration>

이전 구성 파일은 value와 함께 다음 키를 로드합니다.The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

같은 요소 이름을 사용하는 반복 요소는 다음과 같이 name 특성을 사용하여 요소를 구분하면 작동합니다.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</key>
    <key name="key1">value</key>
  </section>
  <section name="section1">
    <key name="key0">value</key>
    <key name="key1">value</key>
  </section>
</configuration>

이전 구성 파일은 value와 함께 다음 키를 로드합니다.The previous configuration file loads the following keys with value:

  • section:section0:key:key0section:section0:key:key0
  • section:section0:key:key1section:section0:key:key1
  • section:section1:key:key0section:section1:key:key0
  • section:section1:key:key1section:section1:key:key1

특성을 사용하여 값을 제공할 수 있습니다.Attributes can be used to supply values:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

이전 구성 파일은 value와 함께 다음 키를 로드합니다.The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

파일별 키 구성 공급자Key-per-file Configuration Provider

KeyPerFileConfigurationProvider는 디렉터리의 파일을 구성 키-값 쌍으로 사용합니다.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. 파일별 키 구성 공급자는 Docker 호스팅 시나리오에서 사용됩니다.The Key-per-file Configuration Provider is used in Docker hosting scenarios.

파일별 키 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddKeyPerFile 확장 메서드를 호출합니다.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. 파일의 directoryPath는 절대 경로여야 합니다.The directoryPath to the files must be an absolute path.

오버로드에서는 다음을 지정할 수 있습니다.Overloads permit specifying:

  • 소스를 구성하는 Action<KeyPerFileConfigurationSource> 대리자An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • 디렉터리가 선택 사항인지 여부와 디렉터리의 경로Whether the directory is optional and the path to the directory.

두 개의 밑줄(__)은 파일 이름에서 구성 키 구분 기호로 사용됩니다.The double-underscore (__) is used as a configuration key delimiter in file names. 예를 들어, 파일 이름 Logging__LogLevel__System은 구성 키 Logging:LogLevel:System을 생성합니다.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

호스트를 빌드할 때 ConfigureAppConfiguration을 호출하여 앱의 구성을 지정합니다.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);
})

메모리 구성 공급자Memory Configuration Provider

MemoryConfigurationProvider는 메모리 내 컬렉션을 구성 키-값 쌍으로 사용합니다.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

메모리 내 컬렉션 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddInMemoryCollection 확장 메서드를 호출합니다.To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

IEnumerable<KeyValuePair<String,String>>을 사용하여 구성 공급자를 초기화할 수 있습니다.The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

호스트를 빌드할 때 ConfigureAppConfiguration을 호출하여 앱의 구성을 지정합니다.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

다음 예제에서는 구성 사전이 만들어집니다.In the following example, a configuration dictionary is created:

public static readonly Dictionary<string, string> _dict = 
    new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

사전은 AddInMemoryCollection을 호출하여 구성을 제공하는 데 사용됩니다.The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddInMemoryCollection(_dict);
})

GetValueGetValue

ConfigurationBinder.GetValue<T>는 지정된 키를 사용하여 구성에서 단일 값을 추출하고 해당 값을 지정된 컬렉션이 아닌 형식으로 변환합니다.ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified noncollection type. 오버로드는 기본값을 허용합니다.An overload accepts a default value.

다음 예제가 하는 일:The following example:

  • NumberKey 키를 사용하여 구성에서 문자열 값을 추출합니다.Extracts the string value from configuration with the key NumberKey. 구성 키에서 NumberKey를 찾을 수 없으면 99의 기본값이 사용됩니다.If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • 값을 int 형식으로 입력합니다.Types the value as an int.
  • 페이지에 사용할 값을 NumberConfig 속성에 저장합니다.Stores the value in the NumberConfig property for use by the page.
public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public int NumberConfig { get; private set; }

    public void OnGet()
    {
        NumberConfig = _config.GetValue<int>("NumberKey", 99);
    }
}

GetSection, GetChildren 및 ExistsGetSection, GetChildren, and Exists

이어지는 예제에서는 다음 JSON 파일을 고려하세요.For the examples that follow, consider the following JSON file. 네 개의 키가 두 개 섹션에 있고, 두 섹션 중 하나에는 하위 섹션 쌍이 포함되어 있습니다.Four keys are found across two sections, one of which includes a pair of subsections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  },
  "section2": {
    "subsection0" : {
      "key0": "value",
      "key1": "value"
    },
    "subsection1" : {
      "key0": "value",
      "key1": "value"
    }
  }
}

파일을 구성으로 읽어 들이면 구성 값을 저장하기 위해 다음과 같은 고유한 계층 키가 생성됩니다.When the file is read into configuration, the following unique hierarchical keys are created to hold the configuration values:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1
  • section2:subsection0:key0section2:subsection0:key0
  • section2:subsection0:key1section2:subsection0:key1
  • section2:subsection1:key0section2:subsection1:key0
  • section2:subsection1:key1section2:subsection1:key1

GetSectionGetSection

IConfiguration.GetSection은 지정된 하위 섹션 키를 사용하여 구성 하위 섹션을 추출합니다.IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.

section1의 키-값 쌍만 포함하는 IConfigurationSection을 반환하려면 GetSection을 호출하고 섹션 이름을 제공합니다.To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

var configSection = _config.GetSection("section1");

configSection에는 값이 포함되지 않고 키 및 경로만 포함됩니다.The configSection doesn't have a value, only a key and a path.

마찬가지로 section2:subsection0의 키 값을 가져오려면 GetSection을 호출하고 섹션 경로를 제공합니다.Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

var configSection = _config.GetSection("section2:subsection0");

GetSectionnull을 반환하지 않습니다.GetSection never returns null. 일치하는 섹션을 찾을 수 없으면 빈 IConfigurationSection이 반환됩니다.If a matching section isn't found, an empty IConfigurationSection is returned.

GetSection이 일치하는 섹션을 반환할 때 Value는 채워지지 않습니다.When GetSection returns a matching section, Value isn't populated. 섹션이 존재하면 KeyPath가 반환됩니다.A Key and Path are returned when the section exists.

GetChildrenGetChildren

section2에서 IConfiguration.GetChildren을 호출하면 다음을 포함하는 IEnumerable<IConfigurationSection>이 반환됩니다.A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

  • subsection0
  • subsection1
var configSection = _config.GetSection("section2");

var children = configSection.GetChildren();

있음Exists

ConfigurationExtensions.Exists를 사용하면 구성 섹션이 있는지 확인할 수 있습니다.Use ConfigurationExtensions.Exists to determine if a configuration section exists:

var sectionExists = _config.GetSection("section2:subsection2").Exists();

예제 데이터의 경우 구성 데이터에 section2:subsection2 섹션이 없으므로 sectionExistsfalse입니다.Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

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

Bind는 전체 POCO 개체 그래프를 바인딩할 수 있습니다.Bind is capable of binding an entire POCO object graph. 단순 개체 바인딩과 마찬가지로 공용 읽기/쓰기 속성만 바인딩되었습니다.As with binding a simple object, only public read/write properties are bound.

다음 샘플은 개체 그래프에MetadataActors 클래스가 포함된 TvShow 모델(Models/TvShow.cs)을 포함합니다.The sample contains a TvShow model whose object graph includes Metadata and Actors classes (Models/TvShow.cs):

public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}

샘플 앱의 tvshow.xml 파일에는 다음 구성 데이터가 포함됩니다.The sample app has a tvshow.xml file containing the configuration data:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>

Bind 메서드를 사용하여 전체 TvShow 개체 그래프에 구성을 바인딩합니다.Configuration is bound to the entire TvShow object graph with the Bind method. 바인딩된 인스턴스는 렌더링할 속성에 할당됩니다.The bound instance is assigned to a property for rendering:

var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;

ConfigurationBinder.Get<T>는 지정된 형식을 바인딩하고 반환합니다.ConfigurationBinder.Get<T> binds and returns the specified type. Get<T>Bind보다 사용하기 더 간편합니다.Get<T> is more convenient than using Bind. 다음 코드는 위의 예제에 Get<T>를 사용하는 방법을 보여 줍니다.The following code shows how to use Get<T> with the preceding example:

TvShow = _config.GetSection("tvshow").Get<TvShow>();

클래스에 배열 바인딩Bind an array to a class

다음 샘플 앱은 이 섹션에서 설명하는 개념을 보여 줍니다.The sample app demonstrates the concepts explained in this section.

Bind는 구성 키에 배열 인덱스를 사용하여 배열을 개체에 바인딩하는 것을 지원합니다.The Bind supports binding arrays to objects using array indices in configuration keys. 숫자 키 세그먼트(:0:, :1:, … :{n}:)를 노출하는 모든 배열 형식은 POCO 클래스 배열에 배열 바인딩할 수 있습니다.Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array.

참고

바인딩은 규칙에 따라 제공됩니다.Binding is provided by convention. 배열 바인딩을 구현하기 위해 사용자 지정 구성 공급자가 필요하지는 않습니다.Custom configuration providers aren't required to implement array binding.

메모리 내 배열 처리In-memory array processing

다음 표에 표시된 구성 키 및 값을 사용하세요.Consider the configuration keys and values shown in the following table.

KeyKey Value
array:entries:0array:entries:0 value0value0
array:entries:1array:entries:1 value1value1
array:entries:2array:entries:2 value2value2
array:entries:4array:entries:4 value4value4
array:entries:5array:entries:5 value5value5

메모리 구성 공급자를 사용하는 샘플 앱에서는 다음과 같은 키 및 값이 로드됩니다.These keys and values are loaded in the sample app using the Memory Configuration Provider:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

배열은 인덱스 #3에 대한 값을 건너뜁니다.The array skips a value for index #3. 구성 바인더는 null 값을 바인딩하거나 바인딩된 개체에 null 항목을 만들 수 없으며, 이 점은 이 배열을 개체에 바인딩한 결과를 설명할 때 명확해집니다.The configuration binder isn't capable of binding null values or creating null entries in bound objects, which becomes clear in a moment when the result of binding this array to an object is demonstrated.

샘플 앱에서는 POCO 클래스를 사용하여 바인딩된 구성 데이터를 저장할 수 있습니다.In the sample app, a POCO class is available to hold the bound configuration data:

public class ArrayExample
{
    public string[] Entries { get; set; }
}

구성 데이터는 개체에 바인딩됩니다.The configuration data is bound to the object:

var arrayExample = new ArrayExample();
_config.GetSection("array").Bind(arrayExample);

ConfigurationBinder.Get<T> 구문을 사용할 수도 있으며, 이 경우 코드가 더 간결해집니다.ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

ArrayExample = _config.GetSection("array").Get<ArrayExample>();

바인딩된 개체 즉, ArrayExample의 인스턴스는 구성에서 배열 데이터를 받습니다.The bound object, an instance of ArrayExample, receives the array data from configuration.

ArrayExample.Entries 인덱스ArrayExample.Entries Index ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value4value4
44 value5value5

바인딩된 개체의 인덱스 #3은 array:4 구성 키에 대한 구성 데이터와 value4의 값을 포함합니다.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 merely used to iterate the configuration data when creating the object. 구성 데이터에 null 값을 유지할 수 없으며, 구성 키의 배열에서 하나 이상의 인덱스를 건너뛰더라도 바인딩된 개체에 null 값 항목이 생성되지 않습니다.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.

인덱스 #3에 대한 누락된 구성 항목은 ArrayExample 인스턴스에 바인딩하기 전에 구성에서 올바른 키-값 쌍을 생성하는 모든 구성 공급자에서 제공할 수 있습니다.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that produces the correct key-value pair in configuration. 샘플에 누락된 키-값 쌍이 있는 추가 JSON 구성 공급자가 포함된 경우 ArrayExample.Entries는 전체 구성 배열과 일치합니다.If the sample included an additional JSON Configuration Provider with the missing key-value pair, the ArrayExample.Entries matches the complete configuration array:

missing_value.json:missing_value.json:

{
  "array:entries:3": "value3"
}

ConfigureAppConfiguration의 경우In ConfigureAppConfiguration:

config.AddJsonFile(
    "missing_value.json", optional: false, reloadOnChange: false);

표에 표시된 키-값 쌍이 구성으로 로드됩니다.The key-value pair shown in the table is loaded into configuration.

KeyKey Value
array:entries:3array:entries:3 value3value3

JSON 구성 공급자에 인덱스 #3에 대한 항목이 포함된 후 ArrayExample 클래스 인스턴스를 바인딩하는 경우 ArrayExample.Entries 배열에 이 값이 포함됩니다.If the ArrayExample class instance is bound after the JSON Configuration Provider includes the entry for index #3, the ArrayExample.Entries array includes the value.

ArrayExample.Entries 인덱스ArrayExample.Entries Index ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

JSON 배열 처리JSON array processing

JSON 파일에 배열이 포함된 경우 0부터 시작하는 섹션 인덱스를 사용하여 배열 요소에 대한 구성 키가 생성됩니다.If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. 다음 구성 파일에서 subsection은 배열입니다.In the following configuration file, subsection is an array:

{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}

JSON 구성 공급자는 구성 데이터를 다음 키-값 쌍으로 읽습니다.The JSON Configuration Provider reads the configuration data into the following key-value pairs:

KeyKey Value
json_array:keyjson_array:key valueAvalueA
json_array:subsection:0json_array:subsection:0 valueBvalueB
json_array:subsection:1json_array:subsection:1 valueCvalueC
json_array:subsection:2json_array:subsection:2 valueDvalueD

샘플 앱에서는 다음 POCO 클래스를 사용하여 구성 키-값 쌍을 바인딩할 수 있습니다.In the sample app, the following POCO class is available to bind the configuration key-value pairs:

public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}

바인딩 후 JsonArrayExample.KeyvalueA 값을 포함합니다.After binding, JsonArrayExample.Key holds the value valueA. 하위 섹션 값은 POCO 배열 속성 Subsection에 저장됩니다.The subsection values are stored in the POCO array property, Subsection.

JsonArrayExample.Subsection 인덱스JsonArrayExample.Subsection Index JsonArrayExample.SubsectionJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

사용자 지정 구성 공급자Custom configuration provider

샘플 앱에서는 EF(Entity Framework)를 사용하여 데이터베이스에서 구성 키-값 쌍을 읽는 기본 구성 공급자를 만드는 방법을 보여 줍니다.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:

  • 데모용으로 EF 메모리 내 데이터베이스를 사용합니다.The EF in-memory database is used for demonstration purposes. 연결 문자열이 필요한 데이터베이스를 사용하려면 보조 ConfigurationBuilder를 구현하여 다른 구성 공급자에서 연결 문자열을 제공하세요.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • 이 공급자는 시작 시 데이터베이스 테이블을 구성으로 읽어 들입니다.The provider reads a database table into configuration at startup. 이 공급자는 키별 기준으로 데이터베이스를 쿼리하지 않습니다.The provider doesn't query the database on a per-key basis.
  • 변경 시 다시 로드가 구현되지 않으므로 앱 시작 후 데이터베이스를 업데이트해도 앱 구성에 영향을 주지 않습니다.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

데이터베이스에 구성 값을 저장하는 EFConfigurationValue 엔터티를 정의합니다.Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

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

구성된 값을 저장 및 액세스하는 EFConfigurationContext를 추가합니다.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

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

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

IConfigurationSource를 구현하는 클래스를 만듭니다.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

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);
    }
}

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

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

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

AddEFConfiguration 확장 메서드를 사용하여 구성 소스를 ConfigurationBuilder에 추가할 수 있습니다.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder, 
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

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

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

시작하는 동안 구성에 액세스Access configuration during startup

Startup.ConfigureServices의 구성 값에 액세스하려면 IConfigurationStartup 생성자에 삽입합니다.Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. Startup.Configure의 구성에 액세스하려면 IConfiguration을 메서드에 직접 삽입하거나 생성자의 인스턴스를 사용합니다.To access configuration in Startup.Configure, either inject IConfiguration directly into the method or use the instance from the constructor:

public class Startup
{
    private readonly IConfiguration _config;

    public Startup(IConfiguration config)
    {
        _config = config;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var value = _config["key"];
    }

    public void Configure(IApplicationBuilder app, IConfiguration config)
    {
        var value = config["key"];
    }
}

시작 편의 메서드를 사용하여 구성에 액세스하는 방법의 예는 앱 시작: 편리한 메서드 편을 참조하세요.For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Razor Pages 페이지 또는 MVC 뷰에서 구성에 액세스Access configuration in a Razor Pages page or MVC view

Razor Pages 페이지나 MVC 뷰에서 구성 설정에 액세스하려면 Microsoft.Extensions.Configuration 네임스페이스using 지시문(C# 참조: using 지시문)을 추가하고 IConfiguration을 페이지 또는 뷰로 삽입합니다.To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.

Razor Pages 페이지에서 다음을 수행합니다.In a Razor Pages page:

@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index Page</title>
</head>
<body>
    <h1>Access configuration in a Razor Pages page</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

MVC 뷰에서:In an MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index View</title>
</head>
<body>
    <h1>Access configuration in an MVC view</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

외부 어셈블리의 구성 추가Add configuration from an external assembly

IHostingStartup 구현은 시작 시 앱의 Startup 클래스 외부에 있는 외부 어셈블리에서 앱에 향상된 기능을 추가할 수 있습니다.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. 자세한 내용은 ASP.NET Core에서 호스팅 시작 어셈블리 사용를 참조하세요.For more information, see ASP.NET Core에서 호스팅 시작 어셈블리 사용.

추가 자료Additional resources