在 Visual Studio 中重新安裝和更新 NuGet 套件

  • 發行項

有時候，套件參考可能會中斷於Visual Studio專案中。 卸載並重新安裝相同版本的套件通常會還原工作順序的參考。 更新安裝更新版本的套件也可以解決此問題。 本文說明如何重新安裝和更新 NuGet 套件，以解決中斷的套件參考和中斷的專案。

注意

本文中的指引僅適用於使用 packages.config 管理格式的專案。 針對 PackageReference 專案，還原作業會自動修正中斷的參考。

常見案例

以下是您在Visual Studio專案中可能會遇到套件參考中斷的一些常見案例。

案例 描述 解決方案
套件還原後中斷的參考 您可以開啟 Visual Studio 專案並還原 NuGet 套件，但套件參考仍會中斷。 若要修正參考，請嘗試個別重新安裝每個套件。
因已刪除的檔案而中斷的專案 已刪除 （遺失） 套件檔案會導致您的項目中斷。 NuGet 不會防止刪除您從套件新增的專案。 不小心修改從套件安裝的內容並中斷專案很容易。 若要還原專案，請嘗試重新安裝受影響的套件。
套件更新之後中斷的專案 套件更新會中斷您的專案。 相依性套件的隨附更新通常會導致這種類型的失敗。 若要將相依性的狀態還原為其先前的工作順序，請嘗試重新安裝特定的相依套件。
項目複位目標或升級之後的中斷參考 項目複位目標或升級程式會導致套件參考中斷。 重新設定項目目標之後，NuGet 會顯示建置錯誤。 建置警告會列出可能需要重新安裝的套件。 或者，升級項目之後，NuGet 會在專案升級記錄檔中顯示錯誤。 記錄檔會列出可能需要重新安裝的套件。 若要解決目標架構變更所造成的問題，請嘗試重新安裝一或多個套件。
開發下的套件變更 套件作者通常需要重新安裝他們目前正在開發的相同套件版本，以測試其變更。 Visual Studio 中的 NuGet 封裝管理員 主控台提供更新和重新安裝套件的彈性選項。 若要重新安裝開發中的套件，您可以使用 Update-Package -reinstall 命令。

實作選項

您有數個選項可用來更新和重新安裝 NuGet 套件。 常見的方法包括 NuGet 封裝管理員 UI 選項、NuGet 封裝管理員 主控台，以及 NuGet （命令行介面） CLI。

套件管理員 UI

除了主控台介面之外，封裝管理員 UI 也提供安裝、更新和卸載套件的功能表選項。

  • 若要更新套件，請開啟 [更新] 索引標籤，選擇一或多個套件，然後選取 [更新]。

  • 若要重新安裝套件，請先卸載套件，然後再安裝一次。 開啟 [ 已安裝] 索引標籤，選擇套件並記錄其名稱，然後選取 [ 卸載]。 切換至 [ 瀏覽] 索引標籤並搜尋套件名稱，選擇套件，然後選取 [ 安裝]。

套件管理員主控台

您可以在 [工具>NuGet] 封裝管理員> 封裝管理員 [控制台] 下存取 [封裝管理員 控制台]。

  • 若要更新套件，封裝管理員 主控台會提供 Update-Package 命令。

  • 若要重新安裝套件，您可以搭配 -reinstall 參數使用相同的命令。 如果此方法與組態相容，這是最簡單的選項。

如需詳細資訊，請參閱 Update-Package命令 和 套件重新安裝考慮 小節。

NuGet CLI

NuGet CLI nuget.exe是 Windows 的命令行公用程式，可提供所有 NuGet 功能。

  • 若要更新已安裝的套件，請執行 nuget update 命令。

  • 若要重新安裝所有 NuGet 套件，請刪除套件資料夾，然後執行 nuget install 命令。

  • 若要重新安裝單一套件，請刪除套件資料夾，然後執行 nuget install <id> 命令，其中 <id> 自變數是特定套件的標識碼。

注意

針對 dotnet CLI，不需要對等的程式。 當您執行 dotnet restore 命令時，dotnet CLI 會使用 NuGet 來判斷相依性，並下載任何必要的 NuGet 套件。 如需詳細資訊，請參閱 使用 dotnet CLI 還原 NuGet 套件。

升級版本的條件約束

重新安裝或更新套件預設「一律」會安裝套件來源中可用的最新版本。 不過，使用 packages.config 管理格式的專案可以特別限制允許的 NuGet 套件版本範圍。

假設您的應用程式僅適用於套件 1.x 版，但不適用於 2.0 版或更新版本，因為套件 API 發生重大變更。 為了確保應用程式如預期般運作，您想要將 NuGet 套件升級限為僅限 1.x 版。 此限制有助於防止可能會中斷應用程式的意外更新。

若要設定條件約束，請在文本編輯器中開啟 packages.config 檔案。 找出您想要限制的相依性，並使用您想要的版本範圍新增 allowedVersions 屬性。

下列範例示範如何將 屬性設定為 [1,2)來限制 1.x 版的allowedVersions更新：

<?xml version="1.0" encoding="utf-8"?>
<packages>
    <package id="ExamplePackage" version="1.1.0" allowedVersions="[1,2)" />

    <!-- ... -->
</packages>

在所有情況下，都請使用套件版本控制中所述的標記法。

Update-Package 命令

