.NET 런타임 구성 설정

  • 아티클

.NET 5+(.NET Core 버전 포함)는 구성 파일 및 환경 변수를 사용하여 .NET 애플리케이션의 동작을 구성할 수 있도록 지원합니다.

참고 항목

이 섹션의 문서는 .NET 런타임 자체의 구성에 대해 설명합니다. .NET Core 3.1 이상으로 마이그레이션하고 app.config 파일을 대체하려는 경우 또는 .NET 앱에서 사용자 지정 구성 값을 사용하는 방법을 원하는 경우 .NET에서 Microsoft.Extensions.Configuration.ConfigurationBuilder클래스 및구성을 참조하세요.

다음과 같은 경우 이러한 설정을 사용하는 것이 매력적인 옵션입니다.

  • 애플리케이션의 소스 코드를 소유하거나 제어하지 않으므로 프로그래밍 방식으로 해당 소스 코드를 구성할 수 없습니다.
  • 애플리케이션의 여러 인스턴스가 단일 시스템에서 동시에 실행되며 최적의 성능을 위해 각 인스턴스를 구성하려고 합니다.

.NET은 .NET 런타임의 동작을 구성하기 위한 다음 메커니즘을 제공합니다.

팁

환경 변수를 사용하여 옵션을 구성하면 설정이 모든 .NET 앱에 적용됩니다. runtimeconfig.json 또는 프로젝트 파일에서 옵션을 구성하면 해당 애플리케이션에만 설정이 적용됩니다.

일부 구성 값은 AppContext.SetSwitch 메서드를 호출하여 프로그래밍 방식으로 설정할 수도 있습니다.

설명서의 이 섹션에 있는 문서는 디버깅 및 가비지 수집 등의 범주별로 구성되어 있습니다. 해당하는 경우 .NET Framework 프로젝트의 runtimeconfig.json 파일, MSBuild 속성, 환경 변수 그리고 상호 참조의 경우 app.config 파일에 대한 구성 옵션이 표시됩니다.

runtimeconfig.json

프로젝트가 빌드되면 [앱 이름].runtimeconfig.json 파일이 출력 디렉터리에 생성됩니다. runtimeconfig.template.json 파일이 프로젝트 파일과 같은 폴더에 있으면 포함된 모든 구성 옵션이 [앱 이름].runtimeconfig.json 파일에 삽입됩니다. 앱을 직접 빌드하는 경우 runtimeconfig.template.json 파일에 구성 옵션을 배치합니다. 앱을 실행만 하는 경우에는 [앱 이름].runtimeconfig.json 파일에 직접 삽입합니다.

참고 항목

  • 그러면 [앱 이름].runtimeconfig.json 파일이 다음 번 빌드에서 덮어쓰입니다.
  • 앱의 OutputType이 Exe가 아니고 구성 옵션을 runtimeconfig.template.json에서 [appname].runtimeconfig.json으로 복사하려면 프로젝트 파일에서 GenerateRuntimeConfigurationFiles를 true로 명시적으로 설정해야 합니다. runtimeconfig.json 파일이 필요한 앱의 경우 이 속성은 기본적으로 true로 설정됩니다.

runtimeconfig.json 또는 runtimeconfig.template.json 파일의 configProperties 섹션에서 런타임 구성 옵션을 지정합니다. 이 섹션은 형식은 다음과 같습니다.

"configProperties": {
  "config-property-name1": "config-value1",
  "config-property-name2": "config-value2"
}

예: [앱 이름].runtimeconfig.template.json 파일

출력 JSON 파일에 옵션을 배치하는 경우 runtimeOptions 속성 아래에 중첩합니다.

{
  "runtimeOptions": {
    "tfm": "netcoreapp3.1",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "3.1.0"
    },
    "configProperties": {
      "System.Globalization.UseNls": true,
      "System.Net.DisableIPv6": true,
      "System.GC.Concurrent": false,
      "System.Threading.ThreadPool.MinThreads": 4,
      "System.Threading.ThreadPool.MaxThreads": 25
    }
  }
}

예: runtimeconfig.template.json 파일

템플릿 JSON 파일에 옵션을 배치하는 경우 runtimeOptions 속성을 생략합니다.

{
  "configProperties": {
    "System.Globalization.UseNls": true,
    "System.Net.DisableIPv6": true,
    "System.GC.Concurrent": false,
    "System.Threading.ThreadPool.MinThreads": "4",
    "System.Threading.ThreadPool.MaxThreads": "25"
  }
}

MSBuild 속성

일부 런타임 구성 옵션은 SDK 스타일 .NET 프로젝트의 .csproj 또는 .vbproj 파일에서 MSBuild 속성을 사용하여 설정할 수 있습니다. MSBuild 속성은 runtimeconfig.template.json 파일에 설정된 옵션보다 우선적으로 적용됩니다.

특정 MSBuild 속성이 없는 런타임 구성 설정의 경우 RuntimeHostConfigurationOption MSBuild 항목을 대신 사용할 수 있습니다. runtimeconfig.json 설정 이름을 Include 특성 값으로 사용합니다.

다음은 .NET 런타임의 동작을 구성하기 위한 MSBuild 속성이 있는 SDK 스타일 프로젝트 파일의 예입니다.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
    <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
    <ThreadPoolMaxThreads>25</ThreadPoolMaxThreads>
  </PropertyGroup>

  <ItemGroup>
    <RuntimeHostConfigurationOption Include="System.Globalization.UseNls" Value="true" />
    <RuntimeHostConfigurationOption Include="System.Net.DisableIPv6" Value="true" />
  </ItemGroup>

</Project>

런타임의 동작을 구성하기 위한 MSBuild 속성은 각 영역에 대한 개별 문서(예: 가비지 수집)에 나와 있습니다. 또한 SDK 스타일 프로젝트에 대한 MSBuild 속성 참조의 런타임 구성 섹션에 나열됩니다.

환경 변수

환경 변수를 사용하여 일부 런타임 구성 정보를 제공할 수 있습니다. 환경 변수로 지정된 구성 노브는 일반적으로 DOTNET_ 접두사가 붙어 있습니다.

참고 항목

.NET 6은 .NET 런타임 동작을 구성하는 환경 변수에 대해 COMPlus_ 대신 접두사 DOTNET_을 표준화합니다. 그러나 COMPlus_ 접두사도 계속 작동합니다. 이전 버전의 .NET 런타임을 사용하는 경우에도 환경 변수에 COMPlus_ 접두사를 사용해야 합니다.

Windows 제어판, 명령줄 또는 Windows 및 Unix 기반 시스템에서 Environment.SetEnvironmentVariable(String, String) 메서드를 호출하여 프로그래밍 방식으로 환경 변수를 정의할 수 있습니다.

다음 예제는 명령줄에서 환경 변수를 설정하는 방법을 보여 줍니다.

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

참고 항목