大网数据广告活动
.NET 与 C# 开发

.NET API 分析器

· 52CE 我爱测

了解 .NET API 分析器如何有助于检测弃用的 API 和平台兼容性问题。

.NET API 分析器是 Roslyn 分析器,可用于发现不同平台上的潜在 C# API 兼容性风险,并检测是否调用了弃用的 API。 可供所有 C# 开发人员在任何开发阶段使用。

API 分析器以 NuGet 包 Microsoft.DotNet.Analyzers.Compatibility 的形式提供。 在项目中引用此分析器后,它就会自动监视代码,并指出有问题的 API 使用。 还可以单击灯泡图标,获取有关可能解决方案的建议。 下拉菜单包括禁止显示警告的选项。

Note: .NET API 分析器仍为预发行版。

系统必备

  • Visual Studio 2017 及更高版本,或 Visual Studio for Mac(所有版本)。

发现弃用的 API

什么是弃用的 API?

.NET 系列是一组不断升级的大型产品,力求更好地满足客户需求。 弃用并将一些 API 替换为新 API 是很自然的。 若有更好的替换 API,API 便会被视为弃用。 指明 API 已遭弃用且不得使用的一种方法是,用 xref:System.ObsoleteAttribute 属性标记它。 这种方法的缺点是,所有已过时 API 都只有一个诊断 ID(对于 C#,ID 为 CS0612)。 这表示:

  • 无法为每个事例设置专用文档。
  • 无法禁止显示特定类别的警告。 要么禁止显示所有警告,要么允许显示所有警告。
  • 为了通知用户有新弃用,必须更新引用的程序集或目标包。

API 分析器使用 API 专用错误代码,这些代码以 DE(全称是“Deprecation Error”(弃用错误))开头,这样就可以单独控制各个警告的显示。 分析器发现的弃用的 API 在 dotnet/platform-compat 存储库中进行定义。

使用 API 分析器

如果代码使用了弃用的 API(如 xref:System.Net.WebClient),API 分析器便会使用绿色波浪线突出显示它。 如果将鼠标悬停在 API 调用之上,就会看到包含 API 弃用相关信息的灯泡,如下面的示例所示:

“显示绿色波浪线且左侧有灯泡的 WebClient API 屏幕截图”

弃用的 API 每出现一次,“错误列表”窗口中都会显示具有唯一 ID 的警告,如下面的示例所示 (DE004):

“显示警告 ID 和说明的‘错误列表’窗口屏幕截图”

单击 ID 后,便会转到详细信息网页,其中说明了 API 遭弃用的原因,以及有关可用替换 API 的建议。

可以禁止显示任何警告,具体方法是右键单击突出显示的成员,并选择“禁止 <诊断 ID>”。 禁止显示警告的方法有两种:

在本地禁止显示警告

若要在本地禁止显示警告,请右键单击要对其禁止显示警告的成员,再依次选择“快速操作和重构” > “禁止诊断 ID <诊断 ID> > “在源中”。 此时,#pragma 警告预处理器指令会添加到定义的范围内的源代码中:“用 #pragma 警告禁用指令框定的代码屏幕截图”

在全局禁止显示警告

若要在全局禁止显示警告,请右键单击要对其禁止显示警告的成员,再依次选择“快速操作和重构” > “禁止诊断 ID <诊断 ID> > “在禁止文件中”。

“显示绿色波浪线且左侧有灯泡的 WebClient API 屏幕截图”

首次禁止后,GlobalSuppressions.cs 文件会添加到项目中。 此时,新的全局禁止会追加到此文件中。

“显示绿色波浪线且左侧有灯泡的 WebClient API 屏幕截图”

全局禁止是推荐方法,可确保 API 使用跨项目保持一致。

发现跨平台问题

与弃用的 API 类似,分析器可发现所有的非跨平台 API。 例如,xref:System.Console.WindowWidth?displayProperty=nameWithType 适用于 Windows,但不适用于 Linux 和 macOS。 诊断 ID 显示在“错误列表”窗口中。 可以禁止显示警告,具体方法是右键单击并选择“快速操作和重构”。 与禁止显示 API 弃用警告时的两种选择(要么继续使用弃用的成员并禁止显示警告,要么根本就不使用弃用的成员)不同,如果仅对特定平台开发代码,可以对不打算在其上运行代码的其他所有平台禁止显示任何警告。 为此,只需编辑项目文件,并添加列出要忽略的所有平台的 PlatformCompatIgnore 属性即可。 接受的值包括 Linux、macOS 和 Windows。

<PropertyGroup>
    <PlatformCompatIgnore>Linux;macOS</PlatformCompatIgnore>
</PropertyGroup>

如果代码定目标到多个平台,且要利用其中一些平台不支持的 API,可以使用 if 语句作为相应部分代码的临界子句:

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
     var w = Console.WindowWidth;
     // More code
}

可以每目标框架/操作系统进行有条件编译,但暂需要手动这样做。

支持的诊断

目前,分析器处理以下情况:

  • 使用抛出 xref:System.PlatformNotSupportedException 的 .NET Standard API (PC001)。
  • 使用 .NET Framework 4.6.1 不支持的 .NET Standard API (PC002)。
  • 使用 UWP 中不存在的本机 API (PC003)。
  • Delegate.BeginInvoke 和 EndInvoke APIs (PC004) 的用法。
  • 使用标记为弃用的 API (DEXXXX)。

CI 计算机

所有这些诊断不仅可以通过 IDE 获取,还能通过命令行在生成项目期间获取(包括 CI 服务器)。

Configuration

由用户确定应如何处理这些诊断,是生成警告、错误、建议,还是禁用诊断。 例如,作为架构师,可以确定应将兼容性问题处理为错误,对调用某些弃用的 API 生成警告,而对其他情况仅生成建议。 可以按诊断 ID 和按项目单独对此进行配置。 为此,请在“解决方案资源管理器”中转到项目下的“依赖关系”节点。 依次展开节点“依赖关系” > “分析器” > “Microsoft.DotNet.Analyzers.Compatibility”。 右键单击诊断 ID,选择“设置规则集严重性”,并选中相应选项。

“显示诊断和‘设置规则集严重性’弹出对话框的解决方案资源管理器屏幕截图”

请参阅

历史资料。此文对应 2019-08-18 的中文文档快照,适用产品版本和命令行为以原文为准。

来源与署名:Microsoft 和文档贡献者(原始作者元数据 oliag)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。

资料来源与适用范围

资料来源
Microsoft / .NET 中文文档历史快照
适用范围
历史中文快照 2019-08-18;详见原文产品版本;文档日期 04/26/2019
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。