パッケージのバージョン管理
特定のパッケージは、常にパッケージ識別子と正確なバージョン番号を使用して参照されます。 たとえば、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] という形式になっています。ここで、各構成要素には次の意味があります。
- Major: 破壊的変更
- Minor: 新機能、ただし下位互換性あり
- Patch: 下位互換性のバグ修正のみ
- -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 標準に従い、最初にサフィックスのないバージョンを選択し、次にプレリリース バージョンに優先順位を逆アルファベット順に適用し、ドット表記番号を数値順に処理します。
Note
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 ではバージョン範囲を指定するために間隔表記の使用がサポートされます。
| 表記 | 適用されるルール | 説明 |
|---|---|---|
| 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)" />
正規化されたバージョン番号
Note
これは、NuGet 3.4 以降での破壊的変更です。
インストール、再インストール、または復元操作中にリポジトリからパッケージを取得すると、NuGet 3.4 以降ではバージョン番号が次のように扱われます。
先頭のゼロはバージョン番号から削除されます。
- 1.00 は 1.0 として扱われます
- 1.01.1 は 1.1.1 として扱われます
- 1.00.0.1 は 1.0.0.1 として扱われます
バージョン番号の 4 番目の部分のゼロは省略されます
- 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 以降
- Visual Studio 2015 と NuGet VSIX v3.6.0
- .NET SDK 2.0.0 以降
サード パーティ製クライアント:
- JetBrains Rider
- Paket バージョン 5.0 以降
NuGetVersion とセマンティック バージョニングが異なる点
NuGet パッケージのバージョンをプログラムで使用する場合は、パッケージの NuGet.Versioning を使用することを強くお勧めします。 静的メソッド NuGetVersion.Parse(string) はバージョン文字列を解析するために使用でき、VersionComparer は NuGetVersion インスタンスの並べ替えに使用できます。
.NET で実行されない言語で NuGet の機能を実装する場合、既知の NuGetVersion とセマンティック バージョニングの相違点と、既存のセマンティック バージョニング ライブラリが nuget.org で既に公開されているパッケージに対して機能しない可能性がある理由のリストを次に示します。
NuGetVersionは、4 番目のバージョン セグメント (Revision) をサポートします。これは、System.Versionと互換性があるか、この上位集合になります。 そのため、プレリリースとメタデータのラベルを除外すると、バージョン文字列はMajor.Minor.Patch.Revisionになります。 上記のバージョンの正規化に従って、Revisionが 0 の場合は、正規化されたバージョン文字列から除外されます。NuGetVersionには、メジャー セグメントのみを定義する必要があります。 その他すべては任意であり、0 に相当します。 これは、1、1.0、1.0.0、1.0.0.0はすべて受け入れられ、等しいということを意味します。NuGetVersionは、プレリリース コンポーネントに対して、大文字と小文字を区別しない文字列比較を使用します。 つまり、1.0.0-alphaと1.0.0-Alphaは等しいということです。