global.json 개요

아티클
05/10/2023

이 문서의 적용 대상: ✔️ .NET Core 3.1 SDK 이상 버전

global.json 파일을 사용하면 .NET CLI 명령을 실행할 때 어떤 .NET SDK 버전을 사용할지 정의할 수 있습니다. .NET SDK 버전을 선택하는 것은 프로젝트 대상 런타임 버전을 지정하지 않습니다. .NET SDK 버전은 사용되는 .NET CLI 버전을 나타냅니다. 이 문서에서는 global.json을 사용하여 SDK 버전을 선택하는 방법을 설명합니다.

컴퓨터에 설치된 최신 SDK 버전을 항상 사용하려는 경우 global.json 파일이 필요하지 않습니다. 그러나 CI(연속 통합) 시나리오에서는 일반적으로 사용되는 SDK 버전에 허용되는 범위를 지정하려고 합니다. global.json 파일에는 허용되는 버전 범위를 지정하는 유연한 방법을 제공하는 rollForward 기능이 있습니다. 예를 들어 다음 global.json 파일은 컴퓨터에 설치된 6.0에 대한 6.0.300 이상 기능 밴드 또는 패치를 선택합니다.

{
  "sdk": {
    "version": "6.0.300",
    "rollForward": "latestFeature"
  }
}

.NET SDK는 현재 작업 디렉터리(반드시 프로젝트 디렉터리와 동일하지는 않음) 또는 부모 디렉터리 중 하나에서 global.json 파일을 찾습니다.

SDK 버전 대신 런타임 버전을 지정하는 방법에 대한 자세한 내용은 대상 프레임워크를 참조하세요.

global.json 스키마

sdk

유형: object

선택할 .NET SDK에 대한 정보를 지정합니다.

version

유형: string

사용할 .NET SDK의 버전입니다.

이 필드:

와일드카드를 지원하지 않습니다. 즉, 전체 버전 번호를 지정해야 합니다.
버전 범위를 지원하지 않습니다.

시험판 허용

유형: boolean
.NET Core 3.0 SDK부터 사용할 수 있습니다.

사용할 SDK 버전을 선택할 때 SDK 확인자가 시험판 버전을 고려해야 하는지 여부를 나타냅니다.

이 값을 명시적으로 설정하지 않은 경우 Visual Studio에서 실행하고 있는지에 따라 기본값이 달라집니다.

Visual Studio에서 실행하지 않는 경우 기본값은 true입니다.
Visual Studio에서 실행하는 경우 요청된 시험판 상태를 사용합니다. 즉, Visual Studio의 미리 보기 버전을 사용하거나 .NET SDK 미리 보기 사용 옵션(도구>옵션>환경>미리 보기 기능)을 설정하는 경우 기본값은 true입니다. 그렇지 않을 경우 기본값은 false다.

롤포워드

유형: string
.NET Core 3.0 SDK부터 사용할 수 있습니다.

SDK 버전을 선택할 때, 특정 SDK 버전이 누락된 경우 대체하거나 상위 버전을 사용하기 위한 지시문으로 사용할 롤포워드 정책입니다. 버전을 latestMajor로 설정하지 않는 한 rollForward 값을 사용하여 버전을 지정해야 합니다. 기본 롤포워드 동작은 일치 규칙에 의해 결정됩니다.

사용 가능한 정책 및 해당 동작을 이해하려면 x.y.znn 형식의 SDK 버전에 대한 다음 정의를 참조하세요.

x는 주 버전입니다.
y는 부 버전입니다.
z는 기능 밴드입니다.
nn은 패치 버전입니다.

다음 표에서는 rollForward 키에 사용할 수 있는 값을 보여 줍니다.

