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

特定のパッケージは、常にパッケージ識別子と正確なバージョン番号を使用して参照されます。A specific package is always referred to using its package identifier and an exact version number. たとえば、nuget.org の Entity Framework には、バージョン 4.1.10311 からバージョン 6.1.3 (最新の安定したリリース) までの数十の特定のパッケージと、6.2.0-beta1 のようなさまざまなプレリリース バージョンがあります。For example, Entity Framework on nuget.org has several dozen specific packages available, ranging from version 4.1.10311 to version 6.1.3 (the latest stable release) and a variety of pre-release versions like 6.2.0-beta1.

パッケージの作成時に、オプションのプレリリース テキスト サフィックスを使用して特定のバージョン番号を割り当てます。When creating a package, you assign a specific version number with an optional pre-release text suffix. 一方、パッケージを使用するときには、正確なバージョン番号または許容されるバージョンの範囲のいずれかを指定できます。When consuming packages, on the other hand, you can specify either an exact version number or a range of acceptable versions.

このトピックの内容:In this topic:

バージョンの基本Version basics

特定のバージョン番号は、Major.Minor.Patch[-Suffix] という形式になっています。ここで、各構成要素には次の意味があります。A specific version number is in the form Major.Minor.Patch[-Suffix], where the components have the following meanings:

  • Major:互換性に影響する変更Major: Breaking changes
  • Minor: 新機能、ただし下位互換性ありMinor: New features, but backwards compatible
  • Patch: 下位互換性のバグ修正のみPatch: Backwards compatible bug fixes only
  • -Suffix (省略可能): ハイフンに続けて、プレリリース バージョンを示す文字列 (セマンティック バージョニングまたは SemVer 1.0 規約に従う)。-Suffix (optional): a hyphen followed by a string denoting a pre-release version (following the Semantic Versioning or SemVer 1.0 convention).

例:Examples:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta1

重要

nuget.org では、正確なバージョン番号がないパッケージのアップロードがすべて拒否されます。nuget.org rejects any package upload that lacks an exact version number. バージョンは、.nuspec 内またはパッケージの作成に使用されるプロジェクト ファイル内で指定する必要があります。The version must be specified in the .nuspec or project file used to create the package.

プレリリース バージョンPre-release versions

技術的に言えば、パッケージの作成者は、任意の文字列をサフィックスとして使用してプレリリース バージョンを示すことができます。これは、NuGet ではそのようなバージョンがプレリリースとして扱われ、他の解釈は行われないためです。Technically speaking, package creators can use any string as a suffix to denote a pre-release version, as NuGet treats any such version as pre-release and makes no other interpretation. つまり、NuGet では、関係する UI に完全なバージョン文字列が表示され、サフィックスの意味の解釈はコンシューマーに委ねられます。That is, NuGet displays the full version string in whatever UI is involved, leaving any interpretation of the suffix's meaning to the consumer.

つまり、パッケージ開発者は一般に、認識されている名前付け規則に従います。That said, package developers generally follow recognized naming conventions:

  • -alpha:アルファ リリース。一般的に、進行中の製品または実験に使用されます。-alpha: Alpha release, typically used for work-in-progress and experimentation.
  • -beta: ベータ リリース。一般的に、次に計画されているリリースの機能をすべて利用できますが、既知のバグが含まれている可能性があります。-beta: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs.
  • -rc: リリース候補。一般的に、重大なバグが現れない限り、最終版 (安定版) となる可能性があるリリース。-rc: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge.

注意

NuGet 4.3.0 以降では、1.0.1-build.23 のように、ドット表記のプレリリース番号をサポートする SemVer 2.0.0 がサポートされます。NuGet 4.3.0+ supports SemVer 2.0.0, which supports pre-release numbers with dot notation, as in 1.0.1-build.23. ドット表記は、バージョン 4.3.0 より前の NuGet ではサポートされていません。Dot notation is not supported with NuGet versions before 4.3.0. 1.0.1-build23 のような形式を使用できます。You can use a form like 1.0.1-build23.

パッケージ参照を解決するときに、複数のパッケージ バージョンのサフィックスだけが異なる場合、NuGet ではサフィックスのないバージョンが最初に選択され、プレリリース バージョンにアルファベットの逆順の優先順位が適用されます。When resolving package references and multiple package versions differ only by suffix, NuGet chooses a version without a suffix first, then applies precedence to pre-release versions in reverse alphabetical order. たとえば、以下のバージョンは、示されているとおりの順序で選択されます。For example, the following versions would be chosen in the exact order shown:

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.0Semantic Versioning 2.0.0