封裝管理員 控制台中的 Update-Package 命令是重新安裝套件和解決中斷參考的最簡單方式。 不過，此方法在所有案例中都無法使用。 您可以使用 命令來更新已安裝的套件，但無法執行初始安裝。 如果您嘗試更新或重新安裝組態中尚未安裝的套件，命令會傳回錯誤。 在使用 命令之前，請務必檢閱 套件重新安裝考慮 一節。

使用 PackageReference 更新專案或方案中的套件一律會更新為最新版本的套件（不包括發行前版本套件）。 使用packages.config管理格式的專案可以限制升級版本，如升級版本的條件約束中所述。

下列各節提供使用 命令的範例。

重新安裝套件選項

以下是執行重新安裝之命令的基本用法。 若要識別特定的 NuGet 套件，您可以使用選擇性 -Id 參數。

# Reinstall the package named <package_name>
Update-Package -Id <package_name> –reinstall

Update-Package使用 命令比移除套件更容易，然後嘗試以相同版本在 NuGet 資源庫中尋找相同的套件。

更新套件選項

如果適用，沒有 參數的 -reinstall 相同命令會將套件更新為較新版本。 如果指定的套件尚未安裝在專案中，此命令會傳回錯誤。

# Update the package named <package_name>
Update-Package <package_name>

專案和方案選項

根據預設， Update-Package 命令會影響方案中的所有專案。 若要將動作限制為特定專案，請使用 -ProjectName 參數。 提供出現在 Visual Studio 方案總管 中的項目名稱。

下列命令會重新安裝方案中特定專案的 NuGet 套件。 參數中 <package_name> 會提供要重新安裝的特定 NuGet 套件名稱。

# Reinstall the package named <package_name> in MyProject only
Update-Package <package_name> -ProjectName MyProject -reinstall

如果您想要重新安裝專案中的所有套件，請勿指定任何特定的套件，請使用 -ProjectName 參數。 您可以遵循這個相同的方法來更新專案中的套件，如下列範例所示：

# Update all packages in MyProject only
Update-Package -ProjectName MyProject

若要更新方案中的所有套件，只要單獨使用 Update-Package 命令，而沒有其他自變數或參數。

重要

請務必小心使用下列形式的命令。 命令程式可能需要相當長的時間來執行所有更新。

# Update all packages in all projects in the solution
Update-Package

套件重新安裝考慮

如果您想要使用 Update-Package 命令重新安裝套件，請檢閱下列考慮，以確保與組態案例的相容性。

  • 套件及其相依性可能不支持複位目標專案目標架構。
  • requireReinstallation當 屬性設定為 true時，Visual Studio 會針對受影響的套件發出建置警告。
  • 重新安裝套件和版本條件約束可能會造成相依性版本相容性問題。
  • 重新安裝特定套件可能會導致相依套件中斷。

套件不支援專案目標架構

如果您將目標複位為專案目標架構，則一或多個套件可能不支援新的目標組態。

通常，使用 Update-Package –reinstall <package_name> 命令重新安裝套件可以運作。 已卸載針對舊目標 Framework 安裝的套件，而且會針對專案的新目標架構安裝相同的套件。

在某些情況下，套件可能不支援新的目標架構。 以下是您可能會遇到的一些問題：

  • 如果套件支援可攜式類別庫 （PCLs），而且您將項目複位為套件不再支援的平台組合，則重新安裝之後可能會遺漏封裝的參考。

  • 此問題可能會針對您直接使用的套件或安裝為相依性的套件呈現。 您直接使用的任何套件都可能支援新的目標架構，而其相依性則不支援。

  • 如果重新設定應用程式目標之後重新安裝套件會導致建置或運行時間錯誤，您可能需要還原目標架構，或搜尋可正確支援新目標架構的替代套件。

requireReinstallation 屬性設定為 true

重新設定專案目標架構或升級 NuGet 套件之後，NuGet 可能會將 屬性新增 requireReinstallation 至 packages.config 專案的 檔案。 如果 NuGet 在複位目標或升級程式期間偵測到受影響的套件，它會針對所有受影響的套件參考，將屬性新增 requireReinstallation="true" 至 packages.config 檔案。 因此，Visual Studio 中專案的每個後續組建都會引發這些套件的建置警告。 警告會顯示為重新安裝受影響套件的提醒。

套件相依性版本不相容

此命令 Update-Package –reinstall 會 重新安裝已安裝套件的相同 版本，以及 任何相依性的最新版本 。 若要解決版本不相容問題，您可以設定版本範圍條件約束來控制設定。 NuGet 會遵守條件約束，並僅視需要將套件相依性更新為較新版本，才能修正問題。

  • 如果您的條件約束設定導致相依性在套件重新安裝期間還原為舊版，您可以使用 命令解決此問題 Update-Package <dependency_name> 。 此命令會重新安裝指定的相依性，而不會影響相依套件。

  • 您也可以使用 Update-Package –reinstall <packageName> -ignoreDependencies 命令。 此選項會重新安裝相同版本的原始套件，但不會重新安裝相依性。 更新套件相依性時，使用此方法可能會導致設定狀態中斷。

中斷的相依套件

當您重新安裝特定套件時，不會更新相依於重新安裝套件的任何已安裝套件。 這些其他已安裝套件的版本保持不變。 因此，重新安裝相依性可能會中斷相依套件。