代码生成 API 完整参考

📋 文档信息

文档集: 代码生成 API
文档数量: 5 个
总阅读时间: 约 120 分钟
难度: 🟡 中级到 🔴 高级
前置知识:

C# 基础语法
Roslyn 基本概念
语法树基础知识

适合人群:

需要生成 C# 代码的开发者
源生成器开发者
代码分析工具开发者
自动化代码生成工具开发者

🎯 概览

本文档集详细介绍 Roslyn 代码生成 API，包括 SyntaxFactory 的使用、代码构建模式、格式化技巧以及复杂结构的生成方法。

核心内容:

SyntaxFactory 基础: 学习如何使用 SyntaxFactory 创建基本语法元素
SyntaxFactory 高级: 掌握复杂结构的生成技术
代码构建模式: 了解常用的代码构建模式和最佳实践
格式化和美化: 学习如何格式化生成的代码
最佳实践: 掌握代码生成的最佳实践和常见错误

典型应用场景:

源生成器开发
DTO 类自动生成
Builder 模式代码生成
代码重构工具
代码模板生成
测试代码生成

📚 文档列表

基础文档

文档	难度	阅读时间	说明
SyntaxFactory 基础	🟡 中级	25 分钟	学习 SyntaxFactory 的基本使用方法，包括创建类型、表达式和语句
格式化和美化	🟢 简单	15 分钟	学习如何格式化和美化生成的代码

中级文档

文档	难度	阅读时间	说明
代码构建模式	🟡 中级	20 分钟	学习常用的代码构建模式，如构建器模式、流式 API 等
最佳实践	🟡 中级	25 分钟	掌握代码生成的最佳实践、常见错误和性能优化技巧

高级文档

文档	难度	阅读时间	说明
SyntaxFactory 高级	🔴 高级	35 分钟	学习复杂结构的生成技术，包括泛型类、特性、接口实现等

🗺️ 学习路径

初学者路径

如果你是第一次接触 Roslyn 代码生成 API，建议按以下顺序学习：

第一步: 阅读 SyntaxFactory 基础
- 了解 SyntaxFactory 的基本概念
- 学习创建基本类型、表达式和语句
- 掌握常用的 API 方法
第二步: 阅读格式化和美化
- 学习如何格式化生成的代码
- 了解 NormalizeWhitespace 的使用
- 掌握代码美化技巧
第三步: 阅读代码构建模式
- 学习构建器模式
- 了解流式 API 设计
- 掌握代码复用技巧
第四步: 阅读最佳实践
- 了解推荐做法
- 避免常见错误
- 学习性能优化技巧

进阶路径

如果你已经有一定的 Roslyn 基础，想要深入学习高级技术：

复习基础: 快速浏览 SyntaxFactory 基础
深入学习: 重点学习 SyntaxFactory 高级
- 掌握泛型类生成
- 学习特性和接口实现
- 了解复杂结构生成技术
实战应用: 结合代码构建模式和最佳实践
- 设计自己的代码生成架构
- 优化代码生成性能
- 处理复杂的生成场景

实战路径

如果你想快速上手实际项目：

快速入门: 浏览 SyntaxFactory 基础的常用方法部分
选择模式: 根据需求选择代码构建模式中的合适模式
参考实践: 查阅最佳实践中的真实使用场景
深入优化: 根据需要学习 SyntaxFactory 高级的特定技术

📊 API 速查表

常用类型创建

API	说明	返回类型	示例
`PredefinedType(Token(SyntaxKind.IntKeyword))`	创建预定义类型	`PredefinedTypeSyntax`	`int`
`IdentifierName("MyClass")`	创建自定义类型	`IdentifierNameSyntax`	`MyClass`
`GenericName(...)`	创建泛型类型	`GenericNameSyntax`	`List<int>`
`ArrayType(...)`	创建数组类型	`ArrayTypeSyntax`	`int[]`
`NullableType(...)`	创建可空类型	`NullableTypeSyntax`	`int?`

常用表达式创建

API	说明	返回类型	示例
`LiteralExpression(...)`	创建字面量	`LiteralExpressionSyntax`	`42`, `"Hello"`
`BinaryExpression(...)`	创建二元表达式	`BinaryExpressionSyntax`	`a + b`
`InvocationExpression(...)`	创建方法调用	`InvocationExpressionSyntax`	`Method()`
`ObjectCreationExpression(...)`	创建对象创建	`ObjectCreationExpressionSyntax`	`new MyClass()`
`MemberAccessExpression(...)`	创建成员访问	`MemberAccessExpressionSyntax`	`obj.Property`

常用语句创建

API	说明	返回类型	示例
`LocalDeclarationStatement(...)`	创建变量声明	`LocalDeclarationStatementSyntax`	`int x = 42;`
`ExpressionStatement(...)`	创建表达式语句	`ExpressionStatementSyntax`	`Method();`
`ReturnStatement(...)`	创建返回语句	`ReturnStatementSyntax`	`return value;`
`IfStatement(...)`	创建 if 语句	`IfStatementSyntax`	`if (condition) { }`
`ForStatement(...)`	创建 for 循环	`ForStatementSyntax`	`for (int i = 0; i < 10; i++) { }`

