共用方式為

套件版本控制

  • 發行項

特定套件一律會使用其套件標識碼和確切的版本號碼來參考。 例如，nuget.org 上的 Entity Framework 有數十個可用的特定套件，範圍從版本 4.1.10311到 6.1.3 版本，以及各種發行前版本，例如 6.2.0-beta1。

建立套件時，您會指派具有選擇性發行前版本文字後綴的特定版本號碼。 另一方面，取用套件時，您可以指定確切的版本號碼或可接受的版本範圍。

下列檔遵循 NuGet 4.3.0+ 和 Visual Studio 2017 15.3+版支援的 Semantic Versioning 2.0.0 標準。 舊版用戶端不支援 SemVer v2.0.0 的特定 語意。

在本主題中：

版本基本概念

特定版本號碼的格式為 Major.Minor.Patch[-Suffix]，其中元件具有下列意義：

  • 主要：重大變更
  • 次要：新功能，但回溯相容
  • Patch：僅回溯相容 Bug 修正
  • -Suffix（選擇性）：連字元後面接著表示發行前版本的字串（遵循 語意版本設定或 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 檔案中，一律指定套件相依性的版本或版本範圍。 在沒有版本或版本範圍的情況下，解析相依性時，不保證還原結果一致。 除非您知道相容性問題，否則請避免將上限指定至您不擁有的套件。 版本範圍的上限會損害採用，勸阻取用者取得相依性的寶貴更新，在某些情況下，可能會導致他們使用不支援的相依性版本。

項目檔中的參考 （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 only version 6.1.0. -->
<PackageReference Include="ExamplePackage" Version="[6.1.0]" />

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

檔案中的 參考

<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 騎手
  • 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 相等。