通过

从 packages.config 迁移到 PackageReference

Visual Studio 2017 版本 15.7 及更高版本支持将项目从 packages.config 管理格式迁移到 PackageReference 格式。

使用 PackageReference 的好处

  • 在一个位置管理所有项目依赖项：就像项目到项目引用和程序集引用一样，NuGet 包引用（使用 PackageReference 节点）直接在项目文件中管理，而不是使用单独的 packages.config 文件。
  • 顶级依赖项的未整理视图：与 packages.config不同，PackageReference 仅列出直接安装在项目中的那些 NuGet 包。 因此，NuGet 包管理器 UI 和项目文件不被下层依赖项所冗杂。
  • 性能改进：使用 PackageReference 时，包将保留在全局包文件夹中（如管理全局包和缓存文件夹packages而不是解决方案中的文件夹中所述）。 因此，PackageReference 的性能更快，占用的磁盘空间更少。
  • 精细控制依赖项和内容流：使用 MSBuild 的现有功能，可以 有条件地引用 NuGet 包，并为每个目标框架、配置、平台或其他维度选择包引用。

局限性

  • NuGet PackageReference 在 Visual Studio 2015 及更早版本中不可用。 迁移的项目只能在 Visual Studio 2017 及更高版本中打开。
  • 迁移目前不适用于C++和 ASP.NET 项目。
  • 某些包可能无法与 PackageReference 完全兼容。 有关详细信息，请参阅 包兼容性问题。

此外，PackageReferences 的工作方式与 packages.config相比存在一些差异。例如，PackageReference 不支持 升级版本的约束 ，但 PackageReference 添加了对 浮动版本的支持。

已知问题

  1. 此选项 Migrate packages.config to PackageReference... 在右键单击上下文菜单中不可用

問题

首次打开项目时，在执行 NuGet 操作之前，NuGet 可能尚未初始化。 这会导致迁移选项不显示在 packages.config 或 References 的右键菜单中。

解决方法

执行以下任一 NuGet 操作：

  • 打开包管理器 UI - 右键单击 References 并选择 Manage NuGet Packages...
  • 打开包管理器控制台 - 从 Tools > NuGet Package Manager中选择 Package Manager Console
  • 运行 NuGet 还原 - 右键单击解决方案资源管理器中的解决方案节点，然后选择 Restore NuGet Packages
  • 生成同时触发 NuGet 还原的项目

现在应该能够看到迁移选项。 请注意，此选项不受支持，并且不会显示 ASP.NET 和C++项目类型。

迁移步骤

注释

在迁移开始之前，Visual Studio 会创建项目的备份，以便在必要时 回滚到 packages.config 。

  1. 使用packages.config打开包含项目的解决方案。

  2. 在 解决方案资源管理器中，右键单击 “引用 ”节点或 packages.config 文件，然后选择“ 将 packages.config 迁移到 PackageReference...”。

  3. 迁移程序分析项目的 NuGet 包引用，并尝试将它们分类为 顶级依赖项 （直接安装的 NuGet 包）和 可传递依赖项 （作为顶级包的依赖项安装的包）。

    注释

    PackageReference 支持可传递包还原并动态解析依赖项，这意味着不需要显式安装可传递依赖项。

  4. （可选）您可以将某个分类为可传递依赖项的 NuGet 包视为顶级依赖项，只需为该包选择顶级选项。 对于那些不进行传递流动（位于build、buildCrossTargeting或contentFiles文件夹中的资产）以及标记为开发者依赖项的analyzers包，将自动设置此选项。

  5. 检查任何 软件包兼容性问题。

  6. 选择 “确定 ”开始迁移。

  7. 在迁移结束时，Visual Studio 提供一个报表，其中包含备份的路径、已安装的包列表（顶级依赖项）、作为可传递依赖项引用的包列表，以及迁移开始时确定的兼容性问题列表。 报表将保存到备份文件夹。

  8. 验证解决方案是否生成并运行。 如果遇到问题， 请在 GitHub 上提出问题。

如何回滚到 packages.config

  1. 关闭迁移的项目。

  2. 将项目文件以及 packages.config 从备份（通常） <solution_root>\MigrationBackup\<unique_guid>\<project_name>\复制到项目文件夹。 如果项目根目录中存在，请删除 obj 文件夹。

  3. 打开项目。

  4. 使用“工具 > NuGet 包管理器 > 包管理器控制台”菜单命令打开包管理器控制台。

  5. 在控制台中运行以下命令：

    update-package -reinstall

迁移后创建包

迁移完成后，建议将包元数据从 .nuspec 文件复制到 MSBuild 属性，然后可用于 msbuild -t:pack 创建包。 如果使用 Visual Studio 2022 或更早版本，则还需要安装 NuGet.Build.Tasks.Pack 包。 从 Visual Studio 2026 开始，包集成到 MSBuild。

包兼容性问题

PackageReference 不支持 packages.config 支持的某些方面。 迁移程序分析和检测此类问题。 迁移后，任何具有以下一个或多个问题的包都可能无法按预期方式运行。

迁移后安装包时，将忽略“install.ps1”脚本

  • 说明：在安装或卸载包时，不会执行 PackageReference、install.ps1 和 uninstall.ps1 PowerShell 脚本。

  • 潜在影响：依赖于这些脚本在目标项目中配置某些行为的包可能无法按预期工作。

迁移后安装软件包时，“内容”资源不可用。

  • 说明：PackageReference 不支持包 content 文件夹中的资产，并且将被忽略。 PackageReference 添加了对 contentFiles 更好的可传递支持和共享内容的支持。

  • 潜在影响：在 content 的资产没有复制到项目中，依赖这些资产的项目代码需要重构。

在升级后安装包时，不会应用 XDT 转换。

  • 说明：PackageReference .xdt 不支持 XDT 转换，安装或卸载包时将忽略文件。

  • 潜在影响：XDT 转换不应用于任何项目 XML 文件（最常见的 web.config.install.xdtweb.config.uninstall.xdt情况），这意味着在安装或卸载包时不会更新项目 web.config 的文件。

迁移后安装软件包时，将忽略位于 lib 根目录中的程序集。

  • 说明：使用 PackageReference 时，会忽略根文件夹中那些没有目标框架特定子文件夹的程序集。 NuGet 查找与项目的目标框架名字对象（TFM）相对应的子文件夹，并将匹配的程序集安装到项目中。

  • 潜在影响：在迁移过程中，如果包中没有与项目目标框架名字对象（TFM）匹配的子文件夹，可能会导致行为异常或安装失败。

找到了问题？ 报告它！

如果遇到迁移体验问题，请在 NuGet GitHub 存储库上提出问题。