Roslyn这名字在C#开发者圈子里已经不算陌生,但很多人对它的认识还停留在编译器层面。其实Roslyn提供的是完整的编译器平台,把词法分析、语法分析、语义绑定、代码生成这些原本封闭在csc内部的能力全部开放成了托管API。对于需要批量分析代码、做架构检查、自动重构或代码生成的场景,用Roslyn来操作源文件比正则表达式可靠得多。下面从解析一个代码字符串开始,逐步覆盖语法树遍历、节点替换和完整代码生成。

从代码文本到语法树:Roslyn的解析入口
在传统的编译器工具链里,读取并分析一段C#代码通常需要借助正则表达式、第三方解析器或者直接调用csc进程。Roslyn则提供了完全托管的语法解析能力,核心类型是SyntaxTree和CSharpSyntaxTree。只要安装Microsoft.CodeAnalysis.CSharp这个NuGet包,就可以在代码中调用CSharpSyntaxTree.ParseText静态方法,把一段字符串形式的源代码转换成语法树对象。
语法树本身是不可变的,这意味着所有查询操作都不会改变原始树,任何修改都会返回新的节点或新的树。解析完成后通常调用GetRoot方法获取根节点,根节点的类型为CompilationUnitSyntax,代表一个C#编译单元,下面挂载using指令、命名空间、类型声明等内容。语法树还完整保留注释、空白和预处理指令,它们被存储在Trivia结构中,因此后续格式化或重新输出时不会丢失原始排版信息。
示例中的ParseText方法有多个重载,可以传入CSharpParseOptions指定语言版本、预处理器符号等。例如需要解析包含C# 9的顶级语句时,应设置LanguageVersion.CSharp9,否则某些新语法节点可能无法正确识别。语法树一旦生成,就可以通过ToString恢复源代码文本,或者基于它构建语义分析所需的编译对象。
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using System;
class Program
{
static void Main()
{
string code = @"
class Sample
{
public void Run(int value)
{
System.Console.WriteLine(value);
}
}";
SyntaxTree tree = CSharpSyntaxTree.ParseText(code);
var root = tree.GetRoot();
Console.WriteLine(root.ToString());
}
}
遍历语法树获取代码结构
拿到根节点之后,最常用的操作就是遍历语法树,找出感兴趣的节点。Roslyn用SyntaxNode表示语法树中的每一个元素,包括编译单元、命名空间、类、方法、属性、参数等。每个节点都有DescendantNodes方法,可以递归返回所有后代节点。结合LINQ的OfType<T>方法,就能快速筛选出特定类型的语法节点,例如MethodDeclarationSyntax对应方法声明,ClassDeclarationSyntax对应类声明。
这种查询方式非常直观,适合做代码审计、生成API文档或者统计代码指标。比如要统计一个文件里定义了多少个公共方法,只需要过滤MethodDeclarationSyntax并检查Modifiers集合中是否包含public关键字即可。语法节点还带有Span和FullSpan属性,前者表示节点核心部分在源码中的位置区间,后者则包含前后附加的Trivia,比如注释和空白。这样一来,定位问题代码、高亮显示或者按位置插入文本都会方便很多。
除了LINQ查询,Roslyn还提供了CSharpSyntaxWalker类,可以通过继承并重写VisitMethodDeclaration等方法,以访问者模式深度遍历整棵树。对于复杂项目中需要分层处理的场景,自定义Walker比一次性LINQ查询更容易控制遍历顺序和上下文。下面的示例演示如何从一个代码字符串中提取所有方法的名称和返回类型。
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using System;
using System.Linq;
class Parser
{
static void Main()
{
string code = @"
namespace Demo
{
public class Calculator
{
public int Add(int a, int b) => a + b;
private void Print(string text)
{
System.Console.WriteLine(text);
}
}
}";
SyntaxTree tree = CSharpSyntaxTree.ParseText(code);
var root = (CompilationUnitSyntax)tree.GetRoot();
var methods = root.DescendantNodes()
.OfType<MethodDeclarationSyntax>();
foreach (var method in methods)
{
string name = method.Identifier.Text;
string returnType = method.ReturnType.ToString();
Console.WriteLine($"方法名: {name}, 返回类型: {returnType}");
}
}
}
如果还需要知道某个方法调用了哪些其他方法、某个类型实现了哪些接口,仅仅依赖语法树还不够,这时需要构建Compilation对象并获取语义模型。语义模型可以解析符号信息,比如ISymbol、IMethodSymbol,它们能告诉你一个标识符到底指向哪个程序集里的哪个成员。语义分析是重命名重构、查找所有引用等高级功能的基础,但成本也更高,通常只对需要精确语义的操作才启用。
用SyntaxFactory生成和修改C#代码
修改代码时,不能直接改变已有节点的属性,因为语法节点是不可变的。正确做法是先查找目标节点,然后构造一个新节点或新成员,再调用ReplaceNode或AddMembers得到更新后的根节点。Roslyn提供了一个专门的工厂类SyntaxFactory,用来创建所有C#语法元素,包括类型、方法、参数、语句、表达式等。通过链式调用,可以像搭积木一样拼装出一棵完整的语法树。
生成代码时要特别注意节点的结构层级。例如创建一个方法,需要先创建MethodDeclarationSyntax,然后依次设置返回类型、方法名、修饰符、参数列表和主体。参数列表里的每个参数又需要单独创建ParameterSyntax并指定类型和名称。如果某一层结构缺失,格式化或输出时可能出现不完整甚至非法的代码。为了避免手工拼接出错,可以先在IDE里写一小段目标代码,用解析工具查看它的语法树结构,再照着结构编写生成逻辑。
下面的示例从零开始生成一个带命名空间和类的完整编译单元。生成完成后通过AdhocWorkspace和Formatter.Format对代码进行标准化排版,避免节点之间的空白和缩进混乱。
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using Microsoft.CodeAnalysis.Formatting;
using System;
class Generator
{
static void Main()
{
var compilationUnit = SyntaxFactory.CompilationUnit()
.AddUsings(SyntaxFactory.UsingDirective(SyntaxFactory.ParseName("System")));
var @namespace = SyntaxFactory.NamespaceDeclaration(SyntaxFactory.ParseName("Demo"))
.AddMembers(
SyntaxFactory.ClassDeclaration("GeneratedService")
.AddModifiers(SyntaxFactory.Token(SyntaxKind.PublicKeyword))
.AddMembers(
SyntaxFactory.MethodDeclaration(
SyntaxFactory.PredefinedType(SyntaxFactory.Token(SyntaxKind.VoidKeyword)),
"Greet")
.AddModifiers(SyntaxFactory.Token(SyntaxKind.PublicKeyword))
.WithBody(SyntaxFactory.Block(
SyntaxFactory.ParseStatement("Console.WriteLine(\"Hello from Roslyn\");")))
)
);
compilationUnit = compilationUnit.AddMembers(@namespace);
using var workspace = new AdhocWorkspace();
var formattedNode = Formatter.Format(compilationUnit, workspace);
Console.WriteLine(formattedNode.ToFullString());
}
}
如果要基于现有代码做局部修改,也可以使用ParseStatement快速创建语句,避免逐层构造表达式。例如下面的代码读取一个已有的类定义,给它追加一个折扣计算方法。整个过程中原始的注释、换行和空格都保存在未修改节点的Trivia里,替换操作不会影响其他部分。
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using System;
using System.Linq;
class Modifier
{
static void Main()
{
string code = "public class Order { public decimal Total { get; set; } }";
SyntaxTree tree = CSharpSyntaxTree.ParseText(code);
var root = (CompilationUnitSyntax)tree.GetRoot();
var classDeclaration = root.DescendantNodes()
.OfType<ClassDeclarationSyntax>().First();
var method = SyntaxFactory.MethodDeclaration(
SyntaxFactory.PredefinedType(SyntaxFactory.Token(SyntaxKind.DecimalKeyword)),
"ApplyDiscount")
.AddModifiers(SyntaxFactory.Token(SyntaxKind.PublicKeyword))
.AddParameterListParameters(
SyntaxFactory.Parameter(SyntaxFactory.Identifier("rate"))
.WithType(SyntaxFactory.PredefinedType(SyntaxFactory.Token(SyntaxKind.DecimalKeyword))))
.WithBody(SyntaxFactory.Block(
SyntaxFactory.ParseStatement("return Total * (1 - rate);")));
var newClass = classDeclaration.AddMembers(method);
var newRoot = root.ReplaceNode(classDeclaration, newClass);
Console.WriteLine(newRoot.NormalizeWhitespace().ToFullString());
}
}
处理真实项目文件与常见问题
前面演示的都是直接解析内存中的字符串,实际项目中往往需要批量处理文件夹里的.cs文件。最简单的方式是用Directory.EnumerateFiles遍历路径,再对每个文件调用File.ReadAllText和CSharpSyntaxTree.ParseText。但如果代码依赖其他项目或NuGet包,单纯解析语法树无法获得完整的类型信息。此时应该使用MSBuildWorkspace打开解决方案或项目文件,由Roslyn自动加载项目引用和编译选项,然后通过Compilation获取每个语法树的语义模型。
还有一个常见的误区是认为语法树只能解析完全合法的代码。实际上ParseText可以解析包含语法错误的代码,只是错误节点会被标记为SkippedTokensTrivia或者生成CompilationUnitSyntax中带有诊断信息的节点。这个特性对编辑器场景非常有用,例如在用户输入过程中实时分析不完整的代码。但在代码生成和自动重构时,最好先检查GetDiagnostics结果,确保输入的源文件没有严重语法错误,否则后续替换和生成可能得到不可预期的结果。
Trivia的处理也需要特别留意。很多开发者在修改节点后直接调用NormalizeWhitespace统一格式化,这虽然能获得整齐的缩进,却可能丢失原始注释或特殊空行。Roslyn把注释、空格和换行都归为Trivia,存储在与节点关联的LeadingTrivia和TrailingTrivia中。如果必须保留原始注释,应当在构造新节点时显式把旧节点的Trivia迁移过去,或者使用WithLeadingTrivia和WithTrailingTrivia恢复。对于只追求可编译输出而不关心注释的场景,才建议直接用格式化器重排。
性能方面,解析大量文件时最好缓存已解析的SyntaxTree和Compilation对象,避免重复读取磁盘和重新解析。Roslyn的语法树和编译对象都是不可变的,可以安全地在多个任务之间共享。如果同一个文件被多次修改和查询,也可以缓存SyntaxTree并基于旧树创建新树,减少全量解析开销。总体来看,Roslyn API把C#源代码从静态文本变成了可编程的数据结构,无论是做静态分析、自动化重构还是代码生成,都提供了远比字符串操作更加稳定和精确的基础设施。
C# RoslynRoslyn API代码生成修改时间:2026-11-01 06:27:53