创建移植计划

在直接进入代码前，请花时间完成推荐的迁移前步骤。 本文将让你深入了解可能遇到的问题类型，并帮助你确定最有意义的方法。

重要

API 端口已弃用，改为使用 .NET 升级助手 工具进行二进制分析。 API 端口的后端服务已关闭，因此要使用该工具，必须以脱机方式使用。 有关详细信息，请参阅 .NET API 端口自述文件。

移植代码

继续下一步之前，请确保遵循移植代码的先决条件。 准备好决定最适合你的方法并开始移植代码。

重要

.NET 升级助手已正式弃用。 使用 GitHub Copilot 现代化聊天代理 ，其包含在 Visual Studio 2026 和 Visual Studio 2022 17.14.16 或更高版本中。 此工具分析您的项目和依赖项，生成一个包含针对性建议和自动代码修复的分步迁移计划，并提交每个更改，以便您可以验证或回滚。 它自动执行常见移植任务（更新项目文件、替换已弃用的 API 和解决生成问题），以便可以更快地进行现代化，只需更少的手动工作量即可实现现代化。

主要处理编译器

此方法可能较适合小项目或不会用很多 .NET Framework API 的项目。 此方法很简单：

  1. 可选择在项目上运行 ApiPort。 运行 ApiPort 后，通过报告获取解决问题所需的深入信息。
  2. 将所有代码复制到新的 .NET 项目。
  3. 查看可移植性报表（如果已生成）时，解决编译器错误，直至项目完全得到编译。

尽管它是非结构化的，但这种以代码为中心的方法通常可以快速解决问题。 只包含数据模型的项目可能是此方法的理想选择。

在解决可移植性问题之前，请继续使用 .NET Framework

如果更希望拥有在整个过程期间编译的代码，此方法可能是最佳选择。 该方法如下所示：

  1. 在项目上运行 ApiPort。
  2. 通过使用可移植的不同 API 解决问题。
  3. 记录阻止你使用直接替代方案的所有区域。
  4. 对所有要移植的项目重复前面的步骤，直到确信每个项目都做好被复制到新的 .NET 项目中的准备。
  5. 将代码复制到新的 .NET 项目中。
  6. 解决任何你已注意到不存在直接替代方案的问题。

这种谨慎的方法比单纯解决编译器错误更有条理，但相对而言，它仍以代码为中心，且优点是始终拥有编译的代码。 解决不能通过只使用另一个 API 解决的某些问题的方法大不相同。 你可能会发现对于某些项目，需要制定更全面的计划，这将在下一种方法中介绍。

制定全面的攻击计划

此方法可能最适合大型或更复杂的项目，在这种情况下，为支持 .NET，可能必需重构代码或将某些代码区域完全重写。 该方法如下所示：

  1. 在项目上运行 ApiPort。

  2. 了解每个非可移植类型使用的位置以及位置对整体可移植性的影响。

    • 了解这些类型的特性。 它们是否数量少，但使用频繁？ 它们是否数量大，但使用不频繁？ 它们的使用是集中在一起的，还是在整个代码中分布的？
    • 是否可以轻松隔离不可移植的代码，以便可以更有效地处理它？
    • 是否需要重构代码？
    • 对于这些不可移植的类型，是否存在可完成相同任务的备用 API？ 例如，如果使用的是 WebClient 类，则改用 HttpClient 类。
    • 是否存在其他可用于完成任务的可移植 API，即使它不是直接替代 API？ 例如，如果使用 XmlSchema 来分析 XML，但是无需 XML 架构发现，则可使用 System.Xml.Linq API 并自行实现分析，而不是依赖于某个 API。

  3. 如果具有难以移植的程序集，是否值得将其暂时留在 .NET Framework 上？ 以下是一些需要考虑的事项：

    • 库中可能具有某些与 .NET 不兼容的功能，因为它过于依赖 .NET Framework 或 Windows 特定的功能。 是否值得暂时搁置该功能，并直到资源可用于移植这些功能，才发布具有较少功能的库的临时 .NET 版本？
    • 重构是否有用？

  4. 编写自己对不可用 .NET Framework API 的实现是否合理？

    可以考虑复制、修改，并使用 .NET Framework 参考源中的代码。 参考源代码已在 MIT 许可证下获得许可，因此可以自由选择将此源作为自己代码的基础。 只需确保在代码中正确归因于 Microsoft。

  5. 根据不同项目的需要，重复此过程。

分析阶段可能需要一些时间，具体取决于代码库的大小。 在此阶段花费时间（尤其是在具有复杂的代码库时），全面了解所需的更改范围并制定计划，最终通常可节省时间。

计划可能包括对代码库做重大更改，同时仍以 .NET Framework 4.7.2 为目标。 这是前一种方法更有条理的版本。 着手执行计划的方式具体取决于代码库。

混合方法

可能会在每个项目的基础上混合使用上述方法。 选择对你和代码库最有意义的行动。

迁移您的测试

要确保移植代码后一切正常的最佳方式是在将代码移植到 .NET 时进行测试。 为此，需要使用将针对 .NET 生成和运行测试的测试框架。 当前，有三个选择：

从根本上讲，移植工作在很大程度上取决于生成 .NET Framework 代码的方式。 移植代码的一个好方法是从库的基项开始，这是代码的基础组件。 这可能是数据模型或某些其他内容直接或间接使用的基本类和方法。

  1. 移植测试项目，该项目测试当前正在移植的库层。
  2. 将库中的基项复制到新的 .NET 项目中，然后选择想要支持的 .NET Standard 版本。
  3. 进行任何所需的更改，使代码进行编译。 大部分内容可能会要求将 NuGet 包依赖项添加到 csproj 文件。
  4. 运行测试并进行任何所需调整。
  5. 选择下一层代码进行移植，并重复前面的步骤。

如果从库的基项开始并从基项向外移动并根据需要测试每一层，移植将是一个系统化的过程，在这种情况下，问题可以一次隔离到一层代码中。

后续步骤

  • Last updated on