패키지 버전 관리

아티클
01/23/2025

특정 패키지는 항상 해당 패키지 식별자와 정확한 버전 번호를 사용하여 참조됩니다. 예를 들어 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 특정 의미 체계는 이전 클라이언트에서 지원되지 않습니다.

이 항목에서는 다음을 수행합니다.

버전 기본 시험판 접미사를 포함합니다.
버전 범위
정규화된 버전 번호
의미 체계 버전 관리 2.0.0

버전 기본 사항

특정 버전 번호는 Major.Minor.Patch[-Suffix]형식으로 구성 요소에 다음과 같은 의미가 있습니다.

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

예:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

중요하다

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

시험판 버전

기술적으로 말하자면, 패키지 작성자는 NuGet이 이러한 버전을 시험판으로 처리하고 다른 해석을 하지 않으므로 모든 문자열을 접미사로 사용하여 시험판 버전을 나타낼 수 있습니다. 즉, NuGet은 관련된 모든 UI에 전체 버전 문자열을 표시하여 접미사의 의미를 소비자에게 그대로 둡니다.

즉, 패키지 개발자는 일반적으로 인식된 명명 규칙을 따릅니다.

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

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

메모

점 표기법이 있는 시험판 번호(1.0.1-build.23)는 SemVer 2.0.0 표준의 일부로 간주되며, 따라서 NuGet 4.3.0 이상만 지원되기 .

SemVer 2.0 정렬
SemVer 1.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보다 우선 순위가 더 큽 있습니다.

1.0.1
1.0.1-zzz
1.0.1-open
1.0.1-beta05
1.0.1-beta02
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha10
1.0.1-aaa

1.0.1-rc.10 및 1.0.1-rc.2 같은 버전은 이전 버전의 클라이언트에서 구문 분석할 수 없으며 해당 버전이 있는 패키지는 해당 클라이언트에서 다운로드할 수 없습니다.

두 자리 숫자(또는 그 이상)를 사용할 수 있는 시험판 태그와 함께 숫자 접미사를 사용하는 경우 beta01 및 beta05와 같이 선행 0을 사용하여 숫자가 커질 때 올바르게 정렬되도록 합니다. 이 권장 사항은 이 스키마만 적용됩니다.

위에 표시된 순서에도 불구하고 NuGet은 종속성 확인 중에 안정적인 & 시험판 패키지를 항상 고려하지는 않습니다. 이러한 규칙은 종속성 확인자세히 설명되어 있습니다.

버전 범위

패키지 종속성을 참조할 때 NuGet은 다음과 같이 요약된 버전 범위를 지정하기 위한 간격 표기법을 사용하도록 지원합니다.

기보법	적용된 규칙	묘사
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 파일에서 패키지 종속성에 대한 버전 또는 버전 범위를 항상 지정합니다. 버전 또는 버전 범위가 없으면 종속성을 확인할 때 일관된 복원 결과가 보장되지 않습니다. 호환성 문제를 알지 못하는 한 소유하지 않은 패키지에 버전 범위에 대한 상한을 지정하지 마세요. 버전 범위의 상한은 채택에 해를 끼치고, 소비자가 종속성에 대한 중요한 업데이트를 받지 못하게 하며, 경우에 따라 지원되지 않는 버전의 종속성을 사용하도록 유도할 수 있습니다.

프로젝트 파일의 참조(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)" />

파일 참조

<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은 다음 문 중 하나가 true인 경우 패키지 버전을 SemVer v2.0.0으로 간주합니다.

시험판 레이블은 점으로 구분됩니다(예: 1.0.0-alpha.1
버전에는 빌드 메타데이터(예: 1.0.0 이상 githash

nuget.org 경우 다음 문 중 하나가 true인 경우 패키지가 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 라이더
Paket 버전 5.0 이상

NuGetVersion이 의미 체계 버전 관리와 다른 위치

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

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

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

다음을 통해 공유