Dotnet Roslyn Analyzers

dotnet-roslyn-analyzers

Guidance for authoring custom Roslyn analyzers, code fix providers, code refactoring providers, and diagnostic suppressors. Covers project setup, DiagnosticDescriptor conventions, analysis context registration, code fix actions, code refactoring actions, multi-Roslyn-version targeting (3.8 through 4.14), testing with Microsoft.CodeAnalysis.Testing, NuGet packaging, and performance best practices.

For extended code examples (CodeRefactoringProvider implementation, multi-version project structure, test matrix configuration), see details.md in this skill directory.

Scope

• DiagnosticAnalyzer authoring and analysis context registration
• CodeFixProvider and CodeRefactoringProvider implementation
• Multi-Roslyn-version targeting (3.8 through 4.14)
• Testing with Microsoft.CodeAnalysis.Testing
• NuGet packaging for analyzer assemblies

Out of scope

• Consuming and configuring existing analyzers (CA rules, severity) -- see [skill:dotnet-add-analyzers]
• Authoring source generators (IIncrementalGenerator) -- see [skill:dotnet-csharp-source-generators]
• Naming conventions -- see [skill:dotnet-csharp-coding-standards]

Cross-references: [skill:dotnet-csharp-source-generators] for shared Roslyn packaging concepts and IIncrementalGenerator patterns, [skill:dotnet-add-analyzers] for consuming and configuring analyzers, [skill:dotnet-testing-strategy] for general test organization and framework selection, [skill:dotnet-csharp-coding-standards] for naming conventions applied to analyzer code.

Project Setup

Analyzer projects must target netstandard2.0. The compiler loads analyzers into various host processes (Visual Studio on .NET Framework/Mono, MSBuild on .NET Core, dotnet build CLI) -- targeting net8.0+ breaks compatibility with hosts that do not run on that runtime.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
    <IsRoslynComponent>true</IsRoslynComponent>
    <LangVersion>latest</LangVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" PrivateAssets="all" />
  </ItemGroup>
</Project>

• EnforceExtendedAnalyzerRules enables RS-series meta-diagnostics that catch common analyzer authoring mistakes.
• IsRoslynComponent enables IDE tooling support for the project.
• LangVersion>latest lets you write modern C# in the analyzer itself while still targeting netstandard2.0.
• All Roslyn SDK packages must use PrivateAssets="all" to avoid shipping them as transitive dependencies.

DiagnosticAnalyzer

Every analyzer inherits from DiagnosticAnalyzer and must be decorated with [DiagnosticAnalyzer(LanguageNames.CSharp)].

[DiagnosticAnalyzer(LanguageNames.CSharp)]
public sealed class NoPublicFieldsAnalyzer : DiagnosticAnalyzer
{
    public const string DiagnosticId = "MYLIB001";

    private static readonly DiagnosticDescriptor Rule = new(
        id: DiagnosticId,
        title: "Public fields should be properties",
        messageFormat: "Field '{0}' is public; use a property instead",
        category: "Design",
        defaultSeverity: DiagnosticSeverity.Warning,
        isEnabledByDefault: true,
        helpLinkUri: $"https://example.com/docs/rules/{DiagnosticId}");

    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; }
        = ImmutableArray.Create(Rule);

    public override void Initialize(AnalysisContext context)
    {
        context.EnableConcurrentExecution();
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
        context.RegisterSymbolAction(AnalyzeField, SymbolKind.Field);
    }

    private static void AnalyzeField(SymbolAnalysisContext context)
    {
        var field = (IFieldSymbol)context.Symbol;
        if (field.DeclaredAccessibility == Accessibility.Public
            && !field.IsConst && !field.IsReadOnly)
        {
            context.ReportDiagnostic(Diagnostic.Create(Rule, field.Locations[0], field.Name));
        }
    }
}

Analysis Context Registration

DiagnosticDescriptor Conventions

ID Prefix Patterns

Avoid prefixes reserved by the .NET platform: CA, CS, RS, IDE, IL, SYSLIB.

Severity Selection

Default to Warning for most rules. Always provide a non-null helpLinkUri (RS1015 enforces this).

CodeFixProvider

Code fix providers offer automated corrections for diagnostics. Key patterns:

• EquivalenceKey: Every CodeAction must have a unique equivalenceKey for FixAll support (RS1010, RS1011)
• Document vs. Solution modification: Use createChangedDocument for single-file fixes, createChangedSolution for cross-file renames
• Trivia preservation: Always transfer leading/trailing trivia from replaced nodes
• FixAllProvider: Return WellKnownFixAllProviders.BatchFixer for batch-applicable fixes

See details.md for the complete CodeFixProvider implementation with property conversion.

DiagnosticSuppressor

Conditionally suppresses diagnostics from other analyzers when EditorConfig cannot express the suppression condition. Requires Roslyn 3.8+.

Multi-Roslyn-Version Targeting

Version Boundaries

Use conditional compilation constants (ROSLYN_X_Y_OR_GREATER) and version-specific NuGet paths (analyzers/dotnet/roslyn{version}/cs/). See details.md for the complete multi-version project structure.

Testing Analyzers

Use Microsoft.CodeAnalysis.Testing for ergonomic analyzer testing:

using Verify = Microsoft.CodeAnalysis.CSharp.Testing.CSharpAnalyzerVerifier<
    NoPublicFieldsAnalyzer,
    Microsoft.CodeAnalysis.Testing.DefaultVerifier>;

public class NoPublicFieldsAnalyzerTests
{
    [Fact]
    public async Task PublicField_ReportsDiagnostic()
    {
        var test = """
            public class MyClass
            {
                public int {|MYLIB001:Value|};
            }
            """;
        await Verify.VerifyAnalyzerAsync(test);
    }
}

Diagnostic Markup Syntax

NuGet Packaging

Analyzers ship as NuGet packages with assemblies in analyzers/dotnet/cs/, not lib/.

<PropertyGroup>
  <IncludeBuildOutput>false</IncludeBuildOutput>
  <DevelopmentDependency>true</DevelopmentDependency>
  <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>
</PropertyGroup>

<ItemGroup>
  <None Include="$(OutputPath)\$(AssemblyName).dll"
        Pack="true"
        PackagePath="analyzers/dotnet/cs" />
</ItemGroup>

Performance Best Practices

• Resolve types once per compilation inside RegisterCompilationStartAction, not per-node/symbol callbacks
• Cache SupportedDiagnostics as ImmutableArray field, not expression-bodied property
• Enable concurrent execution -- always call context.EnableConcurrentExecution()
• Filter early -- register for the most specific SyntaxKind possible
• Avoid Compilation.GetSemanticModel() -- use the SemanticModel from the analysis context (RS1030)

Common Meta-Diagnostics (RS-Series)

References

• Tutorial: Write your first analyzer and code fix
• Roslyn SDK overview
• Microsoft.CodeAnalysis.Testing
• Analyzer NuGet packaging conventions
• dotnet/roslyn-analyzers (RS diagnostic source)
• Meziantou.Analyzer (exemplar project)