常用成员创建

API	说明	返回类型	示例
`PropertyDeclaration(...)`	创建属性	`PropertyDeclarationSyntax`	`public int Value { get; set; }`
`MethodDeclaration(...)`	创建方法	`MethodDeclarationSyntax`	`public void Method() { }`
`FieldDeclaration(...)`	创建字段	`FieldDeclarationSyntax`	`private int _field;`
`ConstructorDeclaration(...)`	创建构造函数	`ConstructorDeclarationSyntax`	`public MyClass() { }`

常用修饰符

API	说明	示例
`Token(SyntaxKind.PublicKeyword)`	public 修饰符	`public`
`Token(SyntaxKind.PrivateKeyword)`	private 修饰符	`private`
`Token(SyntaxKind.StaticKeyword)`	static 修饰符	`static`
`Token(SyntaxKind.ReadOnlyKeyword)`	readonly 修饰符	`readonly`
`Token(SyntaxKind.AbstractKeyword)`	abstract 修饰符	`abstract`
`Token(SyntaxKind.VirtualKeyword)`	virtual 修饰符	`virtual`
`Token(SyntaxKind.OverrideKeyword)`	override 修饰符	`override`

💡 快速开始

最简单的示例

csharp

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using static Microsoft.CodeAnalysis.CSharp.SyntaxFactory;

// 创建一个简单的属性
var property = PropertyDeclaration(
    PredefinedType(Token(SyntaxKind.IntKeyword)),
    Identifier("Value"))
    .AddModifiers(Token(SyntaxKind.PublicKeyword))
    .AddAccessorListAccessors(
        AccessorDeclaration(SyntaxKind.GetAccessorDeclaration)
            .WithSemicolonToken(Token(SyntaxKind.SemicolonToken)),
        AccessorDeclaration(SyntaxKind.SetAccessorDeclaration)
            .WithSemicolonToken(Token(SyntaxKind.SemicolonToken)));

// 格式化代码
var formattedProperty = property.NormalizeWhitespace();

// 输出代码
Console.WriteLine(formattedProperty.ToFullString());
// 输出: public int Value { get; set; }

常见使用场景

生成 DTO 类

csharp

// 详见: SyntaxFactory 高级 -> 真实使用场景 -> DTO 类生成器

生成 Builder 类

csharp

// 详见: SyntaxFactory 高级 -> 真实使用场景 -> Builder 模式生成器

生成测试代码

csharp

// 详见: 最佳实践 -> 真实使用场景

🔍 常见问题解答

Q1: SyntaxFactory 和字符串拼接哪个更好？

答: 取决于场景：

简单代码: 字符串拼接更简单直观
复杂代码: SyntaxFactory 更安全、更易维护
需要语法验证: 必须使用 SyntaxFactory

详见: SyntaxFactory 高级 -> 字符串插值 vs SyntaxFactory

Q2: 如何生成带命名空间的完整代码文件？

答: 使用 CompilationUnit 和 NamespaceDeclaration：

csharp

var compilationUnit = CompilationUnit()
    .AddUsings(UsingDirective(IdentifierName("System")))
    .AddMembers(
        NamespaceDeclaration(IdentifierName("MyNamespace"))
            .AddMembers(classDeclaration));

详见: SyntaxFactory 高级 -> 常见问题解答 -> Q1

Q3: 生成的代码格式不正确怎么办？

答: 使用 NormalizeWhitespace() 方法：

csharp

var formattedCode = syntaxNode.NormalizeWhitespace();

详见: 格式化和美化 -> NormalizeWhitespace

Q4: 如何提高代码生成性能？

答: 主要优化方向：

重用 SyntaxToken
使用 StringBuilder 模式
避免不必要的格式化
批量生成代码

详见: 最佳实践 -> 性能优化技巧

Q5: 如何调试生成的代码？

答: 推荐使用以下工具：

Syntax Visualizer（Visual Studio 扩展）
ToFullString() 方法输出代码
单元测试验证生成结果

详见: 最佳实践 -> 调试技巧

📖 相关文档

基础知识

语法树基础 - 了解语法树的基本概念
语法树遍历 - 学习如何遍历语法树
语法树修改 - 学习如何修改语法树

API 参考

语义模型 API - 符号和类型系统
编译 API - 编译和元数据引用
诊断 API - 错误和警告报告

实战示例

Hello World 生成器 - 最简单的源生成器
Builder 生成器 - Builder 模式生成器
ToString 生成器 - ToString 方法生成器

🎯 学习目标

学习完本文档集后，你应该能够：

