将 .NET Framework 库移植到 .NET CorePort .NET Framework libraries to .NET Core

本文内容

了解如何将 .NET Framework 库代码移植到 .NET Core，以跨平台运行并扩展使用该代码的应用的范围。

系统必备Prerequisites

本文假定你：

  • 正在使用 Visual Studio 2017 或更高版本。
    • Visual Studio 的早期版本不支持 .NET Core
  • 了解推荐的移植过程。
  • 已解决与第三方依赖项有关的任何问题。还应熟悉下列主题的内容：

.NET Standard此主题介绍了适用于所有 .NET 实现代码的 .NET API 正式规范。

包、元包和框架这篇文章介绍了 .NET Core 如何定义和使用包，以及包如何支持多个 .NET 实现代码。

使用跨平台工具开发库此主题介绍了如何使用跨平台 CLI 工具编写 .NET 的库。

.NET Core 的 csproj 格式的新增内容本文概述了作为从移动到 csproj 和 MSBuild 的一部分，添加到项目文件的更改。

移植到 .NET Core - 分析第三方依赖项本主题介绍了第三方依赖项的可移植性及 NuGet 包依赖项无法在 .NET Core 上运行时要执行的操作。

将 .NET Framework 代码重定向到 .NET Framework 4.7.2Retargeting your .NET Framework code to .NET Framework 4.7.2

如果代码不面向 .NET Framework 4.7.2，建议重定向到 .NET Framework 4.7.2。在 .NET Standard 不支持现有 API 情况下，这可确保最新备用 API 的可用性。

对于 Visual Studio 中每个想要移植的项目，请执行以下操作：

  • 右键单击该项目，然后选择“属性” 。
  • 在“目标框架” 下拉列表中，选择“.NET Framework 4.7.2” 。
  • 重新编译项目。因为项目现在面向 .NET Framework 4.7.2，因此可使用该版本的 .NET Framework 作为移植代码的基准。

确定代码的可移植性Determining the portability of your code

下一步是运行 API 可移植性分析器 (ApiPort) 生成可供分析的可移植性报表。

确保了解 API 可移植性分析器 (ApiPort) 及如何生成用于面向 .NET Core 的可移植性报表。执行此操作的方式可能取决于需求和个人偏好。下面介绍了一些不同方法。用户可能会发现自己根据生成代码的方式混合使用了这些方法中的步骤。

主要处理编译器Dealing primarily with the compiler

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

  • 可选择在项目上运行 ApiPort。若运行 ApiPort，则从报告获取有关需要解决的问题的信息。
  • 将所有代码复制到新的 .NET Core 项目。
  • 查看可移植性报表（如果已生成）时，解决编译器错误，直至项目完全得到编译。尽管这种方法非常松散，但以代码为中心的方法通常可快速解决问题，并且可能是最适合小型项目或库的方法。只包含数据模型的项目可能是此方法的理想选择。

可移植性问题得到解决前停留在 .NET Framework 上Staying on the .NET Framework until portability issues are resolved

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

  • 在项目上运行 ApiPort。
  • 通过使用可移植的不同 API 解决问题。
  • 记录阻止你使用直接替代方案的所有区域。
  • 对所有要移植的项目重复前面的步骤，直到确信每个项目都做好被复制到新的 .NET Core 项目中的准备。
  • 将代码复制到新的 .NET Core 项目。
  • 解决所有已记录的不存在直接替代方案的问题。这种谨慎的方法比单纯解决编译器错误更有条理，但相对而言，它仍以代码为中心，且优点是始终拥有编译的代码。解决不能通过只使用另一个 API 解决的某些问题的方法大不相同。你可能会发现对于某些项目，需要制定更全面的计划，这将在下一种方法中涉及到。

制定全面的施行计划Developing a comprehensive plan of attack

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

  • 在项目上运行 ApiPort。
  • 了解每个非可移植类型使用的位置以及位置对整体可移植性的影响。
    • 了解这些类型的特性。它们是否数量少，但使用频繁？它们是否数量大，但使用不频繁？它们是串联使用，还是在整个代码中传播？
    • 是否可以轻松隔离不可移植的代码，以便可以更有效地处理它？
    • 是否需要重构代码？
    • 对于这些不可移植的类型，是否存在可完成相同任务的备用 API？例如，如果使用 WebClient 类，也许能够改用 HttpClient 类。
    • 是否存在其他可用于完成任务的可移植 API，即使它不是直接替代 API？例如，如果使用 XmlSchema 来分析 XML，但是无需 XML 架构发现，则可使用 System.Xml.Linq API 并自行实现分析，而不依赖于 API。
  • 如果具有难以移植的程序集，是否值得将其暂时留在 .NET Framework 上？以下是一些需要考虑的事项：
    • 库中可能具有某些与 .NET Core 不兼容的功能，因为它太依赖 .NET Framework 或 Windows 特定的功能。是否值得暂时搁置该功能并发布在资源可用于移植这些功能前暂具较少功能的库的 .NET Core 版本？
    • 重构是否有用？
  • 编写自己对不可用 .NET Framework API 的实现是否合理？可以考虑复制、修改，并使用 .NET Framework 参考源中的代码。参考源代码已在 MIT 许可证下获得许可，因此可以自由选择将此源作为自己代码的基础。只需确保在代码中正确设置 Microsoft。
  • 根据不同项目的需要，重复此过程。分析阶段可能需要一些时间，具体取决于代码库的大小。在此阶段花费时间（尤其是在具有复杂的代码库时），全面了解所需的更改范围并制定计划，从长远看通常可节省时间。

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

混合方法Mixing approaches

在每个项目的基础上，可能会将上述方法进行混合。应该进行对你和代码库最有意义的操作。

移植测试Porting your tests

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

移植的推荐方法Recommended approach to porting

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

  • 移植测试项目，该项目测试当前正在移植的库层。
  • 将库中的基项复制到新的 .NET Core 项目，然后选择想要支持的 .NET Standard 版本。
  • 进行任何所需的更改，使代码进行编译。大部分内容可能会要求将 NuGet 包依赖项添加到 csproj 文件。
  • 运行测试并进行任何所需调整。
  • 选择下一层代码进行移植，并重复前面的步骤。如果从库的基项开始并从基项向外移动并根据需要测试每一层，移植将是一个系统化的过程，在这种情况下，问题可以一次隔离到一层代码中。

下一页