在專案中包含 NuGet 套件Including a NuGet package in your project

NuGet 是進行 .NET 開發的最受歡迎套件管理員,並內建於 Visual Studio for Mac 以及 Windows 上的 Visual Studio。NuGet is the most popular package manager for .NET development and is built in to Visual Studio for Mac and Visual Studio on Windows. 您可以使用任一 IDE 來搜尋套件,並將其新增至 Xamarin.iOS 和 Xamarin.Android 專案。You can search for and add packages to your Xamarin.iOS and Xamarin.Android projects using either IDE.

本文件查看如何在專案中包含 NuGet 套件,並示範讓處理序順暢處理的工具鏈。This document looks at how to include a NuGet package in a project and demonstrates the tool chain that makes the process seamless.

Visual Studio for Mac 中的 NuGetNuGet in Visual Studio for Mac

為了示範 NuGet 套件功能,我們會先逐步建立新的應用程式,並在其中新增套件。To demonstrate the NuGet package functionality we'll first walk through creating a new application and adding a package to it. 接著,我們將討論可協助管理套件的 IDE 功能。Then we'll discuss the IDE features that help manage packages.

建立新專案Create a new project

首先,建立名為 HelloNuget 的專案,如下所示。First, create a project named HelloNuget as illustrated below. 此範例顯示「iOS 單一檢視應用程式」範本,但會使用任何支援的專案類型:This example shows the iOS Single View Application template, but any supported project type would work:

建立新 iOS 專案

新增套件Adding a Package

在 Visual Studio for Mac 中開啟專案時,以滑鼠右鍵按一下 [Solution Pad] 中的 [套件] 資料夾,然後選取 [新增套件]:With the project open in Visual Studio for Mac, right-click on the Packages folder in the Solution Pad and select Add Packages...:

新增 NuGet 套件內容動作

這會啟動 [新增套件] 視窗。This launches the Add Packages... window. 確定 [來源] 下拉式清單設定為 nuget.orgEnsure that the Source drop-down, is set to nuget.org:

來源清單下拉式清單

開啟視窗時,會從預設套件來源載入套件清單:nuget.org。初始結果如下:When the window opens it will load a list of packages from the default package source: nuget.org. The initial results look like this:

列出 NuGet 套件

使用右上角的 [搜尋] 方塊來尋找特定套件,例如 azureUse the search box in the top-right corner to find a specific package, for example azure. 當您發現想要使用的套件時,請選取它,然後按一下 [新增套件] 按鈕開始安裝。When you've found a package that you wish to use, select it and click the Add Package button to begin installation.

新增 Azure NuGet 套件Add Azure NuGet Package

套件在下載之後就會新增至您的專案。Once the package has been downloaded it will be added to your project. 會如下變更方案:The solution will change as follows:

  • [參考] 節點將包含屬於 NuGet 套件一部分的所有組件清單。The References node will contain a list of all the assemblies that are part of a NuGet package.
  • [套件] 節點會顯示您已下載的每個 NuGet 套件。The Packages node displays each NuGet package that you have downloaded. 您可以更新或移除此清單中的套件。You can update or remove a package from this list.
  • packages.config 檔案將會新增至專案。A packages.config file will be added to the project. IDE 使用此 XML 檔案來追蹤這個專案中所參考的套件版本。This XML file is used by the IDE to track which package versions are referenced in this project. 這個檔案不應該手動進行編輯,但您應該將它保留在版本控制中。This file should not be hand-edited, but you should keep it in version control. 請注意,可以使用 project.json 檔案,而不要使用 packages.config 檔案。Note that a project.json file can be used instead of a packages.config file. project.json 檔案是支援可轉移還原之 NuGet 3 引進的新套件檔案格式。The project.json file is a new package file format introduced with NuGet 3, which supports transitive restore. 如需 project.json 的詳細資訊,請參閱 NuGet 文件More detailed information on project.json can be found in the NuGet documentation. 需要手動新增 project.json 檔案,以及先關閉並重新開啟專案,再將 project.json 檔案用於 Visual Studio for Mac 中。The project.json file needs to be added manually and the project closed and re-opened before the project.json file is used in Visual Studio for Mac.

使用 NuGet 套件Using NuGet Packages

新增 NuGet 套件並更新專案參考之後,即可針對 API 進行程式設計,就像任何專案參考一樣。Once the NuGet package has been added and the project references updated you can program against the APIs as you would with any project reference.

