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

Luke Latham으로By Luke Latham

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)는 프레임워크에 의해 암시적으로 포함됩니다.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included implicitly by the framework.

일반적인 구성 공급자 시나리오에 대한 구성 패키지(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 기본 사항.

기본 구성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 Generic Host. 웹 호스트를 사용하는 경우 기본 구성에 대한 자세한 내용은 이 항목의 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.
  • 앱 구성은 다음에 의해 제공됩니다.App configuration is provided from:

호스트를 빌드할 때 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:

  • ASP.NET Core에서 여러 환경 사용
  • ASP.NET Core 개발 시 앱 비밀의 안전한 저장 – 환경 변수를 사용하여 중요한 데이터를 저장하는 방법에 대한 조언을 포함합니다.ASP.NET Core 개발 시 앱 비밀의 안전한 저장 – Includes advice on using environment variables to store sensitive data. 비밀 관리자는 파일 구성 공급자를 사용하여 사용자 비밀을 로컬 시스템의 JSON 파일에 저장합니다.The Secret Manager uses the File Configuration Provider to store user secrets in a JSON file on the local system. 파일 구성 공급자에 대해서는 이 항목의 뒷부분에서 설명합니다.The File Configuration Provider is described later in this topic.

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에 삽입하여 클래스에 대한 구성을 가져올 수 있습니다.IConfiguration can be injected into a Razor Pages PageModel to obtain configuration for the class:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

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

    // The _config local variable is used to obtain configuration 
    // throughout the class.
}

구성 공급자는 호스트에서 설정될 때 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.
  • 계층적 키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. 비밀을 앱의 구성으로 로드할 때 대시를 콜론으로 바꾸는 코드를 제공해야 합니다.You must provide 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 (Secret Manager) (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 your code may arrange them. 코드에서는 기본 구성 소스에 대한 우선 순위에 맞게 구성 공급자를 정렬하세요.Order configuration providers in your code to suit your priorities for the underlying configuration sources.

구성 공급자의 일반적인 순서는 다음과 같습니다.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 (Secret Manager) (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 you initialize a new host builder with CreateDefaultBuilder. 자세한 내용은 기본 구성 섹션을 참조하세요.For more information, see the Default configuration section.

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

호스트 작성기를 구성하려면 ConfigureHostConfiguration을 호출하고 구성을 제공합니다.To configure the host builder, call ConfigureHostConfiguration and supply the configuration. ConfigureHostConfiguration은 나중에 빌드 프로세스에서 사용하기 위해 IHostEnvironment를 초기화하는 데 사용됩니다.ConfigureHostConfiguration is used to initialize the IHostEnvironment for use later in the build process. ConfigureHostConfiguration 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다.ConfigureHostConfiguration can be called multiple times with additive results.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureHostConfiguration(config =>
        {
            var dict = new Dictionary<string, string>
            {
                {"MemoryCollectionKey1", "value1"},
                {"MemoryCollectionKey2", "value2"}
            };

            config.AddInMemoryCollection(dict);
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
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 (Secret Manager) 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 you manually build configuration with a ConfigurationBuilder, you can 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.

환경 변수에서 계층적 키를 사용할 경우 일부 플랫폼에서 콜론 구분 기호(:)가 작동하지 않을 수 있습니다(예: Bash).When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms (for example, Bash). 두 개의 밑줄(__)은 모든 플랫폼에서 지원되며 콜론으로 자동으로 바뀝니다.A double underscore (__) is supported by all platforms and is automatically replaced by a colon.

Azure App Service를 사용하면 Azure Portal에서 환경 변수를 설정할 수 있으므로 환경 변수 구성 공급자를 사용한 앱 구성을 재정의할 수 있습니다.Azure App Service permits you to set 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호스트 구성에 대해 접두사가 DOTNET_인 환경 변수를 로드하는 데 사용됩니다.AddEnvironmentVariables is used to load environment variables prefixed with DOTNET_ for host configuration when a new host builder is initialized with the Generic Host and CreateDefaultBuilder is called. 자세한 내용은 기본 구성 섹션을 참조하세요.For more information, see the Default configuration section.

새 호스트 작성기가 웹 호스트로 초기화되고 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 (Secret Manager) 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를 호출합니다.If you need 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) =>
{
    // Call additional providers here as needed.
    // Call AddEnvironmentVariables last if you need to allow
    // environment variables to override values from other 
    // providers.
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})
}

예제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을 다음으로 변경합니다.If you wish 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 you supply 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

파일 구성 공급자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 you initialize a new host builder 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:

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. 구성은 appsettings.jsonappsettings.{Environment}.json에서 로드됩니다.Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

  1. 샘플 앱을 실행합니다.Run the sample app. 브라우저를 열어 http://localhost:5000의 앱으로 이동합니다.Open a browser to the app at http://localhost:5000.
  2. 표에 표시된 대로 환경에 따라 다른 구성에 대한 키-값 쌍이 출력에 포함되어 있는지 확인합니다.Observe that the output contains key-value pairs for the configuration shown in the table depending on the environment. 로깅 구성 키는 콜론(:)을 계층 구분 기호로 사용합니다.Logging configuration keys use the colon (:) as a hierarchical separator.
KeyKey 개발 값Development Value 프로덕션 값Production Value
Logging:LogLevel:SystemLogging:LogLevel:System 정보Information 정보Information
Logging:LogLevel:MicrosoftLogging:LogLevel:Microsoft 정보Information 정보Information
Logging:LogLevel:DefaultLogging:LogLevel:Default DebugDebug ErrorError
AllowedHostsAllowedHosts * *

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 a class

‘옵션 패턴’을 사용하여 관련 설정 그룹을 나타내는 클래스에 구성을 바인딩할 수 있습니다. Configuration can be bound to classes that represent groups of related settings using the options pattern. 자세한 내용은 ASP.NET Core의 옵션 패턴을 참조하세요.For more information, see ASP.NET Core의 옵션 패턴.

구성 값이 문자열로 반환되지만, Bind를 호출하면 POCO 개체를 생성할 수 있습니다.Configuration values are returned as strings, but calling Bind enables the construction of POCO objects.

샘플 앱은 Starship 모델(Models/Starship.cs)을 포함합니다.The sample app contains a Starship model (Models/Starship.cs):

public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}
public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}

샘플 앱이 JSON 구성 공급자를 사용하여 구성을 로드하는 경우 starship.json 파일의 starship 섹션에서 구성을 생성합니다.The starship section of the starship.json file creates the configuration when the sample app uses the JSON Configuration Provider to load the configuration:

{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}
{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}

다음 구성 키-값 쌍이 생성됩니다.The following configuration key-value pairs are created:

KeyKey Value
starship:namestarship:name USS EnterpriseUSS Enterprise
starship:registrystarship:registry NCC-1701NCC-1701
starship:classstarship:class ConstitutionConstitution
starship:lengthstarship:length 304.8304.8
starship:commissionedstarship:commissioned FalseFalse
trademarktrademark Paramount Pictures Corp. https://www.paramount.comParamount Pictures Corp. https://www.paramount.com

샘플 앱은 starship 키를 사용하여 GetSection을 호출합니다.The sample app calls GetSection with the starship key. starship 키-값 쌍은 격리됩니다.The starship key-value pairs are isolated. Bind 메서드는 Starship 클래스의 인스턴스를 전달하는 하위 섹션에서 호출됩니다.The Bind method is called on the subsection passing in an instance of the Starship class. 인스턴스 값을 바인딩한 후 인스턴스는 렌더링할 속성에 할당됩니다.After binding the instance values, the instance is assigned to a property for rendering:

var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;
var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;

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

Bind는 전체 POCO 개체 그래프를 바인딩할 수 있습니다.Bind is capable of binding an entire POCO object graph.

다음 샘플은 개체 그래프에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; }
}
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>
<?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, which allows the bound instance to be directly assigned to the property used for rendering:

TvShow = _config.GetSection("tvshow").Get<TvShow>();
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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
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; }
}
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 = _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_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; }
}
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. 구성 키는 대/소문자를구분하지 않으므로 데이터베이스를 초기화하는 데 사용되는 사전은 대/소문자를 구분하지 않는 비교자(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:

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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

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 페이지에서: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