.NET 可移植性分析器The .NET Portability Analyzer

想让库支持多平台吗?Want to make your libraries support multi-platform? 想要了解使 .NET Framework 应用程序在 .NET Core 上运行需要花费多大的精力?Want to see how much work is required to make your .NET Framework application run on .NET Core? .NET 可移植性分析器是一种工具,可分析程序集并为应用程序或库提供有关缺失的 .NET API 的详细报告,以便在指定的目标 .NET 平台上实现可移植性。The .NET Portability Analyzer is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. 可移植性分析器作为 Visual Studio Extension 提供,用于分析每个项目的一个程序集;也可以作为 ApiPort 控制台应用提供,用于按指定文件或目录分析程序集。The Portability Analyzer is offered as a Visual Studio Extension, which analyzes one assembly per project, and as a ApiPort console app, which analyzes assemblies by specified files or directory.

将项目转换为面向 .NET Core 等新平台后,可以使用基于 Roslyn 的 API 分析器工具来识别引发 PlatformNotSupportedException 异常以及其他兼容性问题的 API。Once you've converted your project to target the new platform, like .NET Core, you can use the Roslyn-based API Analyzer tool to identify APIs throwing PlatformNotSupportedException exceptions and other compatibility issues.

常用对象Common targets

  • .NET Core:采用模块化设计,支持并行安装,面向跨平台方案。.NET Core: Has a modular design, supports side-by-side installation, and targets cross-platform scenarios. 可并行安装意味着无需破坏其他应用即可采用新的 .NET Core 版本。Side-by-side installation allows you to adopt new .NET Core versions without breaking other apps. 如果目标是将应用移植到 .NET Core 以支持多个平台,则建议使用此对象。If your goal is to port your app to .NET Core and support multiple platforms, this is the recommended target.
  • .NET Standard:包括所有 .NET 实现上提供的 .NET Standard API。.NET Standard: Includes the .NET Standard APIs available on all .NET implementations. 如果目标是使自己的库能够在所有 .NET 支持的平台上运行,则建议使用此对象。If your goal is to make your library run on all .NET supported platforms, this is recommended target.
  • ASP.NET Core:在 .NET Core 基础上构建的现代 Web 框架。ASP.NET Core: A modern web-framework built on .NET Core. 如果目标是将 Web 应用移植到 .NET Core 以支持多个平台,则建议使用此对象。If your goal is to port your web app to .NET Core to support multiple platforms, this is the recommended target.
  • .NET Core + 平台扩展:除 Windows 兼容包之外,还包括 .NET Core API,后者提供了许多可用的 .NET Framework 技术。.NET Core + Platform Extensions: Includes the .NET Core APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. 这是推荐的对象,用于将 Windows 上的应用从 .NET Framework 移植到 .NET Core。This is a recommended target for porting your app from .NET Framework to .NET Core on Windows.
  • .NET Standard + 平台扩展:除 Windows 兼容包之外,还包括 .NET Standard API,后者提供了许多可用的 .NET Framework 技术。.NET Standard + Platform Extensions: Includes the .NET Standard APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. 这是推荐的对象,用于将 Windows 上的库从 .NET Framework 移植到 .NET Core。This is a recommended target for porting your library from .NET Framework to .NET Core on Windows.

如何使用 .NET 可移植性分析器How to use the .NET Portability Analyzer

若要开始在 Visual Studio 中使用 .NET 可移植性分析器,必须先从 Visual Studio Marketplace 下载扩展并进行安装。To begin using the .NET Portability Analyzer in Visual Studio, you first need to download and install the extension from the Visual Studio Marketplace. 它适用于 Visual Studio 2017 及更高版本。It works on Visual Studio 2017 and later versions. 可以通过 Visual Studio 中的“分析” > “可移植性分析器设置”对其进行配置,并选择目标平台,即选择 .NET 平台/版本,用于评估与当前程序集构建的平台/版本相比的可移植性差距 。Configure it in Visual Studio via Analyze > Portability Analyzer Settings and select your Target Platforms, which are the .NET platforms/versions that you want to evaluate the portability gaps comparing with the platform/version that your current assembly is built with.

可移植性分析器的屏幕截图。

还可以使用 ApiPort 控制台应用程序,可从 ApiPort 存储库进行下载。You can also use the ApiPort console application, download it from ApiPort repository. 可以使用 listTargets 命令选项以显示可用的目标列表,然后通过指定 -t--target 命令选项来选择目标平台。You can use listTargets command option to display the available target list, then pick target platforms by specifying -t or --target command option.

解决方案范围视图Solution wide view

分析包含多个项目的解决方案的一个很有用的步骤是,可视化依赖项以了解程序集中各个子集的依赖关系。A useful step in analyzing a solution with many projects would be to visualize the dependencies to understand which subset of assemblies depend on what. 一般的建议是,从依赖项关系图中的叶节点开始,以自下而上的方式应用分析结果。The general recommendation is to apply the results of the analysis in a bottom-up approach starting with the leaf nodes in a dependency graph.

要检索此项,可运行以下命令:To retrieve this, you may run the following command:

ApiPort.exe analyze -r DGML -f [directory or file]

在 Visual Studio 中打开时,此结果如下所示:A result of this would look like the following when opened in Visual Studio:

DGML 分析的屏幕截图。

分析可移植性Analyze portability

