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

特定のパッケージは、常にパッケージ識別子と正確なバージョン番号を使用して参照されます。 たとえば、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 の特定のセマンティクスは、古いクライアントではサポートされていません。

このトピックの内容は以下のとおりです。

バージョンの基本

特定のバージョン番号は、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) はバージョン文字列を解析するために使用でき、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 は等しいということです。