NuGet 4.3.0 以降と Visual Studio 2017 バージョン 15.3 以降では、NuGet によってセマンティック バージョニング 2.0.0 がサポートされます。With NuGet 4.3.0+ and Visual Studio 2017 version 15.3+, NuGet supports Semantic Versioning 2.0.0.

SemVer v2.0.0 の特定のセマンティクスは、以前のクライアントではサポートされません。Certain semantics of SemVer v2.0.0 are not supported in older clients. NuGet では、次のいずれかの文が真の場合に、パッケージ バージョンが SemVer v2.0.0 に固有であると見なされます。NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true:

  • プレリリース ラベルがドットで区切られている (例: 1.0.0-alpha.1)The pre-release label is dot-separated, for example, 1.0.0-alpha.1
  • バージョンにビルド メタデータが含まれている (例: 1.0.0+githash)The version has build-metadata, for example, 1.0.0+githash

nuget.org では、次のいずれかの文が真の場合に、パッケージが SemVer v2.0.0 パッケージとして定義されます。For nuget.org, a package is defined as a SemVer v2.0.0 package if either of the following statements is true:

  • パッケージの独自のバージョンが上で定義されている SemVer v2.0.0 に準拠しているが、SemVer v1.0.0 には準拠していない。The package's own version is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, as defined above.
  • パッケージの依存関係のバージョン範囲のいずれかの最小または最大バージョンが上で定義されている SemVer v2.0.0 に準拠しているが、SemVer v1.0.0 には準拠していない (例: [1.0.0-alpha.1, ) )。Any of the package's dependency version ranges has a minimum or maximum version that is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, defined above; for example, [1.0.0-alpha.1, ).

SemVer v2.0.0 固有のパッケージを nuget.org にアップロードした場合、パッケージは以前のクライアントでは非表示になり、以下の NuGet クライアントでのみ使用できます。If you upload a SemVer v2.0.0-specific package to nuget.org, the package is invisible to older clients and available to only the following NuGet clients:

  • NuGet 4.3.0 以降NuGet 4.3.0+
  • Visual Studio 2017 バージョン 15.3 以降Visual Studio 2017 version 15.3+
  • Visual Studio 2015 と NuGet VSIX v3.6.0Visual Studio 2015 with NuGet VSIX v3.6.0
  • dotnetdotnet
    • dotnetcore.exe (.NET SDK 2.0.0+)dotnetcore.exe (.NET SDK 2.0.0+)

サード パーティ製クライアント:Third-party clients:

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

バージョン範囲とワイルドカードVersion ranges and wildcards

パッケージの依存関係を参照する場合、以下にまとめるように、NuGet ではバージョン範囲を指定するために間隔表記の使用がサポートされます。When referring to package dependencies, NuGet supports using interval notation for specifying version ranges, summarized as follows:

NotationNotation 適用されるルールApplied rule 説明Description
11.0 x ≥ 1.0x ≥ 1.0 最小バージョン (示されている値を含む)Minimum version, inclusive
(1.0,)(1.0,) x > 1.0x > 1.0 最小バージョン (示されている値を含まない)Minimum version, exclusive
[1.0][1.0] x == 1.0x == 1.0 正確なバージョンの一致Exact version match
(,1.0](,1.0] x ≤ 1.0x ≤ 1.0 最大バージョン (示されている値を含む)Maximum version, inclusive
(,1.0)(,1.0) x < 1.0x < 1.0 最大バージョン (示されている値を含まない)Maximum version, exclusive
[1.0,2.0][1.0,2.0] 1.0 ≤ x ≤ 2.01.0 ≤ x ≤ 2.0 正確な範囲 (示されている値を含む)Exact range, inclusive
(1.0,2.0)(1.0,2.0) 1.0 < x < 2.01.0 < x < 2.0 正確な範囲 (示されている値を含まない)Exact range, exclusive
[1.0,2.0)[1.0,2.0) 1.0 ≤ x < 2.01.0 ≤ x < 2.0 示されている値を含む最小バージョンと示されている値を含まない最大バージョンの組み合わせMixed inclusive minimum and exclusive maximum version
(1.0)(1.0) 無効なinvalid 無効なinvalid

