使用 NuGet 套件還原還原套件

  • 發行項

NuGet 套件還原會還原項目檔或 packages.config 檔案中列出的所有專案的相依性。 您可以使用 、、 dotnet restoremsbuild -t:restore或 透過 Visual Studio 手動nuget restore還原套件。 dotnet build和 dotnet run 命令會自動還原套件，而且您可以設定 Visual Studio 在建置項目時自動還原套件。

為了提升更簡潔的開發環境並減少存放庫大小，套件還原可讓所有專案的相依性都可供使用，而不需要將它們儲存在原始檔控制中。 若要設定原始檔控制存放庫以排除套件二進位檔，請參閱 套件和原始檔控制。

套件還原行為

套件還原會嘗試將所有套件相依性安裝到符合<PackageReference>項目檔中的 狀態，例如 .csproj 或 <package>packages.config 檔案中的 s。 套件還原會先視需要安裝專案的直接相依性，然後在整個相依性關係圖中安裝那些套件的任何相依性。

如果尚未安裝所需的套件，NuGet 會先嘗試從本機 全域套件或 HTTP 快取資料夾擷取它。 如果套件不在本機資料夾中，NuGet 會嘗試從 Visual Studio 中設定的所有來源下載該套件，位置為 [工具>選項>] NuGet 封裝管理員> Package 來源。

在還原期間，NuGet 會忽略套件來源的順序，並使用回應要求之第一個來源的套件。 如果還原失敗，NuGet 不會指出失敗，直到檢查所有來源為止。 NuGet 接著只會報告清單中的最後一個來源失敗。 錯誤表示套件未出現在任何來源上，即使未個別列出其他失敗也一樣。

如需 NuGet 行為的詳細資訊，請參閱 常見的 NuGet 組態。

還原套件

如果您的項目檔或 packages.config 檔案中的套件參考正確，請使用您慣用的工具來還原套件：

成功還原之後：

  • 針對使用 <PackageReference>的專案，套件會出現在本機 global-packages 資料夾中，並重新建立專案 obj/project.assets.json 檔案。
  • 對於使用 packages.config 的專案，套件會出現在專案的 packages 資料夾中。
  • 專案現在應可順利建置。

如果您的項目檔或 packages.config 檔案中的套件參考不正確，且不符合您所需的狀態，請安裝或更新正確的套件，而不是使用套件還原。

如果您在執行套件還原之後遺失套件或套件相關錯誤，例如 方案總管 中的錯誤圖示，請遵循針對套件還原錯誤進行疑難解答中的指示，或重新安裝或更新套件。 在 Visual Studio 中，封裝管理員 主控台提供數個選項來重新安裝套件。 如需詳細資訊，請參閱 使用 Package-Update。

在 Visual Studio 中還原套件

在 Windows 上的 Visual Studio 中，您可以自動或手動還原套件。 首先，透過工具>選項>設定套件還原 NuGet 封裝管理員。

設定 Visual Studio 套件還原選項

