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

  • [アーティクル]

特定のパッケージは、常にパッケージ識別子と正確なバージョン番号を使用して参照されます。 たとえば、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) はバージョン文字列を解析するために使用でき、VersionComparer は NuGetVersion インスタンスの並べ替えに使用できます。

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

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