패키지 버전 관리

  • 아티클

특정 패키지는 항상 패키지 식별자와 정확한 버전 번호를 사용하여 참조됩니다. 예를 들어, nuget.org의 Entity Framework에는 버전 4.1.10311에서 버전 6.1.3(안정적인 최신 릴리스)과 6.2.0-beta1과 같은 다양한 시험판 버전에 이르기까지 수십 개의 특정 패키지가 있습니다.

패키지를 만들 때 선택적 시험판 문자 접미사를 사용하여 특정 버전 번호를 할당합니다. 반면, 패키지를 사용할 때는 정확한 버전 번호 또는 허용 가능한 버전 범위를 지정할 수 있습니다.

다음 문서는 NuGet 4.3.0 이상 및 Visual Studio 2017 버전 15.3 이상에서 지원하는 의미 체계 버전 관리 2.0.0 표준을 따릅니다. SemVer v2.0.0의 특정 의미 체계는 이전 클라이언트에서 지원되지 않습니다.

이 항목의 내용:

버전 기본 사항

특정 버전 번호는 주.부.패치[-접미사] 형식으로 되어 있으며, 해당 구성 요소의 의미는 다음과 같습니다.

  • 주요: 주요 변경 내용
  • 부: 새로운 기능이지만 이전 버전과 호환됩니다.
  • 패치: 이전 버전과 호환되는 버그 수정만
  • -Suffix(선택 사항): 하이픈 뒤에 시험판 버전을 나타내는 문자열(의미 체계 버전 관리 또는 SemVer 규칙에 따라)입니다.

예:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Important

nuget.org는 정확한 버전 번호가 없는 패키지 업로드를 모두 거부합니다. 버전은 패키지를 만드는 데 사용되는 .nuspec 또는 프로젝트 파일에 지정해야 합니다.

시험판 버전

엄밀히 따지면, 패키지 작성자는 어떤 문자열이든 시험판 버전을 나타내는 접미사로 사용할 수 있습니다. 그 이유는 NuGet이 이러한 모든 버전을 시험판으로 처리하며, 달리 해석하지 않기 때문입니다. 즉, NuGet은 어떤 UI가 사용되었는지에 상관없이 전체 버전 문자열을 표시하며, 접미사의 의미는 전적으로 소비자의 해석에 맡깁니다.

그렇긴 하지만 패키지 개발자는 일반적으로 널리 인정된 명명 규칙을 따릅니다.

  • -alpha: 알파 릴리스는 일반적으로 진행 중인 작업 및 실험에 사용됩니다.
  • -beta: 일반적으로 다음에 계획된 릴리스에 대한 기능 완료인 베타 릴리스이지만 알려진 버그를 포함할 수 있습니다.
  • -rc: 일반적으로 심각한 버그가 발생하지 않는 한 잠재적으로 최종적(안정적)인 릴리스인 릴리스 후보입니다.

우선 순위에 따라 버전을 정렬할 때 NuGet은 SemVer 표준을 따르고 접미사가 없는 버전을 먼저 선택한 다음 사전 릴리스 버전에 우선 순위를 사전 사전순으로 적용하고 점 표기법을 숫자 순서로 처리합니다.

참고 항목

1.0.1-build.23과 같이 점 표기법이 있는 시험판 번호는 SemVer 2.0.0 표준의 일부로 간주되며 NuGet 4.3.0 이상에서만 지원됩니다.

1.0.1
1.0.1-zzz
1.0.1-rc.10
1.0.1-rc.2
1.0.1-open
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha10
1.0.1-aaa

1.0.1-alpha10은 사전순으로 엄격하게 정렬되는 반면 1.0.1-rc.10은 1.0.1-rc.2보다 우선 순위가 더 큽 있습니다.

버전 범위

패키지 종속성을 참조할 때 NuGet은 간격 표기법으로 버전 범위를 다음과 같이 요약하여 지정합니다.

