將套件新增到 .NET 專案

  • 2 分鐘

.NET 隨附許多核心程式庫，這些程式庫可處理從管理檔案到 HTTP 到壓縮檔案等作業。 同時也存在龐大的第三方程式庫生態系統。 您可以使用 NuGet (.NET 套件管理員) 來安裝這些程式庫，並在您的應用程式中加以使用。

.NET 與其生態系統經常使用「相依性」一詞。 套件相依性是第三方程式庫。 其為可完成某種作業且您可將之新增至您應用程式、可重複使用的程式碼片段。 第三方程式庫是您的應用程式需「相依」才能運作的項目，因此有「相依性」一詞。

您可以將第三方程式庫想成是套件，而且其儲存在存放庫中。 套件是由一或多個程式庫所組成，您可以將其新增至應用程式，以便充分利用其功能。

我們會將焦點放在套件相依性上。 .NET 專案也可以有其他類型的相依性，包含架構、分析器、專案參考、共用的專案相依性，以及套件相依性。

決定您是否需要套件

您要如何知道專案是否需要套件？ 這是一個涉及幾個因素的複雜問題：

  • 取得更好的程式碼: 例如，您可以問問自己是否正在處理安全性之類的工作，且正嘗試實作驗證與授權。 處理這種工作時，您必須「正確」執行才能保護您與客戶的資料。 有許多開發人員使用的標準模式與程式庫。 這些程式庫會實作您可能一律需要的功能，並在問題發生時修補。 您應該使用這類程式庫，而不是自行建立程式庫。 您自己也不太可能撰寫程式碼，因為存在許多需要考慮的邊緣案例。
  • 節省時間: 您可以自行建置大部分的工作，例如公用程式或 UI 元件庫，但這需要時間。 即使結果可以與外面所提供的現成品相提並論，在沒有必要的情況下，重複進行撰寫此程式碼的工作也不是運用時間的良好方式。
  • 維護：所有程式庫和應用程式早晚都需要進行維護。 維護牽涉到新增功能和修正錯誤 (Bug)。 讓您或您的小組花費時間來維護程式庫好呢，還是讓開放原始碼軟體小組來處理會更好?

評估套件

安裝程式庫之前，您可以檢查其依賴的相依性。 這些相依性可能會鼓勵您使用該套件，也可能會阻止您。 以下是為專案選取相依性時應考慮的一些因素：

  • 大小: 相依性數目可能會導致大量的磁碟使用量。 如果您的頻寬有限或有其他硬體限制，此因素可能會是一大顧慮。
  • 授權: 您必須確定授與程式庫的授權能涵蓋預定的用途，無論是商業、個人或學術用途。
  • 作用中的維修: 如果您的套件依賴已淘汰或長時間未更新的相依性，這可能會造成問題。

您可以先前往 https://www.nuget.org/packages/<package name> 以深入了解套件，然後再進行安裝。 此 URL 會帶您前往該套件的詳細頁面。 選取 [相依性] 下拉式清單，以查看其運作需要依賴哪些套件。

列出的相依性數目可能無法說明全部事實。 若您下載某個套件，則可能會有包含數十種套件的套件相依性。 這是為什麼？ 每個套件都有一份相依性清單。 為了確保您可以使用某個套件，當您執行 dotnet add package <package name> 命令時，系統會耙梳所有相依性並加以下載。

安裝套件

有數種安裝這些套件的方式。 Visual Studio 與 Visual Studio for Mac 中有適用於套件管理員的內建命令列與圖形化使用者介面。 您可以手動將套件參考新增至專案檔，或透過命令列介面 (CLI) 工具 (例如 Paket 或 .NET Core CLI) 進行安裝。

在此課程模組中，我們將使用內建的 .NET Core CLI 來安裝套件。 您可透過在終端機中叫用命令，將套件新增至 .NET 專案。 一般的安裝命令看起來就像這樣: dotnet add package <name of package>。 當執行 add package 命令時，命令列工具會連線至全域登錄並擷取套件，然後將其儲存於所有專案都可使用的快取資料夾位置中。

在您安裝並建置專案之後，系統會將參考新增至您的偵錯或發行資料夾。 您的專案目錄看起來會像這樣:

-| bin/
---| Debug/
------| net3.1
--------| <files included in the dependency>

尋找套件

個別開發人員可能會使用 NuGet.org 的全域登錄，來尋找並下載其應用程式所需的套件。 公司可能會制定策略，以限制可以使用的套件以及要在哪裡尋找那些套件。

Screenshot of NuGet.org showing a list of popular packages.