確定您將任何必要 using 指示詞新增至檔案頂端:Ensure that you add any required using directives to the top of your file:

using Newtonsoft.Json;

大部分 NuGet 都會提供其他資訊,例如 Nuget 來源的 README 或專案頁面連結。Most NuGet provide additional information, such as a README or Project page link to the Nuget source. 您通常可以在 [新增套件] 頁面的套件簡介上找到此項目的連結:You can normally find a link to this in the package blurb on the Add Packages page:

檢視專案頁面連結View Project Page link

套件更新Package Updates

以滑鼠右鍵按一下 [套件] 節點,或分別以滑鼠右鍵按一下每個元件,即可一次完成所有套件更新。Package updates can be done either all at once, by right-clicking on the Packages node, or individually on each component.

以滑鼠右鍵按一下 [套件] 來存取操作功能表:Right-click on Packages to access the context menu:

套件功能表

  • 新增套件 - 開啟視窗,將更多套件新增至專案。Add Packages - Opens the window to add more packages to the project.
  • 更新 - 檢查每個套件的來源伺服器,然後下載任何較新版本。Update - Checks the source server for each package and downloads any newer versions.
  • 還原 - 下載任何遺漏的套件 (不會將現有套件更新為較新版本)。Restore - Downloads any missing packages (without updating existing packages to newer versions).

方案層級也會提供 [更新] 和 [還原] 選項,而且這些選項會影響方案中的所有專案。Update and Restore options are also available at the Solution level, and affect all the projects in the solution.

您也可以以滑鼠右鍵按一下個別套件,來存取操作功能表:You can also right-click on individual packages to access a context menu:

套件功能表

  • 版本號碼 - 版本號碼是停用的功能表項目;這僅供參考。Version Number - The version number is a disabled menu item - it is provided for informational purposes only.
  • 更新 - 檢查來源伺服器,然後下載較新版本 (如果已存在)。Update - Checks the source server and downloads a newer version (if it exists).
  • 移除 - 從這個專案中移除套件,並從專案的參考中移除相關組件。Remove - Removes the package from this project and removes the relevant assemblies from the project's References.

新增套件來源Adding Package Sources

一開始會從 nuget.org 擷取可用於安裝的套件。不過,您可以將其他套件位置新增至 Visual Studio for Mac。Packages available for installation are initially retrieved from nuget.org. However, you can add other package locations to Visual Studio for Mac. 這適用於測試您自己正在開發的 NuGet 套件,或在公司或組織內使用私用 NuGet 伺服器。This can be useful for testing your own NuGet packages under development, or to use a private NuGet server inside your company or organization.

在 Visual Studio for Mac 中,巡覽至 [Visual Studio] > [喜好設定] > [NuGet] > [來源] 來檢視和編輯套件來源清單。In Visual Studio for Mac, navigate to Visual Studio > Preferences... > NuGet > Sources to view and edit the list of package sources. 請注意,來源可以是遠端伺服器 (由 URL 指定) 或本機目錄。Note that sources can be a remote server (specified by a URL) or a local directory.

套件來源

按一下 [新增] 設定新來源。Click Add to set-up a new source. 輸入套件來源的易記名稱和 URL (或檔案路徑)。Enter a friendly name and the URL (or file path) to the package source. 如果來源是安全網頁伺服器,也請輸入使用者名稱和密碼,否則請將這些項目留白:If the source is a secure web server, enter the username and password as well, otherwise leave these entries blank:

新增套件來源

搜尋套件時,可以選取不同的來源:Different sources can then be selected when searching for packages:

新增套件來源

版本控制Version Control

NuGet 文件討論 using NuGet without committing packages to source control (在未將套件認可到原始檔控制的情況下使用 NuGet)。The NuGet documentation discusses using NuGet without committing packages to source control. 如果您不想要將二進位檔和未使用的資訊儲存至原始檔控制,則可以設定 Visual Studio for Mac 自動從伺服器還原套件。If you prefer not to store binaries and unused information in source control, you can configure the Visual Studio for Mac to automatically restore packages from the server. 這表示,開發人員第一次從原始檔控制擷取專案時,Visual Studio for Mac 將會自動下載並安裝必要的套件。This means that when a developer retrieves the project from source control for the first time, the Visual Studio for Mac will automatically download and install the required packages.

自動還原套件

如需如何排除 packages 目錄不進行追蹤的詳細資料,請參閱特定原始檔控制文件。Refer to your particular source control documentation for details on how to exclude the packages directory from being tracked.