Notation 적용된 규칙 Description
1.0 x ≥ 1.0 최소 버전(포함)
[1.0,) x ≥ 1.0 최소 버전(포함)
(1.0,) x > 1.0 최소 버전(제외)
[1.0] x == 1.0 정확한 버전 일치
(,1.0] x ≤ 1.0 최대 버전(포함)
(,1.0) x < 1.0 최대 버전(제외)
[1.0,2.0] 1.0 ≤ x ≤ 2.0 정확한 범위(포함)
(1.0,2.0) 1.0 < x < 2.0 정확한 범위(제외)
[1.0,2.0) 1.0 ≤ x < 2.0 최소 포함 및 최대 제외 혼합 버전
(1.0) 잘못됨 잘못됨

예제

프로젝트 파일, packages.config 파일, .nuspec 파일에서 패키지 종속성의 버전 또는 버전 범위를 항상 지정합니다. 버전 또는 버전 범위가 없으면, 종속성을 확인할 때 NuGet 2.8.x 이하는 사용 가능한 최신 패키지 버전을 선택하는 반면, NuGet 3.x 이상은 가장 낮은 패키지 버전을 선택합니다. 버전 또는 버전 범위를 지정하면 이러한 불확실성을 피할 수 있습니다.

프로젝트 파일의 참조(PackageReference)

<!-- Accepts any version 6.1 and above.
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any 6.x.y version.
     Will resolve to the highest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="6.*" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. 
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, this form is not
     recommended because it can be difficult to determine the lowest version. 
     Will resolve to the smallest acceptable stable version.
     -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and higher.
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher.
     Will resolve to the smallest acceptable stable version. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

packages.config에서의 참조:

packages.config에서 모든 종속성은 패키지를 복원할 때 사용되는 정확한 version 특성과 함께 나열됩니다. allowedVersions 특성은 패키지가 업데이트될 수 있는 버전을 제한하기 위해 업데이트 작업 시에만 사용됩니다.

<!-- Install/restore version 6.1.0, accept any version 6.1.0 and above on update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="6.1.0" />

<!-- Install/restore version 6.1.0, and do not change during update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="[6.1.0]" />

<!-- Install/restore version 6.1.0, accept any 6.x version during update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="[6,7)" />

<!-- Install/restore version 4.1.4, accept any version above, but not including, 4.1.3.
     Could be used to guarantee a dependency with a specific bug fix. -->
<package id="ExamplePackage" version="4.1.4" allowedVersions="(4.1.3,)" />

<!-- Install/restore version 3.1.2, accept any version up below 5.x on update, which might be
     used to prevent pulling in a later version of a dependency that changed its interface.
     However, this form is not recommended because it can be difficult to determine the lowest version. -->
<package id="ExamplePackage" version="3.1.2" allowedVersions="(,5.0)" />

<!-- Install/restore version 1.1.4, accept any 1.x or 2.x version on update, but not
     0.x or 3.x and higher. -->
<package id="ExamplePackage" version="1.1.4" allowedVersions="[1,3)" />

<!-- Install/restore version 1.3.5, accepts 1.3.2 up to 1.4.x on update, but not 1.5 and higher. -->
<package id="ExamplePackage" version="1.3.5" allowedVersions="[1.3.2,1.5)" />

.nuspec파일에서의 참조

<dependency> 요소의 version 특성은 종속성에 허용되는 범위 버전을 설명합니다.

<!-- Accepts any version 6.1 and above. -->
<dependency id="ExamplePackage" version="6.1" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. -->
<dependency id="ExamplePackage" version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, this form is not
     recommended because it can be difficult to determine the lowest version. -->
<dependency id="ExamplePackage" version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and higher. -->
<dependency id="ExamplePackage" version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<dependency id="ExamplePackage" version="[1.3.2,1.5)" />

정규화된 버전 번호

참고 항목

이는 NuGet 3.4 이상에 대한 호환성이 손상되는 변경입니다.

설치, 다시 설치 또는 복원 작업 시 리포지토리에서 패키지를 가져올 때 NuGet 3.4 이상은 버전 번호를 다음과 같이 처리합니다.

  • 버전 번호 앞에 있는 0을 제거합니다.

    • 1.00은 1.0으로 처리됩니다.
    • 1.01.1은 1.1.1로 처리됩니다.
    • 1.00.0.1은 1.0.0.1로 처리됩니다.

  • 버전 번호의 네 번째 파트에서 0을 생략합니다.

    • 1.0.0.0은 1.0.0으로 처리됩니다.
    • 1.0.01.0은 1.0.1로 처리됩니다.

  • SemVer 2.0.0 빌드 메타데이터가 제거됨

    • 1.0.7+r3456은 1.0.7로 처리됩니다.