套件可能位於許多不同位置。 其中一些來源可能是公開提供，而有些可能會受到限制，而且只有特定公司的員工可以存取。 以下是套件可能所在的一些位置：

  • 登錄: 範例可能是如 NuGet.org 登錄的全域登錄。 您可以裝載自己的登錄，其可以是私人或公用的。 GitHub 與 Azure DevOps 等服務會提供私人登錄。
  • 檔案: 您可以從本機資料夾安裝套件。 當您嘗試開發自己的 .NET 程式庫並希望在本機測試套件，或基於某些原因您不想使用登錄時，從套件進行安裝是常見的情況。

Diagram that illustrates the relationship between package creators, package hosts, and package consumers.

NuGet 登錄與 dotnet 工具

當執行 dotnet add package <name of dependency> 時，.NET 會前往稱為 NuGet.org 登錄的全域登錄，並尋找要下載的程式碼。 其位於 https://nuget.org。如果您使用瀏覽器造訪此頁面，也可以瀏覽此頁面以尋找套件。 每個套件都有您可以前往的專屬網站。

Screenshot of the landing page for a NuGet package.

在這些網站上，您可以深入了解原始程式碼的所在位置。 您也可以找到如下載計量的資訊，以及維護的相關資訊。

Screenshot of information and metrics on a NuGet package.

.NET 命令

到目前為止，您已了解如何使用 .NET Core CLI 來安裝相依性。 但此工具可以執行更多工作。

.NET Core CLI 有相當多命令。 這些命令可協助您進行如安裝套件、撰寫套件，以及將 .NET 專案初始化等工作。 您不需要詳細了解所有命令。 當您開始使用 .NET 時，可能只會使用部分命令。 隨著擴展 .NET 的使用，您可能會使用越來越多來自各種類別的命令。

為了協助您記住命令的作用，將這些命令想成屬於各種類別會很有幫助：

  • 管理相依性: 此類別中的命令涵蓋安裝、移除、在套件安裝之後清除，以及更新套件。
  • 執行程式: .NET Core 工具可協助您管理應用程式開發中的流程。 應用程式流程的範例為執行測試、建置程式碼，以及執行移轉命令來升級專案。
  • 編輯和發行套件: 數個命令可協助您進行像是建立壓縮的套件，以及將套件推送至登錄等工作。

如果您需要所有命令的詳細清單，請在終端機中輸入 dotnet --help。

如何安裝套件

使用 dotnet add package <dependency name> 命令來安裝要用來作為應用程式之一部分的一般相依性。

注意

您能以「全域」方式安裝某些套件。 這些套件不會匯入專案中。 基於這個原因，許多全域套件都是 CLI 工具或範本。 您也可以從套件存放庫安裝這些全域工具。 使用 dotnet tool install <name of package> 命令來安裝工具。 使用 dotnet new -i <name of package> 命令來安裝範本。

安裝之後

已安裝的套件會列在您 .csproj 檔案的 dependencies 區段中。 如果想要查看資料夾中有哪些套件，您可以輸入 dotnet list package。

Project 'DotNetDependencies' has the following package references
   [net8.0]:
   Top-level Package      Requested   Resolved
   > Humanizer            2.7.9       2.7.9

此命令只會列出最上層套件，而非那些我們稱為「可轉移的套件」之套件的相依性。 這比較適合快速查看。 如果您想要更深入的檢視，則可以列出所有可轉移的套件。 當您這麼做時，list 命令看起來就像下面這樣:

dotnet list package --include-transitive

包含可轉移的套件會使您看見相依性與您所安裝的所有套件。 如果您執行 dotnet list package --include-transitive，您可能會得到下列輸出:

Project 'DotNetDependencies' has the following package references
   [net8.0]:
   Top-level Package      Requested   Resolved
   > Humanizer            2.7.9       2.7.9

   Transitive Package               Resolved
   > Humanizer.Core                 2.7.9
   > Humanizer.Core.af              2.7.9
   > Humanizer.Core.ar              2.7.9
   > Humanizer.Core.bg              2.7.9
   > Humanizer.Core.bn-BD           2.7.9
   > Humanizer.Core.cs              2.7.9
   ...

還原相依性

建立或複製專案時，直到您建置專案之前，系統將不會下載或安裝其所包含的相依性。 您可透過執行 dotnet restore 命令來手動還原相依性和專案檔中指定的專案特定工具。 在大部分情況下，您不需要明確地使用該命令。 當您執行如 new、build 與 run 等命令時，NuGet 還原會在必要的情況下以隱含方式執行。

清除相依性

遲早，您可能會意識到自己不再需要套件，或者您可能會意識到您安裝的套件不是您需要的套件。 您也許已找到能以更好的方式完成工作的套件。 不論原因為何，您都應該移除不使用的相依性。 這麼做可讓一切保持整潔。 此外，相依性也會佔用空間。

若要將套件從專案移除，請使用 remove 命令，如下所示: dotnet remove package <name of dependency>。 此命令會從您專案的 .csproj 檔案中移除該套件。