값	동작
`patch`	지정한 버전을 사용합니다. 버전이 없으면 최신 패치 수준으로 롤포워드하세요. 찾을 수 없으면 실패합니다. 이 값은 이전 버전의 SDK에서 발생하는 레거시 동작입니다.
`feature`	지정된 주 버전, 부 버전 및 기능 밴드의 최신 패치 수준을 사용합니다. 최신 패치 수준을 찾을 수 없는 경우 동일한 주/부 버전에 있는 다음 상위 기능 밴드로 롤포워드하고 해당 기능 밴드의 최신 패치 수준을 사용합니다. 찾을 수 없으면 실패합니다.
`minor`	지정된 주 버전, 부 버전 및 기능 밴드의 최신 패치 수준을 사용합니다. 최신 패치 수준을 찾을 수 없는 경우 동일한 주/부 버전에 있는 다음 상위 기능 밴드로 롤포워드하고 해당 기능 밴드의 최신 패치 수준을 사용합니다. 최신 패치 수준을 찾을 수 없는 경우 동일한 주 버전에 있는 다음 상위 부 버전 및 기능 밴드로 롤포워드하고 해당 기능 밴드에 대한 최신 패치 수준을 사용합니다. 찾을 수 없으면 실패합니다.
`major`	지정된 주 버전, 부 버전 및 기능 밴드의 최신 패치 수준을 사용합니다. 최신 패치 수준을 찾을 수 없는 경우 동일한 주/부 버전에 있는 다음 상위 기능 밴드로 롤포워드하고 해당 기능 밴드의 최신 패치 수준을 사용합니다. 최신 패치 수준을 찾을 수 없는 경우 동일한 주 버전에 있는 다음 상위 부 버전 및 기능 밴드로 롤포워드하고 해당 기능 밴드에 대한 최신 패치 수준을 사용합니다. 최신 패치 수준을 찾을 수 없는 경우 다음 상위 주 버전, 부 버전 및 기능 밴드로 롤포워드하고 해당 기능 밴드의 최신 패치 수준을 사용합니다. 찾을 수 없으면 실패합니다.
`latestPatch`	요청된 주, 부 및 기능 밴드와 일치하는 최신 설치된 패치 수준을 지정된 값보다 크거나 같은 패치 수준을 사용합니다. 찾을 수 없으면 실패합니다.
`latestFeature`	지정된 값보다 크거나 같은 기능 대역 및 패치 수준을 사용하여 요청된 주 및 부 버전과 일치하는 가장 높은 설치된 기능 밴드 및 패치 수준을 사용합니다. 찾을 수 없으면 실패합니다.
`latestMinor`	지정된 값보다 크거나 같은 부, 기능 대역 및 패치 수준과 요청된 주 항목과 일치하는 가장 높은 설치된 부, 기능 밴드 및 패치 수준을 사용합니다. 찾을 수 없으면 실패합니다.
`latestMajor`	지정된 값보다 크거나 같은 버전으로 설치된 가장 높은 .NET SDK를 사용합니다. 찾을 수 없으면 실패합니다.
`disable`	롤포워드하지 않습니다. 정확하게 일치해야 합니다.

msbuild-sdk

유형: object

개별 프로젝트가 아닌 한 곳에서 프로젝트 SDK 버전을 제어할 수 있습니다. 자세한 내용은 프로젝트 SDK를 확인하는 방법을 참조하세요.

global.json 주석

global.json 파일의 주석은 JavaScript 또는 C# 스타일 주석을 사용하여 지원됩니다. 다음은 그 예입니다.

{
   // This is a comment.
  "sdk": {
    "version": "7.0.100" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

예

다음 예제에서는 시험판 버전을 사용하지 않는 방법을 보여줍니다.

{
  "sdk": {
    "allowPrerelease": false
  }
}

다음 예제에서는 지정된 버전과 같거나 높은 최상위 버전을 사용하는 방법을 보여줍니다. 표시된 JSON은 2.2.200 이전 SDK 버전을 허용하지 않으며 2.2.200 이상 버전(3.0.xxx 및 3.1.xxx 포함)을 허용합니다.

{
  "sdk": {
    "version": "2.2.200",
    "rollForward": "latestMajor"
  }
}

다음 예제에서는 정확하게 지정된 버전을 사용하는 방법을 보여줍니다.

{
  "sdk": {
    "version": "3.1.100",
    "rollForward": "disable"
  }
}

다음 예제에서는 설치된 특정 주 버전과 부 버전의 최신 기능 밴드 및 패치 버전을 사용하는 방법을 보여줍니다. 표시된 JSON은 3.1.102 이전 SDK 버전을 허용하지 않으며 3.1.102 이상인 3.1.xxx 버전(예: 3.1.103 또는 3.1.200)을 허용합니다.

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestFeature"
  }
}

다음 예제에서는 특정 버전으로 설치된 최상위 패치 버전을 사용하는 방법을 보여줍니다. 표시된 JSON은 3.1.102 이전 SDK 버전을 허용하지 않으며 3.1.102 이상인 3.1.1xx 버전(예: 3.1.103 또는 3.1.199)을 허용합니다.

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestPatch"
  }
}

global.json 및 .NET CLI

global json 파일에 SDK 버전을 설정하기 위해서는 컴퓨터에 설치된 SDK 버전을 알고 있는 것이 좋습니다. 이 작업을 수행하는 방법은 .NET이 이미 설치되어 있는지 확인하는 방법을 참조하세요.

머신에 추가 .NET SDK 버전을 설치하려면 .NET 다운로드 페이지를 방문하세요.

다음 예제와 비슷한 dotnet new 명령을 실행하여 현재 디렉터리에서 global.json 파일을 새로 만들 수 있습니다.

dotnet new globaljson --sdk-version 6.0.100

일치 규칙

참고 항목

일치 규칙에는 설치된 모든 .NET 설치 런타임에서 공통으로 사용되는 dotnet.exe 진입점이 적용됩니다. 여러 런타임이 함께 설치되어 있거나 global.json 파일을 사용 중인 경우 설치된 최신 버전의 .NET 런타임에 대한 일치 규칙이 사용됩니다.

사용할 SDK 버전을 결정할 때 적용되는 규칙은 다음과 같습니다.