pack 및 restore 작업은 가능한 경우 항상 버전을 정규화합니다. 이미 빌드된 패키지의 경우, 이 정규화 작업이 패키지 자체의 버전 번호에 영향을 주지는 않습니다. NuGet이 종속성을 확인할 때 버전과 일치시키는 방식에만 영향을 줍니다.

그러나 패키지 버전 중복을 방지하기 위해서는 NuGet 패키지 리포지토리에서 이러한 값을 NuGet과 동일한 방식으로 처리해야 합니다. 따라서 패키지 버전 1.0을 포함하는 리포지토리는 버전 1.0.0도 별도의 다른 패키지로 호스트해서는 안 됩니다.

유의적 버전 2.0.0

SemVer v2.0.0의 특정 의미 체계는 이전 클라이언트에서 지원되지 않습니다. NuGet은 다음 문 중 하나라도 참인 경우 패키지 버전이 SemVer v2.0.0에 해당한다고 간주합니다.

  • 시험판 레이블이 점으로 구분됩니다(예: 1.0.0-alpha.1).
  • 버전에 빌드-메타데이터(예: 1.0.0+githash)가 있습니다.

nuget.org의 경우 패키지는 다음 문 중 하나가 참인 경우 SemVer v2.0.0 패키지로 정의됩니다.

  • 패키지의 자체 버전은 위에서 정의한 대로 SemVer v2.0.0 규격이며, SemVer v1.0.0 규격이 아닙니다.
  • 패키지의 모든 종속성 버전 범위에는 최소 또는 최대 버전이 있으며, 이는 위에서 정의한 대로 SemVer v2.0.0 규격이며, SemVer v1.0.0 규격이 아닙니다(예: [1.0.0-alpha.1, )).

SemVer v2.0.0 특정 패키지를 nuget.org에 업로드하는 경우 패키지는 이전 클라이언트에 표시되지 않으며, 다음 NuGet 클라이언트에서만 사용할 수 있습니다.

  • NuGet 4.3.0 이상
  • Visual Studio 2017 버전 15.3 이상
  • NuGet VSIX v3.6.0을 사용하는 Visual Studio 2015
  • .NET SDK 2.0.0 이상

타사 클라이언트:

  • JetBrains Rider
  • Paket 버전 5.0 이상

NuGetVersion이 유의적 버전과 구분되는 부분

NuGet 패키지 버전을 프로그래밍 방식으로 사용하려면 NuGet.Versioning 패키지를 사용하는 것이 좋습니다. 정적 메서드 NuGetVersion.Parse(string)는 버전 문자열을 구문 분석하는 데 사용할 수 있으며 VersionComparer는 NuGetVersion 인스턴스를 정렬하는 데 사용할 수 있습니다.

다음은 .NET에서 실행되지 않는 언어로 NuGet 기능을 구현할 경우 NuGetVersion과 유의적 버전 간의 알려진 차이점 목록과 nuget.org에 이미 게시된 패키지에서 기존 유의적 버전 라이브러리가 작동하지 않을 수 있는 이유입니다.

  1. NuGetVersion은 네 번째 버전 세그먼트 Revision이 System.Version과 호환되거나 상위 집합이 되도록 지원합니다. 따라서 시험판 및 메타데이터 레이블을 제외한 버전 문자열은 Major.Minor.Patch.Revision입니다. 위에서 설명한 버전 정규화에 따라 0이면 Revision 정규화된 버전 문자열에서 생략됩니다.
  2. NuGetVersion에서는 주 세그먼트만 정의해야 합니다. 다른 모든 세그먼트는 선택 사항이며 0과 같습니다. 즉, 1, 1.0, 1.0.0, 1.0.0.0은 모두 허용되고 동일합니다.
  3. NuGetVersion 는 시험판 구성 요소에 대해 대/소문자를 구분하지 않는 문자열 비교를 사용합니다. 즉, 1.0.0-alpha와 1.0.0-Alpha가 동일합니다.