在 .NET runtime 仓库中为构建接入 Roslyn 分析器：包接线、规则调级与验证指南

在 .NET runtime 仓库中为构建接入 Roslyn 分析器：包接线、规则调级与验证指南

【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime

dotnet/runtime（即本仓库）是整个 .NET 平台的核心实现，包含 CoreCLR 运行时、BCL 类库与 Mono 运行时，代码量极为庞大。为保证海量代码的正确性、性能与可维护性，仓库将 .NET Compiler Platform（Roslyn）分析器 为主线，结合 eng/Analyzers.targets 与两份 globalconfig 的真实内容，完整讲解：仓库已接入了哪些分析器、如何新增一个分析器包、如何逐条调整规则严重级别、以及如何在“警告即错误”的默认构建策略下安全地推进新规则落地。读完本文，你将具备在本仓库（以及结构类似的 .NET 大型仓库）中自主接入并驯服 Roslyn 分析器的完整能力。

一、仓库的静态分析体系概览

仓库文档开宗明义：本仓库依赖 .NET Compiler Platform（Roslyn）分析器来帮助校验代码的正确性（correctness）、性能（performance）与可维护性（maintainability）。这不是一套可选的美化工具，而是构建的正式组成部分——分析器通过PackageReference被声明在构建工程文件中，随每次构建加载，扫描仓库中所有编译的源码工程。

从实际接线文件 eng/Analyzers.targets 可以看到，仓库当前默认接入了五个分析器包：

这些包统一声明了PrivateAssets="all"，意味着它们只参与当前工程的编译期分析，不会作为依赖流向下游程序集，也不会污染产物。其中Microsoft.DotNet.CodeAnalysis额外带有IsImplicitlyDefined="true"，表明它是仓库基础设施层面默认隐式提供的。

二、接线文件的运行机制：eng/Analyzers.targets 详解

所有分析器配置的“总开关”都在 eng/Analyzers.targets 中，理解它的几个条件分支，比单纯照抄一条PackageReference重要得多。

2.1 何时彻底关闭分析器

仓库在某些特殊工程类型上会显式关闭分析器，以避免在“根本没有源码可分析”的项目上做无意义的工作，甚至触发依赖解析问题：

<PropertyGroup Condition="'$(UsingMicrosoftNoTargetsSdk)' == 'true' or '$(UsingMicrosoftDotNetSharedFrameworkSdk)' == 'true' or '$(MSBuildProjectExtension)' == '.pkgproj' or '$(UsingMicrosoftTraversalSdk)' == 'true'"> <!-- Explicitly disable running analyzers to avoid trying to discover the correct ILLink tool pack for a project that has no sources. --> <RunAnalyzers>false</RunAnalyzers> </PropertyGroup>

如注释所述，对于 NoTargets SDK、共享框架 SDK、.pkgproj打包工程与 Traversal 聚合工程这类没有编译源文件的项目，强行跑分析器只会浪费时间去找不存在的 ILLink 工具包，因此直接关闭。

此外，在源码构建（sourcebuild）模式下，分析器同样会被关闭：

<RunAnalyzers Condition="'$(DotNetBuildSourceOnly)' == 'true'">false</RunAnalyzers> <EnableNETAnalyzers Condition="'$(EnableNETAnalyzers)' == ''">$(RunAnalyzers)</EnableNETAnalyzers>

这里还揭示了一个重要关系：.NET 官方 NetAnalyzers 是否启用（EnableNETAnalyzers）默认直接跟随RunAnalyzers的值。如果你在命令行显式传入-p:EnableNETAnalyzers=true，则可以单独把它重新打开。

2.2 单文件发布分析器与规则配置文件

在分析器开启的前提下（'$(RunAnalyzers)' != 'false'），对面向.NETCoreApp的源码工程还会默认启用 Single File 分析器，用于在“发布为单文件应用”场景下提前发现Assembly.Location等 API 的误用：

<EnableSingleFileAnalyzer Condition=" '$(EnableSingleFileAnalyzer)' == '' and '$(TargetFrameworkIdentifier)' == '.NETCoreApp' and '$(IsSourceProject)' == 'true'">true</EnableSingleFileAnalyzer>

同时，规则严重级别的配置文件被以EditorConfigFiles形式注入：

<EditorConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.src.globalconfig" />

2.3 源码工程与测试工程使用不同的规则集

这是仓库配置中非常关键的一处设计：测试代码的约束比产品源码宽松得多。IsTestProject为true时，会先移除源码用的CodeAnalysis.src.globalconfig，再换上专门针对测试的CodeAnalysis.test.globalconfig：