在 [工具>選項>][NuGet 封裝管理員> General 設定下列套件還原選項。

Screenshot that shows the NuGet Package Manager options.

允許 NuGet 下載遺漏的套件

選取 [允許 NuGet 下載遺漏的套件 ]，以啟用套件還原和 [ 還原 NuGet 套件 ] 命令。 此選取專案會將全域 NuGet.Config 檔案的 packageRestore 區段中，設定True為 ，位於 Windows 上的 %AppData%\Roaming\NuGet 或 Mac 或 Linux 上的 ~/.nuget/NuGet/。packageRestore/enabled

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

注意

若要全域覆寫 packageRestore/enabled 設定，您可以在開啟Visual Studio或啟動組建之前，將環境變數 EnableNuGetPackageRestore 設定為 True 或 False。

若要為計算機上的所有使用者啟用或停用套件還原，您可以將組態設定新增至 Windows 中的全域 NuGet.Config 檔案，位於 %ProgramData%\NuGet\Config，有時位於特定< IDE>\<Version>\<SKU> Visual Studio 資料夾下，或在 ~/.local/share 的 Mac/Linux 中。 個別使用者接著可以視需要選擇性地啟用專案層級的還原。 如需 NuGet 如何排定多個組態檔優先順序的詳細資料，請參閱常見的 NuGet 行為。

重要

如果您直接編輯 packageRestore NuGet.Config 中的設定，請重新啟動 Visual Studio，讓 [選項] 顯示目前的值。

在建置期間自動檢查遺漏的套件

選取 [ 在 Visual Studio 建置期間自動檢查遺漏的套件]，以在從 Visual Studio 執行組建時自動還原任何遺漏的套件。 此設定不會影響從 MSBuild 命令列執行的組建。 這個選取範圍會將 packageRestore/automatic NuGet.Config 檔案區段中的 設定TruepackageRestore設為 。

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

針對非 SDK 樣式的專案，您必須選取 [允許 NuGet 下載遺漏的套件 ]，以及在 Visual Studio中的 [選項 ] 中建置期間自動檢查遺漏的套件，以啟用自動還原。

選擇預設套件管理格式

NuGet 有兩種套件管理格式：PackageReference 和 packages.config。從 [套件管理] 下方的下拉式清單中選取您想要使用的格式。 您也可以選取是否要在第一次安裝套件時允許選取格式。

注意

  • 如果專案不支援這兩種套件管理格式，NuGet 會使用與專案相容的套件管理格式，這可能不是您在選項中設定的預設值。 NuGet 接著不會提示您在第一次安裝時選取，即使您選取了該選項也一樣。

  • 如果您使用 封裝管理員 Console 在專案中安裝第一個套件，則 NuGet 不會提示選取格式，即使在 [選項] 中選取該選項也一樣。

手動或自動還原套件

在 [選項] 中啟用套件還原之後，您可以在 方案總管 中以滑鼠右鍵按兩下解決方案，然後選取 [還原 NuGet 套件] 以隨時還原套件。

如果您在 [選項] 中啟用自動還原，當您從範本建立專案或建置專案時，會自動進行套件還原。 針對 NuGet 4.0+，當您變更 SDK 樣式專案時，還原也會自動發生。

對於使用 <PackageReference>的專案，您可以在 [相依性>套件] 底下看到 Visual Studio 中的套件參考 方案總管。 當您手動還原或執行組建在 方案總管 中顯示錯誤圖示時，未正確安裝的套件。 以滑鼠右鍵按兩下項目，選取 [管理 NuGet 套件]，然後使用 NuGet 封裝管理員 卸載並重新安裝受影響的套件。 如需詳細資訊，請參閱 重新安裝和更新套件。

如果您看到錯誤 此項目參考此計算機上遺失的 NuGet 套件，或 必須還原一或多個 NuGet 套件，但無法因為尚未授與同意，請確定您已啟用自動還原。 針對較舊的專案，請參閱 移轉至自動封裝還原。 另請參閱 針對套件還原錯誤進行疑難解答。

使用 dotnet CLI 還原

dotnet restore 命令會使用 還原項目檔所列出的<PackageReference>套件。 如需詳細資訊，請參閱 項目檔中的 PackageReference。

.NET Core 2.0 和更新版本 dotnet build 和 dotnet run 命令會自動還原套件。 從 NuGet 4.0 起，執行 dotnet restore 與 nuget restore相同的程式代碼。

若要使用 dotnet restore還原套件：

  1. 開啟命令列並切換至包含您專案檔的目錄。
  2. 執行 dotnet restore。

重要

若要將遺漏的套件參考新增至項目檔，請使用 dotnet add package，它也會執行 restore。

使用 NuGet CLI 還原

NuGet CLI 還原 命令會下載並安裝任何遺失的套件。 此命令適用於使用 PackageReference 或 packages.config 進行套件參考的專案。

如同install，restore命令只會將套件新增至磁碟，但不會修改專案檔或 packages.config。若要新增專案相依性，請使用Visual Studio 封裝管理員 UI 或控制台。

若要還原套件，請執行下列命令：

nuget restore <projectPath>

命令 restore 會在指定的項目路徑中使用方案檔或 package.config 檔案。

例如，若要還原目前目錄中MySolution.sln的所有套件，請執行：

nuget restore MySolution.sln

注意

對於使用 PackageReference的非 SDK 樣式專案，請改用 msbuild -t：restore 還原套件。

使用 MSBuild 還原

您可以使用 msbuild -t：restore 還原 NuGet 4.x+ 和 MSBuild 15.1+中的套件，這些套件隨附於 Visual Studio 2017 和更新版本。

此命令會還原使用 PackageReference 進行封裝參考的專案中的套件。 從 MSBuild 16.5+開始，命令也支援 packages.config 套件參考，搭配 -p:RestorePackagesConfig=true使用時。

若要使用 MSBuild 還原：

  1. 藉由搜尋開發人員命令提示字元，並從 Windows [開始] 選單啟動提示字元，以開啟開發人員命令提示字元，以設定 MSBuild 的所有必要路徑。

  2. 切換到項目資料夾， 然後輸入 msbuild -t:restore。

  3. 還原完成之後，請輸入 msbuild 以重建專案。 請確定 MSBuild 輸出指出組建已順利完成。

注意

您可以使用 msbuild -restore 來執行 restore、重載專案和建置，因為組建是預設目標。 如需詳細資訊，請參閱 使用一個 MSBuild 命令還原和建置。

使用 Azure Pipelines 或 Azure DevOps Server 還原

當您在 Azure Pipelines 中建立組建定義時，可以在任何建置工作之前，在 定義中包含 NuGet CLI 還原 或 dotnet CLI 還原 工作。 根據預設，一些建置範本已包含還原工作。

如果您使用 TFS 2013 或更新版本的 Team Build 範本，Azure DevOps Server 和 TFS 2013 和更新版本會在建置期間自動還原套件。 您也可以包含執行命令行還原選項的建置步驟，或選擇性地將組建範本移轉至更新版本。 如需詳細資訊，請參閱使用 Team Foundation Build 的套件還原設定。

限制套件版本

透過任何方法還原 NuGet 會接受您在 packages.config 或項目檔中指定的任何版本條件約束。

  • 在 packages.config 中，您可以指定 allowedVersions 相依性中的範圍。 如需詳細資訊，請參閱 升級版本的條件約束。 例如：

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />

  • 在項目檔中，您可以在相依性屬性中 Version 指定版本範圍。 例如：

    <PackageReference Include="Newtonsoft.json" Version="[6,7)" />

在這兩種情況下，請使用套件版本設定中所述的表示法。

強制從遠端套件來源還原

根據預設，NuGet 還原作業會使用本機 global-packages 和 HTTP-cache 資料夾中的套件，如管理全域套件和快取資料夾中所述。 若要避免使用這些本機套件，請使用下列選項。

若要清除所有本機快取：

  • 在 Visual Studio 中，選取 [工具>選項>][NuGet]> 封裝管理員 [一般] 的 [清除所有 NuGet 快取] 按鈕。
  • 在 dotnet CLI 中，使用 dotnet nuget locals all --clear。
  • 在 NuGet CLI 中，使用 nuget locals all -clear。

若要避免在 global-packages 資料夾中使用套件：

  • 使用 nuget locals global-packages -clear 或 dotnet nuget locals global-packages --clear清除資料夾。
  • 暫時將 NUGET_PACKAGES 環境變數設定為不同的資料夾。
  • 建立 NuGet.Config 檔案，將 PackageReference、 或 repositoryPath packages.config 的 設定globalPackagesFolder為不同的資料夾。 如需詳細資訊，請參閱組態設定。
  • 若為僅限 MSBuild，請使用 RestorePackagesPath 屬性指定不同的資料夾。

若要避免在 HTTP 快取中使用套件：

  • 使用 nuget locals http-cache -clear 或 dotnet nuget locals http-cache --clear清除快取。
  • 暫時將 NUGET_HTTP_CACHE_PATH 環境變數設定為不同的資料夾。
  • 針對 nuget restore，請使用 -NoHttpCache 選項，或 針對 dotnet restore使用 --no-http-cache 選項。 這些選項不會影響透過Visual Studio 封裝管理員 或主控台的還原作業。

遷移至自動封裝還原

舊版 NuGet 支援 MSBuild 整合套件還原。 使用已取代 MSBuild 整合套件還原的項目應該移轉至自動封裝還原。

這些專案通常包含具有三個 檔案的 .nuget 資料夾： NuGet.config、 nuget.exe和 NuGet.targets。 NuGet.targets 檔案會導致 NuGet 使用 MSBuild 整合式方法，因此必須移除它。

若要遷移至自動套件還原：

  1. 啟用自動封裝還原。
  2. 關閉 Visual Studio。
  3. 刪除 .nuget/nuget.exe 和 .nuget/NuGet.targets。
  4. 針對每個項目檔，請移除 <RestorePackages> 專案，並移除 NuGet.targets 的任何參考。

若要測試自動封裝還原：

  1. 將 [packages] 資料夾從解決方案中移除。
  2. 在 Visual Studio 中開啟方案，並啟動建置。 自動套件還原應該下載並安裝每個相依性套件，而不需將其新增至原始檔控制。

下一步