套件版本控制

  • 發行項

您一律必須使用套件的套件識別碼與確切版本號碼來參考特定套件。 例如，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 的特定語意。

本主題內容：

版本基本概念

特定版本號碼的格式為「主要.次要.修補程式[-尾碼]」，其中的元件具有下列意義：

  • 主要：重大變更
  • 次要：新功能，但回溯相容
  • 修補程式：僅回溯相容 Bug 修正
  • -後綴 （選擇性）：連字元後面接著表示發行前版本的字串（遵循 語意版本設定或 SemVer 慣例）。

範例：

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

重要

nuget.org 會拒絕任何缺少確切版本號碼的套件上傳。 您必須在 .nuspec 中，或在用來建立套件的專案檔中指定版本。

發行前版本

就技術上而言，套件建立者可以使用任何字串作為尾碼來表示發行前版本，因為 NuGet 會將任何此類版本視為發行前版本，而且不會進行任何其他解讀。 也就是說，NuGet 會在牽涉到的任何 UI 中顯示完整版本字串，尾碼之意義的任何解讀，都保留給取用者。

話雖如此，套件開發人員通常會遵循公認的命名慣例：

  • -alpha：Alpha 版本，通常用於進行中工作和實驗。
  • -beta：搶鮮版 (Beta) 版本，通常是計劃發行的功能完整版本，但可能包含已知的 Bug。
  • -rc：候選版，除非出現重大的 Bug，不然通常是準最終版本 (穩定版)。

依優先順序排序版本時，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 檔案中的套件相依性指定版本或版本範圍。 如果沒有版本或版本範圍，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)" />

標準化版本號碼

注意

這是 NuGet 3.4+ 的重大變更。

在安裝、重新安裝或還原作業期間從存放庫取得套件時，NuGet 3.4+ 會依照下列方式來對待版本號碼：

  • 系統會將前置零從版本號碼移除：

    • 1.00 被視為 1.0
    • 1.01.1 被視為 1.1.1
    • 1.00.0.1 會被視為 1.0.0.1

  • 系統會移除在版本號碼第四部分中的零

    • 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 為零，則會從正規化版本字串中省略它。
  2. NuGetVersion 只需要定義主要區段。 所有其他專案都是選擇性的，相當於零。 這表示 1、 1.0、 1.0.0和 1.0.0.0 都已接受且相等。
  3. NuGetVersion 會針對發行前版本元件使用不區分大小寫的字串比較。 這表示 1.0.0-alpha 和 1.0.0-Alpha 相等。