<ItemGroup Condition="'$(IsTestProject)' == 'true'"> <EditorConfigFiles Remove="$(RepositoryEngineeringDir)CodeAnalysis.src.globalconfig" /> <EditorConfigFiles Include="$(RepositoryEngineeringDir)CodeAnalysis.test.globalconfig" /> </ItemGroup>

对比如下两份文件即可直观感受差异。以CA1802（Use literals where appropriate）为例：

• 源码配置 eng/CodeAnalysis.src.globalconfig：dotnet_diagnostic.CA1802.severity = warning，并且通过dotnet_code_quality.CA1802.api_surface = private, internal把检查面限定在私有/内部成员上；
• 测试配置 eng/CodeAnalysis.test.globalconfig：dotnet_diagnostic.CA1802.severity = none，直接静默。

再如CA2007（Consider calling ConfigureAwait on the awaited task），源码中是warning，测试中为none。而像SYSLIB1040~SYSLIB1043（InvalidGeneratedRegexAttributeusage）这种会直接产出错误代码的规则，在两份配置中都固定为error，无论源码还是测试都不允许违背。

三、实操：如何向构建中添加一个新的分析器包

文档给出了清晰的三步流程，我们结合仓库实际接线方式逐条展开，并补充每一步的注意事项。

步骤 1：选定要引入的分析器包

文档以 SonarSource 的SonarAnalyzer.CSharp为例——它在 NuGet 上的包名为SonarAnalyzer.CSharp。文档记录到撰写时点的最新版本为8.50.0.58025。选包时需注意两点：

1. 确认包面向的 Roslyn 版本与仓库当前使用的编译器的兼容性——仓库的 Roslyn 版本跟随eng/Versions.props中的MicrosoftCodeAnalysisVersion_LatestVS（当前为5.0.0-2.26070.104）等属性，过老的分析器无法在过新的编译器上运行，反之亦然；
2. 确认规则默认启用的数量——大型分析器包默认启用数百条规则，接入后首次构建会暴露大量诊断，建议先在本地用-warnAsError 0摸底（见第五节）。

步骤 2：在 eng/Analyzers.targets 中添加 PackageReference

打开 eng/Analyzers.targets，在已有的PackageReference组（ItemGroup Condition="'$(RunAnalyzers)' != 'false'"）内追加条目。文档给出的模板如下：

<PackageReference Include="SonarAnalyzer.CSharp" Version="8.50.0.58025" PrivateAssets="all" />

把这条声明放在上述条件组内，意味着：

• 只有在RunAnalyzers未被关闭（非 NoTargets/pkgproj/源码构建等）的工程上才会加载它；
• PrivateAssets="all"保证该分析器不会泄露到下游依赖图中。

步骤 3：在 globalconfig 中调整规则的严重级别

接入新包后，所有默认开启的规则会立即生效。若某些规则过于激进、与仓库既有代码风格冲突，或某些规则需要升级为硬性错误，就在以下两个文件之一中添加对应条目：

• eng/CodeAnalysis.src.globalconfig —— 作用于所有产品源码工程；
• eng/CodeAnalysis.test.globalconfig —— 作用于所有测试工程。

条目格式统一为：

dotnet_diagnostic.<规则ID>.severity = <级别>

可用的严重级别及含义如下：

globalconfig 还支持更精细的作用域控制。例如仓库对CA1052（Static holder types）同时限制了 API 面：

dotnet_diagnostic.CA1052.severity = warning dotnet_code_quality.CA1052.api_surface = private, internal

又如CA2208（Instantiate argument exceptions correctly）限定只检查公开 API：

dotnet_diagnostic.CA2208.severity = warning dotnet_code_quality.CA2208.api_surface = public

dotnet_code_quality.*这一族选项可用于按api_surface（public/internal/private）、按符号种类等维度缩小规则检查范围，是大型代码库中避免误报的利器。

值得一提的是，globalconfig 第一行固定为is_global = true，声明这是一份全局级 EditorConfig 配置，其中的规则设置会应用到整个编译单元，而不受目录层级影响。

四、仓库的自研分析器：PlatformDocAnalyzer 实例

除了消费 NuGet 上的第三方分析器，仓库还在仓库内维护自己的 Roslyn 分析器——eng/analyzers/PlatformDocAnalyzer。其用途（见 eng/analyzers/README.md）是：

强制平台特定类库（启用了UseCompilerGeneratedDocXmlFile=true）遵循文档放置约定。