global. json 파일을 찾을 수 없거나 global.json이 SDK 버전 또는 allowPrerelease 값을 지정하지 않은 경우 설치된 최상위 SDK 버전이 사용됩니다(rollForward을 latestMajor로 설정하는 것과 같음). 시험판 SDK 버전이 고려되는지 여부는 dotnet(이)가 호출되는 방법에 따라 달라집니다.
- Visual Studio에서 실행하지 않는 경우 시험판 버전이 고려됩니다.
- Visual Studio에서 실행하는 경우 요청된 시험판 상태를 사용합니다. 즉, Visual Studio의 미리 보기 버전을 사용하거나 .NET SDK의 미리 보기 사용 옵션(도구>옵션>환경>미리 보기 기능)을 설정하는 경우 시험판 버전이 고려됩니다. 그렇지 않으면 릴리스 버전만 고려됩니다.
SDK 버전을 지정하지 않고 allowPrerelease 값을 지정하는 global.json 파일을 찾은 경우 설치된 최상위 SDK 버전이 사용됩니다(rollForward를 latestMajor로 설정하는 것과 같음). 최신 SDK 버전을 릴리스 또는 시험판이 될 수 있는지는 allowPrerelease 값에 따라 달라집니다. true는 시험판 버전이 고려됨을 나타냅니다. false는 릴리스 버전만 고려됨을 나타냅니다.
global.json 파일을 찾아 SDK 버전을 지정하는 경우 다음과 같습니다.
- rollForward 값이 설정되지 않은 경우 latestPatch를 기본 rollForward 정책으로 사용합니다. 그렇지 않으면 롤포워드 섹션에서 각 값과 해당 동작을 확인하세요.
- 시험판 버전을 고려하는지와 allowPrerelease가 설정되지 않은 경우의 기본 동작은 allowPrerelease 섹션에 설명되어 있습니다.

빌드 경고 문제 해결

다음 경고는 .NET SDK의 시험판 버전을 사용하여 프로젝트를 컴파일했음을 나타냅니다.

.NET Core SDK의 미리보기 버전으로 작업하고 있습니다. SDK 버전은 현재 프로젝트의 global.json 파일을 통해 정의할 수 있습니다. 자세한 내용은 https://go.microsoft.com/fwlink/?linkid=869452를 참조하세요.

.NET의 미리 보기 버전을 사용하고 있습니다. https://aka.ms/dotnet-core-preview을 참조하세요.

.NET SDK 버전은 높은 품질의 기록과 약정을 가지고 있습니다. 그러나 시험판 버전을 사용하지 않으려면 allowPrerelease 섹션에서 사용할 수 있는 다양한 전략을 확인하세요. .NET Core 3.0 이상 런타임 또는 SDK가 설치된 적이 없던 컴퓨터의 경우 global.json 파일을 만들고 사용할 정확한 버전을 지정해야 합니다.
다음 경고는 프로젝트가 .NET Core 2.1 SDK 이상 버전과 호환되지 않는 EF Core 1.0 또는 1.1을 대상으로 함을 나타냅니다.

스타트업 프로젝트 '{startupProject}'는 '.NETCoreApp' 버전 '{targetFrameworkVersion}' 프레임워크를 대상으로 합니다. 이 버전의 Entity Framework Core .NET 명령줄 도구는 버전 2.0 이상만 지원합니다. 이전 버전의 도구 사용에 대한 자세한 내용은 https://go.microsoft.com/fwlink/?linkid=871254를 참조하세요.

.NET Core 2.1 SDK(버전 2.1.300)부터 dotnet ef 명령이 SDK에 포함되었습니다. 프로젝트를 컴파일하려면 머신에 .NET Core 2.0 SDK(버전 2.1.201) 또는 이전 버전을 설치하고 global.json 파일을 사용하여 원하는 SDK 버전을 정의하세요. dotnet ef 명령에 대한 자세한 내용은 EF Core .NET 명령줄 도구를 참조하세요.
global.json을 사용하여 특정 버전의 .NET SDK를 유지하는 경우 Visual Studio는 .NET SDK의 단일 복사본만 설치합니다. 따라서 Visual Studio 버전을 업그레이드하면 새 버전을 설치하는 데 사용한 이전 버전의 .NET SDK가 제거됩니다. 다른 주 .NET 버전인 경우에도 이전 버전을 제거합니다.

Visual Studio에서 .NET SDK 버전을 제거하지 않도록 하려면 다운로드 페이지에서 독립 실행형 .NET SDK를 설치해야 합니다. 이렇게 하면 Visual Studio를 통해 해당 버전의 .NET SDK에 대한 자동 업데이트를 더 이상 받지 않으며 보안 문제가 발생할 수 있습니다.

참고 항목

프로젝트 SDK를 확인하는 방법

global.json 개요

global.json 스키마

sdk

version

시험판 허용

롤포워드

msbuild-sdk

global.json 주석

예

global.json 및 .NET CLI

일치 규칙

빌드 경고 문제 해결

참고 항목

피드백

추가 리소스