.NET 런타임 구성 설정

2025-06-17

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

메커니즘	비고
runtimeconfig.json 파일	특정 앱에 설정을 적용합니다. 앱의 여러 인스턴스가 단일 시스템에서 동시에 실행되고 최적의 성능을 위해 각각을 구성하려는 경우 이 파일을 사용합니다.
MSBuild 속성	특정 앱에 설정을 적용합니다. MSBuild 속성은 runtimeconfig.json 설정보다 우선합니다.
환경 변수	모든 .NET 앱에 설정을 적용합니다.

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

비고

이 섹션의 문서는 .NET 런타임 자체의 구성에 대해 설명합니다. .NET Framework에서 .NET으로 앱을 마이그레이션하고 app.config 파일을 대체하려는 경우 .NET으로 업그레이드한 후 현대화를 참조하세요. .NET 앱에 사용자 지정 구성 값을 제공하는 방법에 대한 자세한 내용은 .NET의 구성을 참조하세요.

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

runtimeconfig.json

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

비고

[appname].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"
}

예제 [appname].runtimeconfig.json 파일

출력 JSON 파일에 옵션을 배치하는 경우, 옵션을 runtimeOptions 속성 아래에 배치하세요.

{
  "runtimeOptions": {
    "tfm": "net8.0",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "8.0.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 속성이 없는 런타임 구성 설정의 경우 MSBuild 항목을 대신 사용할 RuntimeHostConfigurationOption 수 있습니다. runtimeconfig.json 설정 이름을 Include 특성 값으로 사용합니다.

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</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 런타임 동작을 구성하는 환경 변수에 대해 접두사를 DOTNET_에서 COMPlus_으로 표준화합니다. 그러나 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

참고하십시오

.NET 환경 변수