C#代码分析器（Roslyn Analyzer）开发指南

一、C# 代码分析器（Roslyn Analyzer）概述

1.1 Roslyn 简介

Roslyn 是 .NET 编译器平台，它为 C# 和 Visual Basic 语言提供了一种全新的编译器实现方式。与传统编译器不同，Roslyn 以开源库的形式存在，使得开发者能够深入编译器内部，对代码进行语法分析、语义分析等操作。它为开发者提供了丰富的 API，这些 API 可以用于构建代码分析工具、代码生成工具、重构工具等。

1.2 Roslyn Analyzer 是什么

Roslyn Analyzer（代码分析器）是基于 Roslyn 编译器平台开发的一种工具，它能够在编译期间对 C# 代码进行分析，并发现潜在的问题、提供改进建议等。这些分析器可以检查代码是否符合特定的编码规范，是否存在性能问题、安全漏洞等。例如，一个分析器可以检测到代码中未使用的变量，并给出警告提示，帮助开发者清理无用代码，提高代码质量。

二、开发环境搭建

2.1 安装 Visual Studio

首先，你需要安装 Visual Studio。Visual Studio 是开发 .NET 应用程序的主要 IDE，它为 Roslyn Analyzer 的开发提供了良好的支持。建议安装最新版本的 Visual Studio，以获取最新的功能和修复。在安装 Visual Studio 时，确保勾选了“.NET 桌面开发”和“Visual Studio 扩展开发”工作负载，这两个工作负载提供了开发 Roslyn Analyzer 所需的工具和模板。

2.2 创建 Roslyn Analyzer 项目

打开 Visual Studio，选择“创建新项目”。在搜索框中输入“Analyzer with Code Fix”，选择对应的项目模板（适用于 C#）。为项目命名并选择存储位置后，点击“创建”按钮。Visual Studio 会自动生成一个基本的 Roslyn Analyzer 项目结构，其中包含一个分析器类和一个代码修复提供程序类（如果选择的是带有代码修复的模板）。

三、理解语法树和语义模型

3.1 语法树

语法树是代码的一种结构化表示，它按照编程语言的语法规则将代码分解成一个个节点。在 Roslyn 中，你可以通过语法分析器生成语法树。例如，对于以下简单的 C# 代码：

int num = 10;

语法树会将其分解为变量声明节点（int num）和赋值表达式节点（num = 10）。通过遍历语法树，分析器可以获取代码的结构信息，比如变量的声明位置、类型等。

3.2 语义模型

语义模型建立在语法树之上，它提供了代码的语义信息，例如变量的作用域、类型解析等。语义模型能够回答诸如“这个变量在哪里声明的？”“这个方法调用是否有效？”等问题。例如，对于下面的代码：

class Program
{
    static void Main()
    {
        int num = 10;
        Console.WriteLine(num);
    }
}

语义模型可以确定Console.WriteLine调用是有效的，因为它知道Console类型存在且有WriteLine方法，并且num变量在调用处是可见的。

四、编写基本的 Roslyn Analyzer

4.1 分析器类结构

一个基本的 Roslyn Analyzer 类继承自DiagnosticAnalyzer类。在类中，你需要重写Initialize方法，在这个方法中注册分析器感兴趣的语法节点或符号。例如：

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

[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class MyAnalyzer : DiagnosticAnalyzer
{
    public const string DiagnosticId = "MyAnalyzer001";
    private static readonly LocalizableString Title = new LocalizableResourceString(nameof(Resources.AnalyzerTitle), Resources.ResourceManager, typeof(Resources));
    private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(Resources.AnalyzerMessageFormat), Resources.ResourceManager, typeof(Resources));
    private static readonly LocalizableString Description = new LocalizableResourceString(nameof(Resources.AnalyzerDescription), Resources.ResourceManager, typeof(Resources));
    private const string Category = "Naming";

    private static DiagnosticDescriptor Rule = new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, Category, DiagnosticSeverity.Warning, isEnabledByDefault: true, description: Description);

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

    public override void Initialize(AnalysisContext context)
    {
        context.RegisterSymbolAction(AnalyzeSymbol, SymbolKind.NamedType);
    }

    private void AnalyzeSymbol(SymbolAnalysisContext context)
    {
        var namedTypeSymbol = (INamedTypeSymbol)context.Symbol;
        if (namedTypeSymbol.Name.StartsWith("_"))
        {
            var diagnostic = Diagnostic.Create(Rule, namedTypeSymbol.Locations[0], namedTypeSymbol.Name);
            context.ReportDiagnostic(diagnostic);
        }
    }
}

在上述代码中，分析器检查类名是否以下划线开头，如果是，则报告一个警告。

4.2 注册分析方法

在Initialize方法中，通过context.RegisterSymbolAction方法注册对特定符号类型的分析方法。这里注册了对SymbolKind.NamedType（命名类型，如类、接口等）的分析方法AnalyzeSymbol。你也可以注册对语法节点的分析，例如context.RegisterSyntaxNodeAction方法用于注册对语法节点的分析。

4.3 报告诊断信息

当分析器发现问题时，需要创建一个Diagnostic对象并通过context.ReportDiagnostic方法报告。Diagnostic对象包含诊断规则（DiagnosticDescriptor）、问题所在位置（Location）以及相关的参数（用于格式化消息）。

五、处理语法节点

5.1 遍历语法树

要处理语法节点，通常需要遍历语法树。Roslyn 提供了多种方式来遍历语法树，比如使用SyntaxWalker类。下面是一个简单的例子，遍历所有的方法声明节点：

using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;

class MethodDeclarationWalker : SyntaxWalker
{
    public override void VisitMethodDeclaration(MethodDeclarationSyntax node)
    {
        // 处理方法声明节点
        Console.WriteLine($"Method: {node.Identifier.Text}");
        base.VisitMethodDeclaration(node);
    }
}

然后可以在分析器中使用这个SyntaxWalker：

public override void Initialize(AnalysisContext context)
{
    context.RegisterSyntaxNodeAction(AnalyzeSyntaxNode, SyntaxKind.MethodDeclaration);
}

private void AnalyzeSyntaxNode(SyntaxNodeAnalysisContext context)
{
    var methodDeclaration = (MethodDeclarationSyntax)context.Node;
    var walker = new MethodDeclarationWalker();
    walker.Visit(methodDeclaration);
}

5.2 访问语法节点属性

语法节点有许多属性，可以获取节点的详细信息。例如，MethodDeclarationSyntax节点有Identifier属性获取方法名，ParameterList属性获取参数列表等。对于以下方法声明：

public void MyMethod(int param)
{
    // 方法体
}

通过MethodDeclarationSyntax节点的ParameterList.Parameters[0].Type可以获取第一个参数的类型。

六、处理符号

6.1 符号的概念

符号是 Roslyn 中表示代码元素（如类型、方法、变量等）的抽象。符号包含了语义信息，通过符号可以了解代码元素的更多信息，如继承关系、成员列表等。例如，INamedTypeSymbol表示命名类型符号，可以获取类型的名称、基类型、实现的接口等信息。

6.2 获取符号信息

在分析器中，可以通过SyntaxNodeAnalysisContext或SymbolAnalysisContext获取符号。例如，在SymbolAnalysisContext中，可以直接获取当前分析的符号：

private void AnalyzeSymbol(SymbolAnalysisContext context)
{
    var namedTypeSymbol = (INamedTypeSymbol)context.Symbol;
    Console.WriteLine($"Type: {namedTypeSymbol.Name}, Base Type: {namedTypeSymbol.BaseType?.Name}");
}

在SyntaxNodeAnalysisContext中，可以通过context.SemanticModel.GetSymbolInfo方法获取符号：

private void AnalyzeSyntaxNode(SyntaxNodeAnalysisContext context)
{
    var identifierSyntax = (IdentifierNameSyntax)context.Node;
    var symbolInfo = context.SemanticModel.GetSymbolInfo(identifierSyntax);
    var symbol = symbolInfo.Symbol;
    if (symbol != null)
    {
        Console.WriteLine($"Symbol: {symbol.Name}");
    }
}

七、代码修复（Code Fix）

7.1 代码修复提供程序类结构

代码修复提供程序类继承自CodeFixProvider类。在类中，需要重写RegisterCodeFixesAsync方法，在这个方法中注册代码修复操作。例如：

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

[ExportCodeFixProvider(LanguageNames.CSharp, Name = nameof(MyCodeFixProvider)), Shared]
public class MyCodeFixProvider : CodeFixProvider
{
    public sealed override ImmutableArray<string> FixableDiagnosticIds => ImmutableArray.Create(MyAnalyzer.DiagnosticId);

    public sealed override FixAllProvider GetFixAllProvider()
    {
        return WellKnownFixAllProviders.BatchFixer;
    }

    public sealed override async Task RegisterCodeFixesAsync(CodeFixContext context)
    {
        var root = await context.Document.GetSyntaxRootAsync(context.CancellationToken).ConfigureAwait(false);
        var diagnostic = context.Diagnostics.First();
        var diagnosticSpan = diagnostic.Location.SourceSpan;
        var typeDeclaration = root.FindToken(diagnosticSpan.Start).Parent.AncestorsAndSelf().OfType<TypeDeclarationSyntax>().First();
        context.RegisterCodeFix(
            CodeAction.Create(
                title: CodeFixResources.CodeFixTitle,
                createChangedDocument: c => RemoveUnderscoreFromTypeNameAsync(context.Document, typeDeclaration, c),
                equivalenceKey: nameof(CodeFixResources.CodeFixTitle)),
            diagnostic);
    }

