共用方式為


使用 NuGet 套件還原還原套件

NuGet 套件還原會還原項目檔或 packages.config 檔案中列出的所有專案的相依性。 您可以使用 、、 dotnet restoremsbuild -t:restore或 透過 Visual Studio 手動nuget restore還原套件。 dotnet builddotnet 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 有兩種套件管理格式:PackageReferencepackages.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 builddotnet run 命令會自動還原套件。 從 NuGet 4.0 起,執行 dotnet restorenuget restore相同的程式代碼。

若要使用 dotnet restore還原套件:

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

重要

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

使用 NuGet CLI 還原

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

如同installrestore命令只會將套件新增至磁碟,但不會修改專案檔或 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-packagesHTTP-cache 資料夾中的套件,如管理全域套件和快取資料夾中所述。 若要避免使用這些本機套件,請使用下列選項。

若要清除所有本機快取:

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

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

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

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

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

遷移至自動封裝還原

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

這些專案通常包含具有三個 檔案的 .nuget 資料夾: NuGet.confignuget.exeNuGet.targetsNuGet.targets 檔案會導致 NuGet 使用 MSBuild 整合式方法,因此必須移除它。

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

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

若要測試自動封裝還原:

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

下一步