通过

在 Visual Studio 中重新安装和更新 NuGet 包

有时，包引用可能会中断在 Visual Studio 项目中。 卸载并重新安装同一版本的包通常会恢复引用到正常工作状态。 更新安装更新版本的包也可以解决此问题。 本文介绍如何重新安装和更新 NuGet 包，以解决损坏的包引用和损坏的项目。

注释

本文中的指南仅适用于使用 packages.config 管理格式的项目。 对于 PackageReference 项目，还原作会自动修复损坏的引用。

常见应用场景

在 Visual Studio 项目中，以下是一些您可能会遇到包引用出现问题的常见情况。

Scenario Description 决议
包还原后损坏的引用 打开 Visual Studio 项目并还原 NuGet 包，但包引用中断。 若要修复引用，请尝试单独重新安装每个包。
由于已删除的文件而损坏的项目 已删除（缺少）包文件会导致项目中断。 NuGet 不会阻止删除从包中添加的项。 很容易无意中修改从包安装的内容并破坏项目。 若要还原项目，请尝试重新安装受影响的包。
包更新后损坏的项目 包更新会中断项目。 依赖项包的配套更新通常会导致这种类型的失败。 若要将依赖项的状态还原到其以前的工作顺序，请尝试重新安装特定的依赖包。
项目重定目标或升级后的引用损坏 项目重定向或升级过程会导致包引用中断。 重新设置项目目标后，NuGet 会显示构建错误。 生成可能需要重新安装的警告列表包。 或者，升级项目后，NuGet 在项目升级日志中显示错误。 日志文件列出了可能需要重新安装的包。 若要解决目标框架中发生更改的问题，请尝试重新安装一个或多个包。
正在实施的软件包变更 包作者通常需要重新安装他们当前开发的相同版本的包来测试更改。 Visual Studio 中的 NuGet 包管理器控制台提供了用于更新和重新安装包的灵活选项。 若要在开发中重新安装包，可以使用 Update-Package -reinstall 该命令。

实现选项

有多种选项可用于更新和重新安装 NuGet 包。 常见方法包括 NuGet 包管理器 UI 选项、NuGet 包管理器控制台和 NuGet （命令行接口） CLI。

包管理器用户界面

除了控制台界面，包管理器 UI 还提供用于安装、更新和卸载包的菜单选项。

  • 若要更新包，请打开“ 更新 ”选项卡，选择一个或多个包，然后选择“ 更新”。

  • 若要重新安装包，请先卸载包，然后再次安装。 打开 “已安装 ”选项卡，选择包并记录其名称，然后选择“ 卸载”。 切换到 “浏览 ”选项卡并搜索包名称，选择包，然后选择“ 安装”。

包管理器控制台

可以在“工具>NuGet 包管理器>控制台。

  • 若要更新包，包管理器控制台提供 Update-Package 命令。

  • 若要重新安装包，可以将同一命令与参数一起使用 -reinstall 。 此方法是最简单的选项，如果它与配置兼容。

有关详细信息，请参阅 Update-Package 命令 和 包重新安装注意事项 部分。

NuGet 命令行接口 (CLI)

NuGet CLI nuget.exe是 Windows 的命令行实用工具，可提供所有 NuGet 功能。

  • 若要更新已安装的包，请运行以下命令 nuget update 。

  • 若要重新安装所有 NuGet 包，请删除包文件夹，然后运行 nuget install 命令。

  • 若要重新安装单个包，请删除包文件夹，然后运行 nuget install <id> 命令，其中 <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 属性。

以下示例演示如何通过将allowedVersions属性设置为[1,2)来限制对版本 1.x 的更新。

<?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>可以重新安装软件包。 卸载针对旧目标框架安装的包，并针对项目的新目标框架安装同一包。

在某些情况下，包可能不支持新的目标框架。 下面是可能会遇到的一些问题：

  • 如果包支持可移植类库（PCL），并且将项目重定向到包不再支持的平台组合，则重新安装后可能会缺少对该包的引用。

  • 此问题适用于直接使用的包或作为依赖项安装的包。 直接使用的任何包都可能支持新的目标框架，而它们的依赖项则不受支持。

  • 如果在重定目标应用程序后重新安装包会导致生成或运行时错误，则可能需要还原目标框架或搜索正确支持新目标框架的替代包。

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 命令。 此选项重新安装原始包的相同版本，但不会重新安装依赖项。 当更新包依赖项可能导致配置出现问题时，请使用此方法。

损坏的依赖包

重新安装特定包时，不会更新依赖于重新安装包的任何已安装包。 这些其他已安装包的版本保持不变。 因此，重新安装依赖项可能会中断依赖包。

  • Last updated on