PackageReference 形式を使用する場合、NuGet では、番号の Major、Minor、Patch、およびプレリリース サフィックス部分にワイルドカード表記 * を使用できます。When using the PackageReference format, NuGet also supports using a wildcard notation, *, for Major, Minor, Patch, and pre-release suffix parts of the number. packages.config 形式では、ワイルドカードはサポートされていません。Wildcards are not supported with the packages.config format.

注意

PackageReference のバージョン範囲には、プレリリース バージョンが含まれます。Version ranges in PackageReference include pre-release versions. 仕様により、浮動バージョンでは、オプトインしない限りプレリリース バージョンは解決されません。By design, floating versions do not resolve prerelease versions unless opted into. 関連する機能要求の状態については、問題 6434 に関するページをご覧ください。For the status of the related feature request, see issue 6434.

使用例Examples

プロジェクト ファイル、packages.config ファイル、.nuspec ファイル内では、パッケージの依存関係のバージョンまたはバージョン範囲を必ず指定します。Always specify a version or version range for package dependencies in project files, packages.config files, and .nuspec files. バージョンまたはバージョン範囲を指定しない場合、NuGet 2.8.x 以前では依存関係を解決するときに利用可能な最新のパッケージ バージョンが選択されますが、NuGet 3.x 以降ではパッケージの最小バージョンが選択されます。Without a version or version range, NuGet 2.8.x and earlier chooses the latest available package version when resolving a dependency, whereas NuGet 3.x and later chooses the lowest package version. バージョンまたはバージョン範囲を指定すると、この不確実性が回避されます。Specifying a version or version range avoids this uncertainty.

プロジェクト ファイル内の参照 (PackageReference)References in project files (PackageReference)

<!-- Accepts any version 6.1 and above. -->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any 6.x.y version. -->
<PackageReference Include="ExamplePackage" Version="6.*" />
<PackageReference Include="ExamplePackage" Version="[6,7)" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. -->
<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. -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and higher. -->
<PackageReference Include="ExamplePackage" Version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

packages.config 内の参照:References in packages.config:

packages.config では、すべての依存関係が、パッケージの復元時に使用される正確な version 属性と共に一覧表示されます。In packages.config, every dependency is listed with an exact version attribute that's used when restoring packages. allowedVersions 属性は、パッケージの更新先にできるバージョンを制限するために、更新操作中にのみ使用されます。The allowedVersions attribute is used only during update operations to constrain the versions to which the package might be updated.

<!-- 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 ファイル内の参照References in .nuspec files

<dependency> 要素内の version 属性は、依存関係で許容される範囲のバージョンを示します。The version attribute in a <dependency> element describes the range versions that are acceptable for a dependency.

<!-- 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)" />

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

注意

これは、NuGet 3.4 以降での破壊的変更です。This is a breaking change for NuGet 3.4 and later.

インストール、再インストール、または復元操作中にリポジトリからパッケージを取得すると、NuGet 3.4 以降ではバージョン番号が次のように扱われます。When obtaining packages from a repository during install, reinstall, or restore operations, NuGet 3.4+ treats version numbers as follows:

  • 先頭のゼロはバージョン番号から削除されます。Leading zeroes are removed from version numbers:

      1.00 is treated as 1.0
      1.01.1 is treated as 1.1.1
      1.00.0.1 is treated as 1.0.0.1
    
  • バージョン番号の 4 番目の部分のゼロは省略されますA zero in the fourth part of the version number will be omitted

      1.0.0.0 is treated as 1.0.0
      1.0.01.0 is treated as 1.0.1
    

pack 操作と restore 操作では、可能な限りバージョンが正規化されます。pack and restore operations normalize versions whenever possible. 既にビルドされているパッケージの場合、この正規化はパッケージ自体のバージョン番号には影響しません。依存関係を解決するときに NuGet によってバージョンが照合される方法にのみ影響します。For packages already built, this normalization does not affect the version numbers in the packages themselves; it affects only how NuGet matches versions when resolving dependencies.

ただし、NuGet パッケージ リポジトリでは、これらの値を NuGet と同じように処理して、パッケージのバージョンが重複しないようにする必要があります。However, NuGet package repositories must treat these values in the same way as NuGet to prevent package version duplication. したがって、パッケージのバージョン 1.0 を含むリポジトリでは、バージョン 1.0.0 を別の異なるパッケージとしてホストすることはできません。Thus a repository that contains version 1.0 of a package should not also host version 1.0.0 as a separate and different package.