对于按平台拆分实现的类库（如 Unix/Windows 各自实现），编译期生成的 XML 文档文件在多个目标之间会产生冲突，PlatformDocAnalyzer 通过静态检查保证文档注释被放置在正确的位置。它的接入方式与第三方包不同——不是PackageReference，而是以工程引用的形式注入，并在 eng/Analyzers.targets 中通过属性开关控制：

<!-- PlatformDocAnalyzer: Enforce documentation conventions for platform-specific libraries. Opt-in via EnablePlatformDocAnalyzer; src/libraries enables this by default for src projects. --> <ItemGroup Condition="'$(EnablePlatformDocAnalyzer)' == 'true' and '$(MSBuildProjectExtension)' == '.csproj' and '$(RunAnalyzers)' != 'false'"> <ProjectReference Include="$(RepositoryEngineeringDir)analyzers\PlatformDocAnalyzer\PlatformDocAnalyzer.csproj" ReferenceOutputAssembly="false" OutputItemType="Analyzer" SetConfiguration="Configuration=$(LibrariesConfiguration)" /> </ItemGroup>

注意其中的关键参数：

• EnablePlatformDocAnalyzer为真才启用，src/libraries层默认对源码工程开启（可查src/libraries下的构建属性确认）；
• ReferenceOutputAssembly="false"+OutputItemType="Analyzer"：只把编译产物当作分析器加载，而不是作为普通程序集引用；
• 配套的 PlatformDocAnalyzer.props 被条件导入，用于补充该分析器的属性配置。

该分析器还带有独立测试工程 eng/analyzers/PlatformDocAnalyzer.Tests/PlatformDocAnalyzerTests.cs。仓库明确说明这些测试不进入主 CI 测试流水线（与IntrinsicsInSystemPrivateCoreLibAnalyzer.Tests等基础设施分析器测试一致），修改分析器后需本地手动运行：

dotnet test eng/analyzers/PlatformDocAnalyzer.Tests/PlatformDocAnalyzer.Tests.csproj

这个例子展示了在 dotnet/runtime 中“自研分析器”的标准姿势：分析器本身作为仓库内工程编译，用条件开关接入，并用专门的测试工程守护其行为。

五、处理“警告即错误”的默认策略

仓库的构建系统默认把所有警告当作错误处理。这一点在构建脚本中有直接证据：eng/common/build.ps1 的参数声明[bool] $warnAsError = $true，eng/common/tools.ps1 同样默认$warnAsError = true。

在这种策略下，接入新分析器后的首次构建会极其痛苦：默认开启的成百上千条新规则会在全仓库范围内一次性爆发，而每一条都会让编译直接失败。文档给出的建议是：先临时关闭“警告即错误”，以警告形式暴露全部问题，逐批修复后再恢复为错误。

在仓库根目录正常构建的完整命令为：

build.cmd

（Unix 上为./build.sh。）

临时关闭“警告即错误”：

build.cmd -warnAsError 0

对应的参数在 eng/common/build.sh 中也有明确声明：

--warnAsError <value> Sets warnaserror msbuild parameter ('true' or 'false')

这里传入的0最终会被映射为 MSBuild 的TreatWarningsAsErrors=false。推荐的推进节奏是：

1. 以-warnAsError 0构建，收集新规则的全部告警清单；
2. 将短期内无法修复、或与仓库现状冲突的规则，在对应的 globalconfig 中降为none或suggestion；
3. 对值得强制执行的规则，逐个修复代码后将级别设为warning，并保持warnAsError 1（默认）验证；
4. 全部清零后，把真正重要的规则升级为error（如SYSLIB1040系列的做法）。

六、快速自查清单

接入一个分析器包后，建议按以下清单核验，确保配置正确落位：

七、总结

在 dotnet/runtime 这样规模的仓库中，Roslyn 分析器不是可选项，而是保证代码正确性、性能与可维护性的工程基线。其核心机制可以浓缩为三句话：包接线集中在 eng/Analyzers.targets 一处，规则严重级别通过 eng/CodeAnalysis.src.globalconfig 与 eng/CodeAnalysis.test.globalconfig 按源码/测试双轨管理，默认“警告即错误”的构建策略配合-warnAsError 0提供安全的试错窗口。掌握了这三层，你不仅能按文档指引接入SonarAnalyzer.CSharp等第三方分析器，也能像仓库维护 PlatformDocAnalyzer 一样，沉淀出属于自己的、可测试的仓库级分析规则。

【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime