Roslyn编译器API实战：用C#编写自定义代码分析器

一、Roslyn编译器API是什么？

Roslyn是微软开源的.NET编译器平台，它把C#和VB.NET的编译过程完全暴露给开发者。简单来说，它不再是一个黑盒子，而是变成了我们可以直接调用的API。想象一下，你不仅能得到编译结果，还能在编译过程中"插一脚"，这就是Roslyn的魅力所在。

传统编译器就像个固执的老头，只给你最终结果。而Roslyn更像是个乐于助人的邻居，不仅告诉你结果，还愿意跟你分享中间过程。你可以用它来分析代码结构、修改代码、甚至自己造轮子。

二、为什么要自定义代码分析器？

在日常开发中，我们经常会遇到一些重复性的代码问题。比如团队约定所有DTO属性必须大写开头，但总有人忘记；或者某些特定API必须包含日志调用。这些规则用人工检查效率太低，用传统静态分析工具又不够灵活。

这时候自定义代码分析器就派上用场了。它能在你写代码时就实时检查，发现问题立即提示，就像有个经验丰富的同事在旁边做code review。而且它直接集成在Visual Studio中，不需要额外工具。

三、手把手创建第一个分析器

让我们用C#和.NET Core 3.1创建一个简单的分析器，检查类名是否遵循大驼峰命名法。下面是完整示例：

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Diagnostics;
using System.Collections.Immutable;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;

// 1. 定义诊断描述
public static class DiagnosticDescriptors
{
    public static readonly DiagnosticDescriptor ClassNamingRule = new DiagnosticDescriptor(
        id: "CLS001",
        title: "类名必须使用大驼峰命名法",
        messageFormat: "类名 '{0}' 未使用大驼峰命名法",
        category: "Naming",
        defaultSeverity: DiagnosticSeverity.Warning,
        isEnabledByDefault: true);
}

// 2. 创建分析器
[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class ClassNamingAnalyzer : DiagnosticAnalyzer
{
    // 3. 注册支持的诊断
    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics 
        => ImmutableArray.Create(DiagnosticDescriptors.ClassNamingRule);

    // 4. 初始化分析器
    public override void Initialize(AnalysisContext context)
    {
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
        context.EnableConcurrentExecution();
        
        // 注册对类声明的分析
        context.RegisterSyntaxNodeAction(AnalyzeClassDeclaration, SyntaxKind.ClassDeclaration);
    }

    // 5. 具体分析方法
    private static void AnalyzeClassDeclaration(SyntaxNodeAnalysisContext context)
    {
        var classDeclaration = (ClassDeclarationSyntax)context.Node;
        var className = classDeclaration.Identifier.Text;

        // 检查类名是否符合大驼峰命名法
        if (className.Length > 0 && !char.IsUpper(className[0]))
        {
            var diagnostic = Diagnostic.Create(
                DiagnosticDescriptors.ClassNamingRule,
                classDeclaration.Identifier.GetLocation(),
                className);
            
            context.ReportDiagnostic(diagnostic);
        }
    }
}

这个分析器会检查所有类名，如果发现不是以大写字母开头，就会在Visual Studio中显示警告。要使用它，你需要创建一个VSIX扩展项目，这里就不展开讲了。

四、更复杂的分析器示例

让我们看个更实际的例子：检查异步方法是否以"Async"结尾。这是.NET中的常见约定，但很容易被忽略。

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Diagnostics;
using System.Collections.Immutable;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;

public static class DiagnosticDescriptors
{
    public static readonly DiagnosticDescriptor AsyncMethodNamingRule = new DiagnosticDescriptor(
        id: "ASYNC001",
        title: "异步方法名应以'Async'结尾",
        messageFormat: "异步方法 '{0}' 名称应以'Async'结尾",
        category: "Naming",
        defaultSeverity: DiagnosticSeverity.Warning,
        isEnabledByDefault: true);
}

[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class AsyncMethodNamingAnalyzer : DiagnosticAnalyzer
{
    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics 
        => ImmutableArray.Create(DiagnosticDescriptors.AsyncMethodNamingRule);

    public override void Initialize(AnalysisContext context)
    {
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
        context.EnableConcurrentExecution();
        context.RegisterSyntaxNodeAction(AnalyzeMethodDeclaration, SyntaxKind.MethodDeclaration);
    }

    private static void AnalyzeMethodDeclaration(SyntaxNodeAnalysisContext context)
    {
        var methodDeclaration = (MethodDeclarationSyntax)context.Node;
        
        // 检查方法是否有async修饰符
        if (methodDeclaration.Modifiers.Any(SyntaxKind.AsyncKeyword))
        {
            var methodName = methodDeclaration.Identifier.Text;
            
            // 检查方法名是否以Async结尾
            if (!methodName.EndsWith("Async"))
            {
                var diagnostic = Diagnostic.Create(
                    DiagnosticDescriptors.AsyncMethodNamingRule,
                    methodDeclaration.Identifier.GetLocation(),
                    methodName);
                
                context.ReportDiagnostic(diagnostic);
            }
        }
    }
}

这个分析器会检查所有标记为async的方法，确保它们的名称以"Async"结尾。这样能帮助团队保持一致的编码风格。

五、代码修复提供程序

光发现问题还不够，最好还能自动修复。Roslyn提供了CodeFixProvider来实现这个功能。让我们扩展上面的异步方法分析器，添加自动修复功能。

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CodeFixes;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using System.Collections.Immutable;
using System.Threading.Tasks;
using System.Linq;

[ExportCodeFixProvider(LanguageNames.CSharp, Name = nameof(AsyncMethodNamingCodeFixProvider))]
public class AsyncMethodNamingCodeFixProvider : CodeFixProvider
{
    // 1. 注册支持的诊断ID
    public sealed override ImmutableArray<string> FixableDiagnosticIds 
        => ImmutableArray.Create("ASYNC001");

    // 2. 注册修复提供程序
    public sealed override FixAllProvider GetFixAllProvider() => WellKnownFixAllProviders.BatchFixer;

    // 3. 注册代码修复
    public sealed override async Task RegisterCodeFixesAsync(CodeFixContext context)
    {
        var root = await context.Document.GetSyntaxRootAsync(context.CancellationToken);
        var diagnostic = context.Diagnostics.First();
        var diagnosticSpan = diagnostic.Location.SourceSpan;

        // 4. 找到有问题的语法节点
        var declaration = root.FindToken(diagnosticSpan.Start).Parent
            .AncestorsAndSelf().OfType<MethodDeclarationSyntax>().First();

        // 5. 注册修复操作
        context.RegisterCodeFix(
            CodeAction.Create(
                title: "添加'Async'后缀",
                createChangedDocument: c => AddAsyncSuffix(context.Document, declaration, c),
                equivalenceKey: "AddAsyncSuffix"),
            diagnostic);
    }

    // 6. 实际修复逻辑
    private async Task<Document> AddAsyncSuffix(
        Document document, 
        MethodDeclarationSyntax methodDecl, 
        CancellationToken cancellationToken)
    {
        // 获取旧方法名和新方法名
        var identifierToken = methodDecl.Identifier;
        var newName = identifierToken.Text + "Async";

        // 创建新语法树
        var root = await document.GetSyntaxRootAsync(cancellationToken);
        var newRoot = root.ReplaceNode(
            methodDecl,
            methodDecl.WithIdentifier(SyntaxFactory.Identifier(newName)));

        // 返回新文档
        return document.WithSyntaxRoot(newRoot);
    }
}

现在当分析器发现问题时，不仅会提示警告，还会提供快速修复选项。开发者只需点击灯泡图标，选择"添加'Async'后缀"，就能自动修正方法名。

六、实际应用场景

自定义代码分析器在实际项目中有很多应用场景：

代码规范检查：确保团队遵循命名约定、代码结构等规范
安全审计：检查潜在的安全漏洞，如硬编码密码、不安全的API调用
性能优化：识别可能导致性能问题的代码模式
API使用约束：确保特定API被正确使用，比如必须配合using或try-finally
架构约束：防止项目间的非法依赖，确保架构分层

比如，你可以创建一个分析器来检查仓储层是否直接调用了服务层的类，这在分层架构中通常是不允许的。

七、技术优缺点分析

优点：

实时反馈：开发者写代码时就能看到问题，不用等到编译或CI环节
高度定制：可以根据团队或项目需求定制规则
无缝集成：直接集成到Visual Studio中，体验与内置功能一致
性能良好：Roslyn分析器经过优化，对IDE性能影响很小
共享方便：可以通过NuGet包分发分析器

缺点：

学习曲线：需要理解Roslyn API和语法树概念
调试困难：分析器的调试过程比普通代码复杂
版本兼容：不同VS版本对分析器的支持可能有差异
规则冲突：自定义规则可能与现有规则或第三方分析器冲突

八、注意事项

性能考虑：分析器会在每次代码更改时运行，要确保你的分析逻辑高效
错误处理：分析器崩溃会影响IDE体验，务必做好错误处理
明确范围：不要试图用分析器实现所有检查，有些问题更适合用单元测试或运行时检查
渐进采用：刚开始可以只设Warning级别，等团队适应后再改为Error
文档支持：为自定义规则编写清晰的文档，说明为什么需要这条规则

九、总结

Roslyn编译器API为我们打开了一扇新的大门，让编译器从封闭的工具变成了可编程的平台。通过自定义代码分析器，我们可以把团队的最佳实践和规范直接融入到开发环境中，在问题刚出现时就及时发现和纠正。

虽然有一定的学习成本，但投入是值得的。一个好的自定义分析器可以显著提高代码质量，减少代码审查负担，让团队把精力集中在更有价值的事情上。

从简单的命名规范检查到复杂的架构约束，Roslyn分析器都能胜任。结合代码修复提供程序，甚至可以实现"一键修复"，大大提升开发效率。

敲码拾光专注于编程技术，涵盖编程语言、代码实战案例、软件开发技巧、IT前沿技术、编程开发工具，是您提升技术能力的优质网络平台。