✅ 掌握 SyntaxFactory 基础
- 创建各种类型、表达式和语句
- 使用常用的 API 方法
- 理解语法节点的结构
✅ 掌握代码格式化
- 使用 NormalizeWhitespace 格式化代码
- 控制代码缩进和换行
- 生成美观的代码
✅ 掌握代码构建模式
- 使用构建器模式组织代码
- 设计流式 API
- 实现代码复用
✅ 掌握高级生成技术
- 生成泛型类和方法
- 生成特性和接口实现
- 处理复杂的代码结构
✅ 掌握最佳实践
- 避免常见错误
- 优化代码生成性能
- 编写可维护的代码生成器

💡 实用技巧

技巧 1: 使用 `using static` 简化代码

csharp

using static Microsoft.CodeAnalysis.CSharp.SyntaxFactory;

// 之前
var property = SyntaxFactory.PropertyDeclaration(...);

// 之后
var property = PropertyDeclaration(...);

技巧 2: 使用 `Add*` 方法链式调用

csharp

var classDecl = ClassDeclaration("MyClass")
    .AddModifiers(Token(SyntaxKind.PublicKeyword))
    .AddMembers(property1, property2, method1);

技巧 3: 使用辅助方法封装常用操作

csharp

public static PropertyDeclarationSyntax CreateAutoProperty(
    string typeName, string propertyName)
{
    return PropertyDeclaration(
        IdentifierName(typeName),
        Identifier(propertyName))
        .AddModifiers(Token(SyntaxKind.PublicKeyword))
        .AddAccessorListAccessors(
            AccessorDeclaration(SyntaxKind.GetAccessorDeclaration)
                .WithSemicolonToken(Token(SyntaxKind.SemicolonToken)),
            AccessorDeclaration(SyntaxKind.SetAccessorDeclaration)
                .WithSemicolonToken(Token(SyntaxKind.SemicolonToken)));
}

技巧 4: 使用 Syntax Visualizer 查看语法结构

在 Visual Studio 中安装 ".NET Compiler Platform SDK"，然后使用 "View -> Other Windows -> Syntax Visualizer" 查看代码的语法树结构。

🚀 下一步

完成本文档集的学习后，建议继续学习：

语义模型 API: 学习如何使用语义信息
- 语义模型 API 完整参考
- 符号系统详解
增量生成器: 学习如何优化生成器性能
- 增量生成器 API
- 增量生成器示例
实战项目: 动手实践

📝 文档维护

最后更新: 2026-02-05
文档版本: 1.0
维护者: Roslyn 文档团队

如果你发现文档中的错误或有改进建议，欢迎提交反馈。

返回: API 参考首页

代码生成 API 完整参考 ​

📋 文档信息 ​

🎯 概览 ​

📚 文档列表 ​

基础文档 ​

中级文档 ​

高级文档 ​

🗺️ 学习路径 ​

初学者路径 ​

进阶路径 ​

实战路径 ​

📊 API 速查表 ​

常用类型创建 ​

常用表达式创建 ​

常用语句创建 ​

常用成员创建 ​

常用修饰符 ​

💡 快速开始 ​

最简单的示例 ​

常见使用场景 ​

🔍 常见问题解答 ​

Q1: SyntaxFactory 和字符串拼接哪个更好？ ​

Q2: 如何生成带命名空间的完整代码文件？ ​

Q3: 生成的代码格式不正确怎么办？ ​

Q4: 如何提高代码生成性能？ ​

Q5: 如何调试生成的代码？ ​

📖 相关文档 ​

基础知识 ​

API 参考 ​

实战示例 ​

🎯 学习目标 ​

💡 实用技巧 ​

技巧 1: 使用 using static 简化代码 ​

技巧 2: 使用 Add* 方法链式调用 ​

技巧 3: 使用辅助方法封装常用操作 ​

技巧 4: 使用 Syntax Visualizer 查看语法结构 ​

🚀 下一步 ​

📝 文档维护 ​

代码生成 API 完整参考

📋 文档信息

🎯 概览

📚 文档列表

基础文档

中级文档

高级文档

🗺️ 学习路径

初学者路径

进阶路径

实战路径

📊 API 速查表

常用类型创建

常用表达式创建

常用语句创建

常用成员创建

常用修饰符

💡 快速开始

最简单的示例

常见使用场景

🔍 常见问题解答

Q1: SyntaxFactory 和字符串拼接哪个更好？

Q2: 如何生成带命名空间的完整代码文件？

Q3: 生成的代码格式不正确怎么办？

Q4: 如何提高代码生成性能？

Q5: 如何调试生成的代码？

📖 相关文档

基础知识

API 参考

实战示例

🎯 学习目标

💡 实用技巧

技巧 1: 使用 `using static` 简化代码

技巧 2: 使用 `Add*` 方法链式调用

技巧 3: 使用辅助方法封装常用操作

技巧 4: 使用 Syntax Visualizer 查看语法结构

🚀 下一步

📝 文档维护