dotnet-add-analyzers

dotnet-add-analyzers

为现有项目添加并配置 .NET 代码分析器。涵盖内置 Roslyn CA 规则、可空引用类型强制检查、修剪/AOT 兼容性分析器以及第三方分析器包。

**前提条件：**请先运行 [skill:dotnet-version-detection]——分析器功能因 SDK 版本而异。运行 [skill:dotnet-project-analysis] 以了解当前项目布局。

交叉引用：[skill:dotnet-project-structure] 介绍构建属性/目标的位置，[skill:dotnet-scaffold-project] 在新项目中包含分析器设置，[skill:dotnet-editorconfig] 介绍 EditorConfig 层级/优先级、IDE* 代码样式首选项、命名规则和全局 AnalyzerConfig 文件。

---

内置 Roslyn 分析器

.NET SDK 附带由 AnalysisLevel 控制的内置分析器。在 Directory.Build.props 中配置：

<PropertyGroup>
  <AnalysisLevel>latest-all</AnalysisLevel>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>

AnalysisLevel 值

值	行为
latest	仅默认规则——涵盖正确性，不涵盖样式
latest-minimum	规则少于默认配置
latest-recommended	默认规则 + 其他推荐规则
latest-all	启用所有规则——覆盖最全面
9-all、10-all	固定使用特定 SDK 版本的完整规则集

新项目建议使用 latest-all。对于警告较多的现有项目，可先使用 latest-recommended，再逐步收紧规则。

规则类别

类别	前缀	示例
设计	CA1xxx	CA1002（不要公开泛型列表）、CA1062（验证参数）
全球化	CA1300–CA1399	CA1304（指定 CultureInfo）
性能	CA1800–CA1899	CA1822（将成员标记为静态）、CA1848（使用 LoggerMessage）
可靠性	CA2000–CA2099	CA2000（释放对象）、CA2007（ConfigureAwait）
安全性	CA2100–CA2199、CA3xxx、CA5xxx	CA2100（SQL 注入）、CA3075（XML 处理）
用法	CA2200–CA2299	CA2211（非 const 静态字段）、CA2245（不要赋值给自身）
命名	CA1700–CA1799	CA1707（标识符中不要使用下划线）
样式	IDE0xxx	IDE0003（this 限定）、IDE0063（using 声明）

---

EditorConfig 严重性覆盖

在 .editorconfig 中按规则微调分析器严重性：

[*.cs]
# Suppress specific rules
dotnet_diagnostic.CA1062.severity = none          # Nullable handles this
dotnet_diagnostic.CA2007.severity = none          # Not needed in ASP.NET Core apps

# Escalate to error
dotnet_diagnostic.CA1822.severity = error         # Mark members as static
dotnet_diagnostic.CA1848.severity = warning       # Use LoggerMessage delegates

# Style enforcement
dotnet_diagnostic.IDE0005.severity = warning      # Remove unnecessary usings
dotnet_diagnostic.IDE0063.severity = warning      # Use simple using statement
dotnet_diagnostic.IDE0090.severity = warning      # Simplify new expression

按项目类型常见的禁用项

ASP.NET Core 应用——禁用 ConfigureAwait 警告：

dotnet_diagnostic.CA2007.severity = none

库——将 CA2007 保持为警告（调用方可能没有 SynchronizationContext）：

dotnet_diagnostic.CA2007.severity = warning

测试项目——放宽某些规则：

dotnet_diagnostic.CA1707.severity = none          # Allow underscores in test names
dotnet_diagnostic.CA1062.severity = none          # Parameters validated by test framework
dotnet_diagnostic.CA2007.severity = none          # ConfigureAwait not relevant

---

可空引用类型

在 Directory.Build.props 中全局启用：

<PropertyGroup>
  <Nullable>enable</Nullable>
</PropertyGroup>

可空性分析会产生警告（CS86xx），而非 CA 规则。相关设置：

<PropertyGroup>
  
  <WarningsAsErrors>$(WarningsAsErrors);nullable</WarningsAsErrors>
</PropertyGroup>

对于逐步采用可空引用类型的现有代码库，可按文件启用：

#nullable enable

请参阅 [skill:dotnet-csharp-nullable-reference-types]，了解注解策略和模式。

---

修剪和 AOT 兼容性分析器

