Roslyn 源生成器学习指南

Appearance

C# Source Generator 学习指南 ​

📋 文档信息 ​

文档集: C# Source Generator 学习指南
文档数量: 7 个
总阅读时间: 约 180 分钟
最后更新: 2026-02-05

新的学习路径已上线

我们推出了全新的 交互式学习路径，提供更好的学习体验：

  • 8 步渐进式学习
  • 实时进度追踪
  • 交互式检查点
  • 清晰的时间预估

推荐使用新的学习路径！ 本文档保留作为参考资料。

🎯 学习指南概览 ​

本学习指南提供了 C# 源生成器的全面学习资源，从基础原理到高级实践，帮助你系统地掌握源生成器开发技术。

学习指南涵盖:

  • 🏗️ Roslyn 编译器平台和源生成器原理
  • 📚 完整的 Roslyn API 参考和使用指南
  • 🎨 常见的代码生成模式和技巧
  • 💡 性能优化和最佳实践
  • 🔧 故障排除和调试技巧

适合人群:

  • 想要学习源生成器开发的 C# 开发者
  • 需要深入了解 Roslyn API 的开发者
  • 希望优化现有生成器性能的开发者
  • 寻找实用模式和最佳实践的开发者

📚 文档列表 ​

基础文档 ​

文档难度阅读时间说明
源生成器原理🟢 简单20 分钟Roslyn 编译器平台、语法树、语义模型和编译管道
Roslyn API 介绍🟢 简单30 分钟核心命名空间、生成器接口和基本 API 使用

中级文档 ​

文档难度阅读时间说明
语法树 API🟡 中级35 分钟语法树操作、节点遍历和常用语法节点详解
语义模型 API🟡 中级35 分钟符号系统、类型信息和语义分析
常见模式🟡 中级30 分钟代码生成、分析和转换的常见模式

高级文档 ​

文档难度阅读时间说明
最佳实践🔴 高级30 分钟性能优化、错误处理和项目配置
故障排除🔴 高级20 分钟常见问题、调试技巧和解决方案

🗺️ 学习路径 ​

初学者路径（从零开始） ​

如果你是第一次接触源生成器，建议按以下顺序学习：

  1. 第一步：理解原理 - 源生成器原理

    • 了解 Roslyn 编译器平台
    • 理解语法树和语义模型
    • 掌握编译管道流程

  2. 第二步：学习基础 API - Roslyn API 介绍

    • 熟悉核心命名空间
    • 了解生成器接口
    • 学习基本 API 使用

  3. 第三步：掌握语法树 - 语法树 API

    • 学习语法树操作
    • 掌握节点遍历方法
    • 了解常用语法节点

  4. 第四步：学习语义分析 - 语义模型 API

    • 理解符号系统
    • 学习类型信息获取
    • 掌握语义分析技巧

  5. 第五步：实践常见模式 - 常见模式

    • 学习代码生成模式
    • 掌握分析模式
    • 了解转换模式

进阶路径（已有基础） ​

如果你已经有一定的源生成器开发经验，可以直接学习：

  1. 优化性能 - 最佳实践

    • 性能优化技巧
    • 错误处理策略
    • 项目配置建议

  2. 解决问题 - 故障排除

    • 常见问题诊断
    • 调试技巧
    • 解决方案汇总

专题学习路径 ​

根据你的具体需求，可以选择以下专题：

专题 1：性能优化

  1. 源生成器原理 - 了解编译管道和缓存机制
  2. 最佳实践 - 学习性能优化技巧
  3. 故障排除 - 诊断性能问题

专题 2：API 深入

  1. Roslyn API 介绍 - API 概览
  2. 语法树 API - 语法操作详解
  3. 语义模型 API - 语义分析详解

专题 3：实战技巧

  1. 常见模式 - 学习实用模式
  2. 最佳实践 - 掌握最佳实践
  3. 故障排除 - 解决实际问题

📊 快速参考 ​

核心概念速查 ​

概念说明相关文档
Roslyn.NET 编译器平台源生成器原理
语法树代码的结构化表示源生成器原理
语义模型代码的语义信息源生成器原理
编译管道编译流程和生成器执行时机源生成器原理
ISourceGenerator传统生成器接口Roslyn API 介绍
IIncrementalGenerator增量生成器接口（推荐）Roslyn API 介绍

常用 API 速查 ​

API用途相关文档
SyntaxTree语法树操作语法树 API
SyntaxNode语法节点语法树 API
SemanticModel语义分析语义模型 API
ISymbol符号信息语义模型 API
Compilation编译信息Roslyn API 介绍
SyntaxFactory代码生成Roslyn API 介绍

最佳实践速查 ​

实践说明相关文档
使用增量生成器性能提升 10-100 倍最佳实践
ForAttributeWithMetadataName.NET 7+ 高性能特性查找最佳实践
避免传递大对象提高缓存效率最佳实践
使用静态方法避免闭包捕获最佳实践
最小化语义模型访问先用语法过滤最佳实践

🎓 学习建议 ​

学习方法 ​

  1. 循序渐进: 按照推荐的学习路径逐步学习，不要跳过基础内容
  2. 动手实践: 每学完一个章节，尝试编写相应的代码示例
  3. 参考示例: 查看 示例集合 中的完整示例
  4. 解决问题: 遇到问题时查阅 故障排除 文档
  5. 持续优化: 学习 最佳实践 并应用到实际项目中

学习资源 ​

常见学习误区 ​

  1. ❌ 跳过原理直接写代码: 不理解原理会导致性能问题和错误
  2. ❌ 过度使用语义模型: 应该先用语法过滤，再用语义分析
  3. ❌ 使用传统生成器: 应该使用增量生成器获得更好的性能
  4. ❌ 忽视错误处理: 应该使用诊断而不是异常
  5. ❌ 不测试生成器: 应该编写单元测试验证生成器行为

🔗 相关资源 ​

内部资源 ​

外部资源 ​

📝 文档维护 ​

本学习指南会持续更新，以反映最新的 Roslyn API 和最佳实践。

最近更新:

  • 2026-02-05: 文档重构，拆分为多个主题文档
  • 添加了 .NET 7+ 的 ForAttributeWithMetadataName API
  • 更新了性能优化建议
  • 增加了更多实用示例

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

📚 下一步 ​

选择适合你的学习路径开始学习：

基于 MIT 许可发布

Copyright © 2025-present