管理 .NET 專案中的相依性更新

  • 4 分鐘

您遲早都需要更新至新版的程式庫。 可能是因為某個函式標示為已淘汰，也可能是因為您所使用套件的更新版本中有新功能。

在您嘗試更新程式庫之前，請先考慮下列事項：

  • 更新類型：可用的更新類型為何？ 其是否為小型錯誤 (Bug) 修正？ 其是否會新增您需要的新功能？ 其是否會中斷您的程式碼？ 您可以使用稱為「語意化版本控制系統」的系統來傳達更新類型。 程式庫版本號碼的表達方式，可以向開發人員傳達其正在處理的更新類型。
  • 我的專案設定是否正確：您可以透過某種方式設定 .NET 專案，以便只取得您想要的更新類型。 只有在特定類型的更新可供使用時，您才會執行更新。 我們建議使用此方法，因為您不會遇到意外狀況。
  • 專案相依性：持續管理專案相依性涉及注意可能發生的問題。 例如，偵測到弱點時就會促成問題。 在理想的情況下，將會發行可供您下載的修補程式。 .NET Core 工具可協助您在程式庫上執行「稽核」，以找出是否有應更新的套件。 此工具也可協助您採取適當的動作來修正問題。

使用語意化版本控制系統

有個稱為 語意化版本控制系統 的行業標準，這是您表達您或其他開發人員準備要引入程式庫之變更類型的方式。 語意化版本控制系統的運作方式是確保套件具有版本號碼，且該版本號碼已分成這些部分：

  • 主要版本：最左邊的數字。 例如，其為 1.0.0 中的 1。 變更此數字表示您可以預期程式碼中會出現中斷性變更。 您可能需要重寫部分程式碼。
  • 次要版本：中間的數字。 例如，其為 1.2.0 中的 2。 變更此數字表示已新增功能。 您的程式碼應該仍可正常運作。 接受該更新通常是安全的。
  • 修補檔版本：最右邊的數字。 例如，其為 1.2.3 中的 3。 變更此數字表示已套用會修正程式碼中應正常運作之內容的變更。 接受該更新應該是安全的。

下表說明每個版本類型的版本號碼變更方式：

類型 發生什麼情況
主要版本 1.0.0 變更為 2.0.0
次要版本 從 1.1.1 變更為 1.2.0
修補程式版本 從 1.0.1 變更為 1.0.2

許多公司與開發人員皆採用此系統。 若想要發佈套件，並將其推送至 NuGet 登錄，則應該遵循預期的語意化版本控制系統。 即使只會從 NuGet 登錄下載套件，您也可以預期這些套件會遵循語意化版本控制系統。

對套件進行變更可能會導致風險，包括 Bug 可能會對業務造成傷害的風險。 某些風險可能需要您重寫部分程式碼。 重寫程式碼需要花費時間和成本。

更新方法

身為 .NET 開發人員，您可以向 .NET 傳達所要的更新行為。 請以風險為基礎考量更新。 以下是一些方法：

  • 主要版本：我可以接受最新的主要版本一推出馬上更新。我接受可能需要在我這端變更程式碼的事實。
  • 次要版本：我可以接受新增新功能。 我不能接受會造成中斷的程式碼。
  • 修補檔版本：我唯一可以接受的就是錯誤 (Bug) 修正。

若您正在管理新的或較小型的 .NET 專案，則可較寬鬆地定義更新策略。 例如，您可以隨時更新至最新版本。 針對更複雜的專案，會有更多的細微差異，但我們會留到未來的課程模組中再加以說明。

一般來說，您要更新的相依性越小，其所擁有的相依性就越少，而且更新程序極有可能會很容易。

設定更新的專案檔

新增一或多個相依性時，請考慮設定專案檔，以便在還原、建置或執行專案時取得可預測的行為。 您可以傳達您想要針對套件採取的方法。 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,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) 無效 無效

NuGet 也支援將浮動版本標記法用於數字的主要、次要、修補程式與發行前版本尾碼部分。 此標記法為星號 (*)。 例如，版本規格 6.0.* 表示「使用最新的 6.0.x 版」。在另一個範例中，4.* 表示「使用最新的 4.x 版本」。使用浮動版本可減少專案檔的變更，同時持續更新最新版的相依性。

注意

建議安裝特定版本，而非使用任何浮動標記法。 除非明確要求相依性的更新，否則安裝特定版本可確保您的組建是可重複的。

當您使用浮動版本時，NuGet 會解析符合版本模式的最新套件版本。 在下列範例中，6.0.* 會取得以 6.0 開頭的最新套件版本。 該版本是 6.0.1。

Diagram showing choosing the latest version when a floating version is requested.

以下是一些可針對主要、次要或修補程式版本設定的範例：

<!-- Accepts any version 6.1 and later. -->
<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 later version, 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 earlier than 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, we don't recommend this form because determining the earliest version can be difficult. -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

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

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

尋找並更新過期的套件

dotnet list package --outdated 命令會列出過時的套件。 此命令可協助您了解何時有較新版本的套件可供使用。 以下是此命令的一般輸出：

Top-level Package      Requested   Resolved   Latest
> Humanizer            2.7.*       2.7.9      2.8.26

以下是輸出中欄名稱的意義：

  • Requested：您已指定的版本或版本範圍。
  • Resolved: 已針對專案下載的實際版本，其符合指定的版本。
  • Latest：可從 NuGet 更新的最新版本。

建議的工作流程是依此順序執行下列命令：

  1. 執行 dotnet list package --outdated。 此命令會列出所有過期的套件。 其會提供 Requested、Resolved 和 Latest 資料行中的資訊。
  2. 執行 dotnet add package <package name>。 若執行此命令，其將嘗試更新為最新版本。 您也可以選擇性地傳遞 --version=<version number/range>。