    private async Task<Document> RemoveUnderscoreFromTypeNameAsync(Document document, TypeDeclarationSyntax typeDeclaration, CancellationToken cancellationToken)
    {
        var newTypeName = typeDeclaration.Identifier.Text.TrimStart('_');
        var newIdentifier = SyntaxFactory.Identifier(newTypeName);
        var newTypeDeclaration = typeDeclaration.WithIdentifier(newIdentifier);
        var root = await document.GetSyntaxRootAsync(cancellationToken).ConfigureAwait(false);
        var newRoot = root.ReplaceNode(typeDeclaration, newTypeDeclaration);
        return document.WithSyntaxRoot(newRoot);
    }
}

7.2 注册代码修复操作

在RegisterCodeFixesAsync方法中，首先获取语法根节点和诊断信息。然后找到诊断所在的类型声明节点。通过context.RegisterCodeFix方法注册代码修复操作，这里的代码修复操作是创建一个CodeAction，CodeAction包含修复标题和实际的修复逻辑。

7.3 实现代码修复逻辑

在RemoveUnderscoreFromTypeNameAsync方法中，实现了具体的代码修复逻辑。它将类型名开头的下划线去掉，并更新语法树，从而生成一个新的文档，完成代码修复。

八、测试 Roslyn Analyzer

8.1 使用单元测试框架

可以使用 MSTest、NUnit 等单元测试框架来测试 Roslyn Analyzer。首先，需要创建一个测试项目，并添加对分析器项目的引用。例如，使用 MSTest：

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Diagnostics;
using Microsoft.CodeAnalysis.Testing;
using Microsoft.CodeAnalysis.Testing.Verifiers;
using NUnit.Framework;

[TestFixture]
public class MyAnalyzerTests : DiagnosticVerifier
{
    protected override DiagnosticAnalyzer GetCSharpDiagnosticAnalyzer()
    {
        return new MyAnalyzer();
    }

    [Test]
    public async Task TestUnderscoreTypeName()
    {
        var test = @"
class _MyClass
{
}";
        var expected = new DiagnosticResult
        {
            Id = MyAnalyzer.DiagnosticId,
            Message = string.Format(MyAnalyzer.MessageFormat.ToString(), "_MyClass"),
            Severity = DiagnosticSeverity.Warning,
            Locations = new[] { new DiagnosticResultLocation("Test0.cs", 2, 7) }
        };
        await VerifyCSharpDiagnostic(test, expected);
    }
}

8.2 验证诊断结果

在测试方法中，定义测试代码和预期的诊断结果。通过VerifyCSharpDiagnostic方法（在DiagnosticVerifier类中定义）来验证分析器是否正确报告诊断信息。如果分析器报告的诊断信息与预期一致，则测试通过。

九、发布 Roslyn Analyzer

9.1 创建 NuGet 包

要发布 Roslyn Analyzer，通常需要将其打包成 NuGet 包。在 Visual Studio 中，可以通过右键点击分析器项目，选择“打包”来生成 NuGet 包。NuGet 包包含分析器的程序集以及相关的元数据，其他开发者可以通过 NuGet 包管理器轻松安装和使用你的分析器。

9.2 发布到 NuGet 服务器

生成 NuGet 包后，可以将其发布到 NuGet 官方服务器或自己的私有 NuGet 服务器。发布到 NuGet 官方服务器需要先在 NuGet 网站上注册账号，并获取 API 密钥。然后使用nuget push命令将包推送到 NuGet 服务器：

nuget push MyAnalyzer.1.0.0.nupkg YourApiKey -Source https://api.nuget.org/v3/index.json

这样，其他开发者就可以在 Visual Studio 中通过 NuGet 包管理器搜索并安装你的 Roslyn Analyzer 了。

通过以上步骤，你可以逐步开发出功能强大的 Roslyn Analyzer，帮助提升 C# 代码的质量和规范性。无论是团队内部使用，还是发布到公共 NuGet 服务器供广大开发者使用，Roslyn Analyzer 都能在代码开发过程中发挥重要作用。在实际开发中，你可以根据具体需求，不断扩展分析器的功能，处理更复杂的语法和语义场景，为代码质量保驾护航。同时，随着 Roslyn 平台的不断发展，新的功能和 API 也会不断涌现，开发者需要持续关注和学习，以充分利用 Roslyn 带来的强大能力。