次の方法で共有

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

  • [アーティクル]

特定のパッケージは常に、そのパッケージ識別子と正確なバージョン番号を使用して参照されます。 たとえば、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]形式です。コンポーネントの意味は次のとおりです。

  • 主な: 重大な変更
  • マイナー: 新機能が、下位互換性がある
  • パッチ: 下位互換性のあるバグ修正のみ
  • -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 以降のでのみサポート 。

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 ファイル内のパッケージ依存関係のバージョンまたはバージョン範囲を常に指定します。 バージョンまたはバージョンの範囲がない場合、依存関係を解決する場合、一貫性のある復元結果は保証されません。 互換性の問題がわかっている場合を除き、所有していないパッケージにはバージョン範囲の上限を指定しないでください。 バージョン範囲の上限は導入に悪影響を及ぼし、コンシューマーが依存関係に対して重要な更新プログラムを取得するのを防ぎ、場合によってはサポートされていないバージョンの依存関係を使用する可能性があります。

プロジェクト ファイル内の参照 (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)" />

正規化されたバージョン番号

手記

これは、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 番目の部分の 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 では、次のいずれかのステートメントに該当する場合、パッケージ バージョンが 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 以降
  • 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 が等しいことを意味します。