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

  • 项目

有时，Visual Studio 项目中的包引用会中断。 卸载然后重新安装相同版本的包通常可将引用还原为正常工作状态。 更新包（即安装更新版本）也可以解决此问题。 本文介绍了如何重新安装和更新 NuGet 包以解决 Visual Studio 中包引用和项目损坏的问题。

注意

文中指南仅适用于使用 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> 参数是具体包的 ID。

注意

对于 dotnet CLI，不需要相同的过程。 运行 dotnet restore 命令时，dotnet CLI 使用 NuGet 来确定 NuGet 包必需使用的任何依赖项和下载。 有关详细信息，请参阅 使用 dotnet CLI 还原 NuGet 包。

升级版本约束

默认情况下，重新安装或更新包常常会安装包源中提供的最新版本。 但是，使用 packages.config 管理格式的项目可将允许的 NuGet 包版本限制在特定范围内。

假设应用由于包 API 中发生重大更改而只能与版本 1.x 包一起使用，但不能与版本 2.0 或更高版本一起使用。 若要确保应用如预期正常工作，则要约束 NuGet 包只能升级到版本 1.x。 此限制可帮助避免发生可能使应用无效的意外更新。

若要设置约束，在文本编辑器中打开 packages.config 文件。 找到要限制的依赖项，然后为 allowedVersions 属性添加想要的版本范围。

以下示例演示如何通过将 allowedVersions 属性设置为 [1,2)来约束版本升级：

<?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 管理格式的项目可以限制升级版本。

以下部分提供使用该命令的示例。

重新安装包选项

以下是使用该命令执行重新安装的基本用法。 可以使用可选 -Id 参数来识别具体的 NuGet 包。

# 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 命令。 此选项重新安装同一版本的初始包，但不重新安装依赖项。 使用此方法更新依赖项时可能会导致配置状态损坏。

损坏的依赖包

重新安装具体包时，不更新任何依赖重新安装的包的已安装包。 这些其他已安装包的版本保持不变。 因此，重新安装某个依赖项可能会损坏依赖包。