パッケージのバージョン管理

特定のパッケージは、常にパッケージ識別子と正確なバージョン番号を使用して参照されます。 たとえば、nuget.org の Entity Framework には、バージョン 4.1.10311 からバージョン 6.1.3 (最新の安定したリリース) までの数十の特定のパッケージと、6.2.0-beta1 のようなさまざまなプレリリース バージョンがあります。

パッケージの作成時に、オプションのプレリリース テキスト サフィックスを使用して特定のバージョン番号を割り当てます。 一方、パッケージを使用するときには、正確なバージョン番号または許容されるバージョンの範囲のいずれかを指定できます。

このトピックの内容:

バージョンの基本

特定のバージョン番号は、Major.Minor.Patch[-Suffix] という形式になっています。ここで、各構成要素には次の意味があります。

例:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta1

重要

nuget.org では、正確なバージョン番号がないパッケージのアップロードがすべて拒否されます。 バージョンは、.nuspec 内またはパッケージの作成に使用されるプロジェクト ファイル内で指定する必要があります。

プレリリース バージョン

技術的に言えば、パッケージの作成者は、任意の文字列をサフィックスとして使用してプレリリース バージョンを示すことができます。これは、NuGet ではそのようなバージョンがプレリリースとして扱われ、他の解釈は行われないためです。 つまり、NuGet では、関係する UI に完全なバージョン文字列が表示され、サフィックスの意味の解釈はコンシューマーに委ねられます。

つまり、パッケージ開発者は一般に、認識されている名前付け規則に従います。

  • -alpha:アルファ リリース。一般的に、進行中の製品または実験に使用されます。
  • -beta: ベータ リリース。一般的に、次に計画されているリリースの機能をすべて利用できますが、既知のバグが含まれている可能性があります。
  • -rc: リリース候補。一般的に、重大なバグが現れない限り、最終版 (安定版) となる可能性があるリリース。

Note

NuGet 4.3.0 以降では、1.0.1-build.23 のように、ドット表記のプレリリース番号をサポートする SemVer 2.0.0 がサポートされます。 ドット表記は、バージョン 4.3.0 より前の NuGet ではサポートされていません。 1.0.1-build23 のような形式を使用できます。

パッケージ参照を解決するときに、複数のパッケージ バージョンのサフィックスだけが異なる場合、NuGet ではサフィックスのないバージョンが最初に選択され、プレリリース バージョンにアルファベットの逆順の優先順位が適用されます。 たとえば、以下のバージョンは、示されているとおりの順序で選択されます。

1.0.1
1.0.1-zzz
1.0.1-rc
1.0.1-open
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha
1.0.1-aaa

セマンティック バージョニング 2.0.0

NuGet 4.3.0 以降と Visual Studio 2017 バージョン 15.3 以降では、NuGet によってセマンティック バージョニング 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
  • dotnet
    • dotnetcore.exe (.NET SDK 2.0.0+)

サード パーティ製クライアント:

  • JetBrains Rider
  • Paket バージョン 5.0 以降

バージョン範囲

パッケージの依存関係を参照する場合、以下にまとめるように、NuGet ではバージョン範囲を指定するために間隔表記の使用がサポートされます。

Notation 適用されるルール 説明
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) 無効 無効

PackageReference 形式を使用する場合、NuGet では、番号の Major、Minor、Patch、およびプレリリース サフィックス部分に浮動小数点表記 * を使用することもできます。 packages.config 形式では、浮動小数点バージョンはサポートされていません。 浮動バージョンを指定した場合、バージョンの説明に一致する既存の最高バージョンに解決されるというルールになります。 次に、浮動バージョンと解決の例を示します。

Note

PackageReference のバージョン範囲には、プレリリース バージョンが含まれます。 仕様により、浮動バージョンでは、オプトインしない限りプレリリース バージョンは解決されません。 関連する機能要求の状態については、問題 6434 に関するページをご覧ください。

プロジェクト ファイル、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)" />

浮動バージョンの解決

Version サーバーに存在するバージョン 解決方法 理由 メモ
* 1.1.0
1.1.1
1.2.0
1.3.0-alpha
1.2.0 最も高い安定バージョン。
1.1.* 1.1.0
1.1.1
1.1.2-alpha
1.2.0-alpha
1.1.1 指定したパターンに従う最も高い安定バージョン。
*-* 1.1.0
1.1.1
1.1.2-alpha
1.3.0-beta
1.3.0-beta 安定していないバージョンも含めた、最も高いバージョン。 Visual Studio バージョン 16.6、NuGet バージョン 5.6、.NET Core SDK バージョン 3.1.300 で使用可能。
1.1.*-* 1.1.0
1.1.1
1.1.2-alpha
1.1.2-beta
1.3.0-beta
1.1.2-beta 安定していないバージョンも含めて、パターンに従う最も高いバージョン。 Visual Studio バージョン 16.6、NuGet バージョン 5.6、.NET Core SDK バージョン 3.1.300 で使用可能。

注意

フローティング バージョン解決では、パッケージが一覧に含まれるかどうかは考慮されません。 フローティング バージョン解決は、グローバル パッケージ フォルダー内のパッケージで条件を満たすことができる場合、ローカルで解決されます。

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 を別の異なるパッケージとしてホストすることはできません。

NuGetVersion とセマンティック バージョニングが異なる点

NuGet パッケージのバージョンをプログラムで使用する場合は、パッケージの NuGet.Versioning を使用することを強くお勧めします。 静的メソッド NuGetVersion.Parse(string) はバージョン文字列を解析するために使用でき、VersionComparerNuGetVersion インスタンスの並べ替えに使用できます。

.NET で実行されない言語で NuGet の機能を実装する場合、既知の NuGetVersion とセマンティック バージョニングの相違点と、既存のセマンティック バージョニング ライブラリが nuget.org で既に公開されているパッケージに対して機能しない可能性がある理由のリストを次に示します。

  1. NuGetVersion は、4 番目のバージョン セグメント (Revision) をサポートします。これは、System.Version と互換性があるか、この上位集合になります。 そのため、プレリリースとメタデータのラベルを除外すると、バージョン文字列は Major.Minor.Patch.Revision になります。 上記のバージョンの正規化に従って、Revision が 0 の場合は、正規化されたバージョン文字列から除外されます。
  2. NuGetVersion には、メジャー セグメントのみを定義する必要があります。 その他すべては任意であり、0 に相当します。 これは、11.01.0.01.0.0.0 はすべて受け入れられ、等しいということを意味します。
  3. NuGetVersion では、プレリリース コンポーネントに対して大文字と小文字を区別しない文字列比較が使用されます。 つまり、1.0.0-alpha1.0.0-Alpha は等しいということです。