若要在 Visual Studio 中分析整个项目,请在“解决方案资源管理器”中右键单击该项目,然后选择“分析程序集可移植性” 。To analyze your entire project in Visual Studio, right-click on your project in Solution Explorer and select Analyze Assembly Portability. 也可以转到“分析”菜单,选择“分析程序集可移植性”。 Otherwise, go to the Analyze menu and select Analyze Assembly Portability. 在该位置选择项目的可执行文件或 DLL。From there, select your project's executable or DLL.

解决方案资源管理器中的可移植性分析器的屏幕截图。

还可以使用 ApiPort 控制台应用You can also use the ApiPort console app.

  • 键入以下命令即可分析当前目录:ApiPort.exe analyze -f .Type the following command to analyze the current directory: ApiPort.exe analyze -f .
  • 若要分析特定的 .dll 文件列表,请键入以下命令:ApiPort.exe analyze -f first.dll -f second.dll -f third.dllTo analyze a specific list of .dll files, type the following command: ApiPort.exe analyze -f first.dll -f second.dll -f third.dll
  • 运行 ApiPort.exe -? 以获取更多帮助Run ApiPort.exe -? to get more help

建议包含自己拥有的且要移植的所有相关 exe 和 dll 文件,并且排除应用所依赖的,但你既不拥有又无法移植的文件。It is recommended that you include all the related exe and dll files that you own and want to port, and exclude the files that your app depends on, but you don't own and can't port. 这将为你提供最相关的可移植性报表。This will give you most relevant portability report.

查看和解释可移植性结果View and interpret portability result

报表中仅显示目标平台不支持的 API。Only APIs that are unsupported by a Target Platform appear in the report. 在 Visual Studio 中运行分析后,你将看到弹出的 .NET 可移植性报表文件链接。After running the analysis in Visual Studio, you'll see your .NET Portability report file link pops up. 如果使用的是 ApiPort 控制台应用,.NET 可移植性报表将以指定的格式保存为文件。If you used the ApiPort console app, your .NET Portability report is saved as a file in the format you specified. 默认位于当前目录中的 Excel 文件 (.xlsx) 中。The default is in an Excel file (.xlsx) in your current directory.

可移植性摘要Portability Summary

可移植性摘要的屏幕截图。

报表的“可移植性摘要”部分显示运行中包含的每个程序集的可移植性百分比。The Portability Summary section of the report shows the portability percentage for each assembly included in the run. 在上述示例中,svcutil 应用中使用的 71.24% 的 .NET Framework API 在 .NET Core + Platform Extensions 中可用。In the previous example, 71.24% of the .NET Framework APIs used in the svcutil app are available in .NET Core + Platform Extensions. 如果针对多个程序集运行 .NET 可移植性分析器工具,则每个程序集在“可移植性摘要”报表中都应有一行。If you run the .NET Portability Analyzer tool against multiple assemblies, each assembly should have a row in the Portability Summary report.

详细信息Details

可移植性详细信息的屏幕截图。

报表的“详细信息”部分列出了任意选定目标平台缺少的 API。The Details section of the report lists the APIs missing from any of the selected Targeted Platforms.

  • 目标类型:该类型具有目标平台缺少的 APITarget type: the type has missing API from a Target Platform
  • 目标成员:目标平台缺少的方法Target member: the method is missing from a Target Platform
  • 程序集名称:缺少的 API 所在的 .NET Framework 程序集。Assembly name: the .NET Framework assembly that the missing API lives in.
  • 每个选定的目标平台都是一列,例如“.NET Core”:“不支持”值表示此目标平台不支持 API。Each of the selected Target Platforms is one column, such as ".NET Core": "Not supported" value means the API is not supported on this Target Platform.
  • 建议的更改:要进行更改的推荐 API 或技术。Recommended Changes: the recommended API or technology to change to. 对于许多 API,此字段当前为空或已过时。Currently, this field is empty or out of date for many APIs. 由于 API 数量众多,在维护 API 最新状态方面,我们面临着巨大的挑战。Due to the large number of APIs, we have a significant challenge to keep it up to date. 我们致力于提供备用解决方案,以便为客户提供有用的信息。We're looking at alternative solutions to provide helpful information to customers.

缺少程序集Missing Assemblies

缺少的程序集的屏幕截图。

可以在报表中找到“缺少程序集”部分。You may find a Missing Assemblies section in your report. 此部分包含由你的经过分析的程序集引用的程序集列表(此列表未经过分析)。This section contains a list of assemblies that are referenced by your analyzed assemblies and were not analyzed. 如果它是你自己拥有的程序集,请将其包含在 API 可移植性分析器运行过程中,以便你可以获得详细的 API 级别可移植性报表。If it's an assembly that you own, include it in the API portability analyzer run so that you can get a detailed, API-level portability report for it. 如果它是第三方库,请检查是否存在支持目标平台的更新版本,并考虑转到较新的版本。If it's a third-party library, check if there is a newer version that supports your target platform, and consider moving to the newer version. 最终,此列表应该包含你的应用依赖的所有第三方程序集(其中具有支持目标平台的版本)。Eventually, the list should include all the third-party assemblies that your app depends on that have a version supporting your target platform.

有关 .NET 可移植性分析器的详细信息,请访问 GitHub 文档简要了解 .NET 可移植性分析器第 9 频道视频。For more information on the .NET Portability Analyzer, visit the GitHub documentation and A Brief Look at the .NET Portability Analyzer Channel 9 video.