应用程序

对于使用修剪或 Native AOT 发布的应用，请同时启用分析器和发布属性：

<PropertyGroup>
  
  <PublishTrimmed>true</PublishTrimmed>
  <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

  
  <PublishAot>true</PublishAot>
  <EnableAotAnalyzer>true</EnableAotAnalyzer>

  
  <EnableSingleFileAnalyzer>true</EnableSingleFileAnalyzer>
</PropertyGroup>

尽早启用分析器（即使尚未进行修剪发布），以便在开发期间发现问题。EnableTrimAnalyzer 和 EnableAotAnalyzer 可独立于 PublishTrimmed/PublishAot 设置。

库

库使用 IsTrimmable 和 IsAotCompatible 向使用方声明兼容性。即使使用方尚未启用修剪，也应启用这些属性：

<PropertyGroup>
  <IsTrimmable>true</IsTrimmable>
  <IsAotCompatible>true</IsAotCompatible>
</PropertyGroup>

设置 IsTrimmable/IsAotCompatible 会自动启用相应的分析器。这可确保使用方最终启用修剪/AOT 时，库仍能正常工作。

分析器会标记哪些问题

这些分析器会标记：

• 会导致修剪失败的反射用法（IL2xxx 警告）
• 与 AOT 不兼容的 P/Invoke 模式
• 动态代码生成（Reflection.Emit、System.Linq.Expressions 编译）
• 未使用 [DynamicallyAccessedMembers] 注解的类型

---

第三方分析器

在 Directory.Build.targets 中添加，使其应用于所有项目：

<Project>
  <ItemGroup>
    <PackageReference Include="Meziantou.Analyzer" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" PrivateAssets="all" />
  </ItemGroup>
</Project>

使用 CPM 时，在 Directory.Packages.props 中添加版本条目：

<PackageVersion Include="Meziantou.Analyzer" Version="2.0.187" />
<PackageVersion Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" Version="3.11.0-beta1.25058.1" />

推荐的分析器包

包	重点
Meziantou.Analyzer	安全性、性能、最佳实践（覆盖面广）
Microsoft.CodeAnalysis.BannedApiAnalyzers	通过 BannedSymbols.txt 禁用特定 API
Microsoft.CodeAnalysis.PublicApiAnalyzers	跟踪公共 API 范围（适用于库作者）
SonarAnalyzer.CSharp	安全性、可靠性、可维护性

BannedSymbols.txt

使用 BannedApiAnalyzers 时，在仓库根目录创建 BannedSymbols.txt 并将其包含进来：

<ItemGroup>
  <AdditionalFiles Include="$(MSBuildThisFileDirectory)BannedSymbols.txt"
                   Condition="Exists('$(MSBuildThisFileDirectory)BannedSymbols.txt')" />
</ItemGroup>

BannedSymbols.txt 示例：

T:System.DateTime;Use DateTimeOffset instead
M:System.DateTime.Now;Use DateTimeOffset.UtcNow instead
T:System.GC;Do not call GC methods directly

---

为现有项目添加分析器

1. 启用内置分析器 — 在 Directory.Build.props 中设置 AnalysisLevel 和 EnforceCodeStyleInBuild
2. 从推荐级别开始 — 如果 latest-all 产生过多警告，则使用 latest-recommended
3. 添加 EditorConfig 覆盖项 — 禁用不适用于项目类型的规则
4. 添加第三方分析器 — 通过 Directory.Build.targets 和 CPM 版本进行添加
5. 逐步修复 — 仅在处理完现有警告后启用 TreatWarningsAsErrors，或暂时使用 <NoWarn> 忽略正在处理的类别

渐进式采用模式

对于大型代码库，不要一次性修复所有警告：

<PropertyGroup>
  <AnalysisLevel>latest-recommended</AnalysisLevel>
  
  <NoWarn>$(NoWarn);CA1822;CA1848</NoWarn>
</PropertyGroup>

处理完每个类别后，移除相应的 NoWarn 条目。使用以下方式跟踪进度：

dotnet build 2>&1 | grep -oE 'CA[0-9]+' | sort | uniq -c | sort -rn

---

参考资料

• 代码分析概述
• 配置分析器
• 修剪分析器
• AOT 兼容性
• 适用于 .NET 的 EditorConfig