.NET의 구성 공급자

.NET에서 구성은 구성 공급자를 사용하여 수행할 수 있습니다. 여러 유형의 공급자는 다양한 구성 원본을 사용합니다. 이 문서에서는 모든 다양한 구성 공급자와 해당 소스를 자세히 설명합니다.

• 파일 구성 공급자
• 환경 변수 구성 공급자
• 명령줄 구성 공급자
• 파일별 키 구성 공급자
• 메모리 구성 공급자

파일 구성 공급자

FileConfigurationProvider는 파일 시스템에서 구성을 로드하기 위한 기본 클래스입니다. 다음 구성 공급자는 FileConfigurationProvider에서 파생됩니다.

• JSON 구성 공급자
• XML 구성 공급자
• INI 구성 공급자

키는 대/소문자를 구분하지 않습니다. 모든 파일 구성 공급자는 단일 공급자에서 중복 키를 찾을 때 FormatException을 throw합니다.

JSON 구성 공급자

JsonConfigurationProvider 클래스는 JSON 파일에서 구성을 로드합니다. Microsoft.Extensions.Configuration.Json NuGet 패키지를 설치합니다.

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

• 파일이 선택 사항인지 여부
• 파일이 변경되면 구성을 다시 로드하는지 여부

다음 코드를 생각해 봅시다.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ConsoleJson.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

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

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

앞의 코드가 하는 역할은 다음과 같습니다.

• CreateApplicationBuilder(String[]) 메서드에 기본적으로 추가된 기존 구성 공급자를 모두 지웁니다.
• 다음 옵션을 사용하여 appsettings.json 및 appsettings.Environment.json 파일을 로드하도록 JSON 구성 공급자를 구성합니다.
  • optional: true: 파일은 선택 사항입니다.
  • reloadOnChange: true: 변경 내용이 저장되면 파일이 다시 로드됩니다.

Important

IConfigurationBuilder.Add로 구성 공급자를 추가할 때 추가된 구성 공급자가 IConfigurationSource 목록의 끝에 추가됩니다. 여러 공급자가 키를 찾은 경우 키를 읽는 마지막 공급자가 이전 공급자를 재정의합니다.

다양한 구성 설정을 사용하는 예제 appsettings.json 파일은 다음과 같습니다.

{
    "SecretKey": "Secret key value",
    "TransientFaultHandlingOptions": {
        "Enabled": true,
        "AutoRetryDelay": "00:00:07"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    }
}

구성 공급자가 추가된 후 IConfigurationBuilder 인스턴스에서 IConfigurationBuilder.Build()를 호출하여 IConfigurationRoot 개체를 가져올 수 있습니다. 구성 루트는 구성 계층 구조의 루트를 나타냅니다. 구성의 섹션은 .NET 개체의 인스턴스에 바인딩되고 나중에 IOptions<TOptions> 종속성 주입을 통해 제공될 수 있습니다.

참고 항목

JSON 파일의 빌드 작업 및 출력 디렉터리에 복사 속성을 각각 콘텐츠 및 새 버전이면 복사(또는 항상 복사)로 설정해야 합니다.

다음과 같이 정의된 TransientFaultHandlingOptions 클래스를 고려하세요.

namespace ConsoleJson.Example;

public sealed class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

다음 코드는 구성 루트를 빌드하고, 섹션을 TransientFaultHandlingOptions 클래스 형식에 바인딩하고, 바인딩된 값을 콘솔 창에 출력합니다.

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

애플리케이션은 다음 샘플 출력을 씁니다.

// Sample output:
//    TransientFaultHandlingOptions.Enabled=True
//    TransientFaultHandlingOptions.AutoRetryDelay=00:00:07

XML 구성 공급자

XmlConfigurationProvider 클래스는 런타임에 있는 XML 파일에서 구성을 로드합니다. Microsoft.Extensions.Configuration.Xml NuGet 패키지를 설치합니다.

다음 코드에서는 XML 구성 공급자를 사용한 XML 파일의 구성을 보여 줍니다.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

builder.Configuration
    .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
    .AddXmlFile("repeating-example.xml", optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();

if (args is { Length: > 0 })
{
    builder.Configuration.AddCommandLine(args);
}

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

앞의 코드가 하는 역할은 다음과 같습니다.

• CreateApplicationBuilder(String[]) 메서드에 기본적으로 추가된 기존 구성 공급자를 모두 지웁니다.
• 다음 옵션을 사용하여 appsettings.xml 및 repeating-example.xml 파일을 로드하도록 XML 구성 공급자를 구성합니다.
  • optional: true: 파일은 선택 사항입니다.
  • reloadOnChange: true: 변경 내용이 저장되면 파일이 다시 로드됩니다.
• 환경 변수 구성 공급자를 구성합니다.
• 지정된 args에 인수가 포함된 경우 명령줄 구성 공급자를 구성합니다.

XML 설정은 환경 변수 구성 공급자 및 명령줄 구성 공급자의 설정에 따라 재정의됩니다.

다양한 구성 설정을 사용하는 예제 appsettings.xml 파일은 다음과 같습니다.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <SecretKey>Secret key value</SecretKey>
  <TransientFaultHandlingOptions>
    <Enabled>true</Enabled>
    <AutoRetryDelay>00:00:07</AutoRetryDelay>
  </TransientFaultHandlingOptions>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

팁

WinForms 앱에서 IConfiguration 형식을 사용하려면 Microsoft.Extensions.Configuration.Xml NuGet 패키지에 대한 참조를 추가합니다. ConfigurationBuilder를 인스턴스화하고 AddXmlFile 및 Build()에 대한 호출을 연결합니다. 자세한 내용은 .NET Docs 이슈 #29679를 참조하세요.

.NET 5 이하 버전에서는 동일한 요소 이름을 사용하는 반복 요소를 구분하는 name 특성을 추가합니다. .NET 6 이상 버전에서 XML 구성 공급자는 반복 요소를 자동으로 인덱싱합니다. 즉, 키에 "0" 인덱스를 사용하고 요소가 하나만 있는 경우를 제외하고는 name 특성을 지정할 필요가 없습니다. (.NET 6 이상으로 업그레이드하는 경우 이 동작 변경으로 인해 중단이 발생할 수 있습니다. 자세한 내용은 반복 XML 요소에 인덱스 포함을 참조하세요.)

<?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>

다음 코드는 이전 구성 파일을 읽고 키 및 값을 표시합니다.

IConfigurationRoot configurationRoot = builder.Configuration;

string key00 = "section:section0:key:key0";
string key01 = "section:section0:key:key1";
string key10 = "section:section1:key:key0";
string key11 = "section:section1:key:key1";

string? val00 = configurationRoot[key00];
string? val01 = configurationRoot[key01];
string? val10 = configurationRoot[key10];
string? val11 = configurationRoot[key11];

Console.WriteLine($"{key00} = {val00}");
Console.WriteLine($"{key01} = {val01}");
Console.WriteLine($"{key10} = {val10}");
Console.WriteLine($"{key10} = {val11}");

애플리케이션은 다음 샘플 출력을 작성합니다.

// Sample output:
//    section:section0:key:key0 = value 00
//    section:section0:key:key1 = value 01
//    section:section1:key:key0 = value 10
//    section:section1:key:key0 = value 11

특성을 사용하여 값을 제공할 수 있습니다.

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

이전 구성 파일은 value와 함께 다음 키를 로드합니다.

• key:attribute
• section:key:attribute

INI 구성 공급자

IniConfigurationProvider 클래스는 런타임에 있는 INI 파일에서 구성을 로드합니다. Microsoft.Extensions.Configuration.Ini NuGet 패키지를 설치합니다.

다음 코드는 모든 구성 공급자를 지우고 두 개의 INI 파일을 소스로 사용하여 IniConfigurationProvider를 추가합니다.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddIniFile("appsettings.ini", optional: true, reloadOnChange: true)
    .AddIniFile($"appsettings.{env.EnvironmentName}.ini", true, true);

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

다양한 구성 설정을 사용하는 예제 appsettings.ini 파일은 다음과 같습니다.

SecretKey="Secret key value"

[TransientFaultHandlingOptions]
Enabled=True
AutoRetryDelay="00:00:07"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

다음 코드는 이전 구성 설정을 콘솔 창에 기록하여 표시합니다.

foreach ((string key, string? value) in
    builder.Configuration.AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

애플리케이션은 다음 샘플 출력을 작성합니다.

// Sample output:
//    TransientFaultHandlingOptions:Enabled=True
//    TransientFaultHandlingOptions:AutoRetryDelay=00:00:07
//    SecretKey=Secret key value
//    Logging:LogLevel:Microsoft=Warning
//    Logging:LogLevel:Default=Information

환경 변수 구성 공급자

기본 구성을 사용하여 EnvironmentVariablesConfigurationProvider는 appsettings.json, appsettings.Environment.json, 비밀 관리자를 읽은 후 환경 변수 키-값 쌍에서 구성을 로드합니다. 따라서 환경에서 읽은 키 값이 appsettings.json, appsettings.Environment.json 및 비밀 관리자에서 읽은 값을 재정의합니다.

: 구분 기호는 모든 플랫폼의 환경 변수 계층적 키에서 작동하지 않습니다. 예를 들어 : 구분 기호는 Bash에서 지원되지 않습니다. 모든 플랫폼에서 지원되는 이중 밑줄(__)은 환경 변수의 모든 : 구분 기호를 자동으로 바꿉니다.

TransientFaultHandlingOptions 클래스를 살펴보겠습니다.

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

다음 set 명령은 SecretKey 및 TransientFaultHandlingOptions의 환경 키와 값을 설정합니다.

set SecretKey="Secret key from environment"
set TransientFaultHandlingOptions__Enabled="true"
set TransientFaultHandlingOptions__AutoRetryDelay="00:00:13"

이러한 환경 설정은 설정된 명령 창에서 시작된 프로세스에서만 설정됩니다. Visual Studio에서 시작된 웹앱에서는 읽지 않습니다.

Visual Studio 2019 이상에서는 시작 프로필 대화 상자를 사용하여 환경 변수를 지정할 수 있습니다.

다음 setx 명령을 사용하여 Windows에서 환경 키 및 값을 설정할 수 있습니다. set와 달리, setx 설정은 유지됩니다. /M은 시스템 환경에서 변수를 설정합니다. /M 스위치를 사용하지 않으면 사용자 환경 변수가 설정됩니다.

setx SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

이전 명령이 apsettings.json 및 appsettings.Environmentjson 설정을 재정의하는지 테스트하려면:

• Visual Studio 사용: Visual Studio를 종료하고 다시 시작합니다.
• CLI 사용: 새 명령 창을 시작하고 dotnet run을 입력합니다.

접두사

환경 변수에 대한 접두사를 지정하려면 문자열을 사용하여 AddEnvironmentVariables를 호출합니다.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddEnvironmentVariables(prefix: "CustomPrefix_");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

위의 코드에서

• config.AddEnvironmentVariables(prefix: "CustomPrefix_")는 기본 구성 공급자 뒤에 추가됩니다. 구성 공급자 순서 지정 예제는 XML 구성 공급자를 참조하세요.
• CustomPrefix_ 접두사를 사용하여 설정된 환경 변수는 기본 구성 공급자를 재정의합니다. 여기에는 접두사 없는 환경 변수가 포함됩니다.

구성 키-값 쌍을 읽으면 접두사는 제거됩니다.

기본 구성은 DOTNET_ 접두사가 붙은 환경 변수 및 명령줄 인수를 로드합니다. DOTNET_ 접두사는 .NET에서 호스트 및 앱 구성에 사용되지만 사용자 구성에는 사용되지 않습니다.

호스트 및 앱 구성에 대한 자세한 내용은 .NET 제네릭 호스트를 참조하세요.

연결 문자열 접두사

구성 API에는 네 개의 연결 문자열 환경 변수에 대한 특별한 처리 규칙이 있습니다. 해당 연결 문자열은 앱 환경의 Azure 연결 문자열을 구성하는 데 관련됩니다. 기본 구성을 사용하거나 AddEnvironmentVariables에 제공된 접두사가 없는 경우 표에 표시된 접두사가 붙은 환경 변수가 앱에 로드됩니다.

연결 문자열 접두사	공급자
CUSTOMCONNSTR_	사용자 지정 공급자
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Azure SQL Database
SQLCONNSTR_	SQL Server

표에 표시된 네 개 접두사 중 하나가 붙은 환경 변수가 검색되어 구성으로 로드되면 다음과 같이 됩니다.

• 환경 변수 접두사를 제거하고 구성 키 섹션(ConnectionStrings)을 추가하여 구성 키가 생성됩니다.
• 데이터베이스 연결 제공자(지정된 공급자가 없는 CUSTOMCONNSTR_ 제외)를 나타내는 새 구성 키-값 쌍이 생성됩니다.

환경 변수 키	변환된 구성 키	공급자 구성 항목
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	구성 항목이 생성되지 않습니다.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	키: ConnectionStrings:{KEY}_ProviderName: 값: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	키: ConnectionStrings:{KEY}_ProviderName: 값: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	키: ConnectionStrings:{KEY}_ProviderName: 값: System.Data.SqlClient

Important

사용 가능한 가장 안전한 인증 흐름을 사용하는 것이 권장됩니다. Azure SQL에 연결하려는 경우, 권장되는 인증 방법은 Azure 리소스에 대한 관리 ID입니다.

launchSettings.json에 설정된 환경 변수

launchSettings.json에 설정된 환경 변수는 시스템 환경에 설정된 변수를 재정의합니다.

Azure App Service 설정

Azure App Service의 설정>구성 페이지에서 새 애플리케이션 설정을 선택합니다. Azure App Service 애플리케이션 설정은,

• 미사용 시 암호화되고 암호화된 채널을 통해 전송됩니다.
• 환경 변수로 노출됩니다.

명령줄 구성 공급자

기본 구성을 사용하여 CommandLineConfigurationProvider는 다음 구성 소스 뒤에 명령줄 인수 키-값 쌍에서 구성을 로드합니다.

• appsettings.json 및 appsettings.Environment.json 파일
• Development 발 환경의 앱 비밀(비밀 관리자)
• 환경 변수입니다.

기본적으로 명령줄에 설정된 구성 값은 다른 모든 구성 공급자를 사용하여 설정된 구성 값을 재정의합니다.

Visual Studio 2019 이상에서는 시작 프로필 대화 상자를 사용하여 명령줄 인수를 지정할 수 있습니다.

명령줄 인수

다음 명령은 =를 사용하여 키 및 값을 설정합니다.

dotnet run SecretKey="Secret key from command line"

다음 명령은 /를 사용하여 키 및 값을 설정합니다.

dotnet run /SecretKey "Secret key set from forward slash"

다음 명령은 --를 사용하여 키 및 값을 설정합니다.

dotnet run --SecretKey "Secret key set from double hyphen"

키 값은,

• = 다음에 와야 합니다. 또는 값이 공백에 다음에 오는 경우 키에 -- 또는 / 접두사가 있어야 합니다.
• =이 사용된 경우 필요하지 않습니다. 예: SomeKey=.

같은 명령 내에서 =을 사용하는 명령줄 인수 키-값 쌍을 공백을 사용하는 키-값 쌍과 함께 사용하지 마세요.

파일별 키 구성 공급자

KeyPerFileConfigurationProvider는 디렉터리의 파일을 구성 키-값 쌍으로 사용합니다. 키는 파일 이름이고, 값은 파일의 콘텐츠입니다. 파일별 키 구성 공급자는 Docker 호스팅 시나리오에서 사용됩니다.

파일별 키 구성을 활성화하려면 ConfigurationBuilder 인스턴스에서 AddKeyPerFile 확장 메서드를 호출합니다. 파일의 directoryPath는 절대 경로여야 합니다.

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

• 소스를 구성하는 Action<KeyPerFileConfigurationSource> 대리자
• 디렉터리가 선택 사항인지 여부와 디렉터리의 경로

두 개의 밑줄(__)은 파일 이름에서 구성 키 구분 기호로 사용됩니다. 예를 들어, 파일 이름 Logging__LogLevel__System은 구성 키 Logging:LogLevel:System을 생성합니다.

호스트를 빌드할 때 ConfigureAppConfiguration을 호출하여 앱의 구성을 지정합니다.

.ConfigureAppConfiguration((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.AddKeyPerFile(directoryPath: path, optional: true);
})

메모리 구성 공급자

MemoryConfigurationProvider는 메모리 내 컬렉션을 구성 키-값 쌍으로 사용합니다.

다음 코드는 구성 시스템에 메모리 컬렉션을 추가합니다.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["SecretKey"] = "Dictionary MyKey Value",
        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
        ["Logging:LogLevel:Default"] = "Warning"
    });

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

이전 코드에서 MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>)은 기본 구성 공급자 뒤에 메모리 공급자를 추가합니다. 구성 공급자 순서 지정 예제는 XML 구성 공급자를 참조하세요.

참고 항목

• .NET의 구성
• .NET 일반 호스트
• 사용자 지정 구성 공급자 구현