wshaddix/dotnet-skills/dotnet-add-analyzers

dotnet-add-analyzers

Add and configure .NET code analyzers to an existing project. Covers built-in Roslyn CA rules, nullable reference types enforcement, trimming/AOT compatibility analyzers, and third-party analyzer packages.

Prerequisites: Run [skill:dotnet-version-detection] first — analyzer features vary by SDK version. Run [skill:dotnet-project-analysis] to understand the current project layout.

Cross-references: [skill:dotnet-project-structure] for where build props/targets live, [skill:dotnet-scaffold-project] which includes analyzer setup in new projects, [skill:dotnet-editorconfig] for EditorConfig hierarchy/precedence, IDE* code style preferences, naming rules, and global AnalyzerConfig files.

Built-in Roslyn Analyzers

.NET SDK ships built-in analyzers controlled by AnalysisLevel. Configure in Directory.Build.props:

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

AnalysisLevel Values

latest-all is recommended for new projects. For existing projects with many warnings, start with latest-recommended and tighten over time.

Rule Categories

EditorConfig Severity Overrides

Fine-tune analyzer severity per-rule in .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

Common Suppressions by Project Type

ASP.NET Core apps — suppress ConfigureAwait warnings:

dotnet_diagnostic.CA2007.severity = none

Libraries — keep CA2007 as warning (callers may not have a SynchronizationContext):

dotnet_diagnostic.CA2007.severity = warning

Test projects — relax certain rules:

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

Nullable Reference Types

Enable globally in Directory.Build.props:

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

Nullable analysis produces warnings (CS86xx) not CA rules. Related settings:

<PropertyGroup>
  <!-- Treat nullable warnings as errors -->
  <WarningsAsErrors>$(WarningsAsErrors);nullable</WarningsAsErrors>
</PropertyGroup>

For gradual adoption in existing codebases, enable per-file:

#nullable enable

See [skill:dotnet-csharp-nullable-reference-types] for annotation strategies and patterns.

Trimming and AOT Compatibility Analyzers

Applications

For apps published with trimming or Native AOT, enable the analyzers alongside the publish properties:

<PropertyGroup>
  <!-- Enable trimmed publishing + analysis -->
  <PublishTrimmed>true</PublishTrimmed>
  <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
 
  <!-- Enable AOT publishing + analysis -->
  <PublishAot>true</PublishAot>
  <EnableAotAnalyzer>true</EnableAotAnalyzer>
 
  <!-- Single-file analysis (subset of trim analysis) -->
  <EnableSingleFileAnalyzer>true</EnableSingleFileAnalyzer>
</PropertyGroup>

Enable the analyzers early (even before publishing trimmed) to catch issues during development. EnableTrimAnalyzer and EnableAotAnalyzer can be set independently of PublishTrimmed/PublishAot.

Libraries

Libraries use IsTrimmable and IsAotCompatible to declare compatibility to consumers. Enable these even if consumers don't trim yet:

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

Setting IsTrimmable/IsAotCompatible automatically enables the corresponding analyzers. This ensures the library works correctly when consumers eventually enable trimming/AOT.

What the Analyzers Flag

These analyzers flag:

• Reflection usage that breaks trimming (IL2xxx warnings)
• P/Invoke patterns incompatible with AOT
• Dynamic code generation (Reflection.Emit, System.Linq.Expressions compilation)
• Types not annotated with [DynamicallyAccessedMembers]

Third-Party Analyzers

Add via Directory.Build.targets so they apply to all projects:

<!-- Directory.Build.targets -->
<Project>
  <ItemGroup>
    <PackageReference Include="Meziantou.Analyzer" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" PrivateAssets="all" />
  </ItemGroup>
</Project>

With CPM, add version entries in Directory.Packages.props:

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

Recommended Analyzer Packages

BannedSymbols.txt

When using BannedApiAnalyzers, create BannedSymbols.txt at the repo root and include it:

<!-- Directory.Build.targets -->
<ItemGroup>
  <AdditionalFiles Include="$(MSBuildThisFileDirectory)BannedSymbols.txt"
                   Condition="Exists('$(MSBuildThisFileDirectory)BannedSymbols.txt')" />
</ItemGroup>

Example 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

Adding Analyzers to an Existing Project

1. Enable built-in analyzers — set AnalysisLevel and EnforceCodeStyleInBuild in Directory.Build.props
2. Start at recommended level — use latest-recommended if latest-all produces too many warnings
3. Add EditorConfig overrides — suppress rules that don't apply to your project type
4. Add third-party analyzers — via Directory.Build.targets with CPM versions
5. Fix incrementally — enable TreatWarningsAsErrors only after addressing existing warnings, or use <NoWarn> temporarily for categories being addressed

Incremental Adoption Pattern

For large codebases, avoid fixing all warnings at once:

<!-- Directory.Build.props — temporary during migration -->
<PropertyGroup>
  <AnalysisLevel>latest-recommended</AnalysisLevel>
  <!-- Fix these categories first, then remove NoWarn entries -->
  <NoWarn>$(NoWarn);CA1822;CA1848</NoWarn>
</PropertyGroup>

Remove NoWarn entries as each category is addressed. Track progress with:

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

References

• Code Analysis Overview
• Configure Analyzers
• Trimming Analyzer
• AOT Compatibility
• EditorConfig for .NET