蔡振原1. 项目概述：当.NET遇上Roslyn代码生成
第一次看到基于Roslyn的.NET代码生成器时，就像发现了一把瑞士军刀——原本需要手工编写的重复性代码，现在通过几行模板就能自动生成。这个开源项目本质上利用了Roslyn编译器即服务（Compiler as a Service）的特性，将代码生成过程从"编译后"提前到"编译时"完成。
在实际开发中，我经常遇到需要为DTO类生成验证逻辑、为API接口生成客户端代理等场景。传统方式要么依赖T4模板（体验差且难调试），要么使用反射在运行时生成（性能损耗大）。而基于Roslyn的源码生成器直接在编译阶段介入，既能获得静态检查的优势，又不会增加运行时开销。比如最近一个WebAPI项目，通过代码生成器自动为所有模型类生成FluentValidation规则，开发效率提升了40%以上。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心原理拆解
2.1 Roslyn编译管道扩展机制
Roslyn的独特之处在于它将整个编译过程分解为可插拔的阶段。当我们在项目中安装Microsoft.CodeAnalysis.CSharp包（3.8.0+版本）后，就可以通过实现ISourceGenerator接口挂载到编译流程中。具体工作流程如下：
- 初始化阶段：编译器加载所有被[Generator]标记的生成器
- 语法分析阶段：生成器接收Compilation对象（包含所有语法树）
- 生成阶段：通过ExecutionContext.AddSource方法输出新代码
- 编译阶段：生成的代码与原始代码一起参与编译
实测发现，生成器在VS2022中的响应速度极快——修改完模板后保存文件，新代码能在300ms内出现在IntelliSense中。
2.2 源码生成器典型结构
一个完整的生成器项目通常包含三个关键部分：
csharp复制// 1. 生成器声明
[Generator]
public class DtoGenerator : ISourceGenerator {
// 2. 初始化
public void Initialize(GeneratorInitializationContext context) {
context.RegisterForSyntaxNotifications(() => new SyntaxReceiver());
}
// 3. 执行生成
public void Execute(GeneratorExecutionContext context) {
var syntaxReceiver = (SyntaxReceiver)context.SyntaxReceiver;
// 生成代码逻辑...
context.AddSource("GeneratedDto.cs", SourceText.From(code, Encoding.UTF8));
}
}
// 语法树接收器（可选）
class SyntaxReceiver : ISyntaxReceiver {
public List<ClassDeclarationSyntax> CandidateClasses { get; } = new();
public void OnVisitSyntaxNode(SyntaxNode syntaxNode) {
if (syntaxNode is ClassDeclarationSyntax cds && cds.AttributeLists.Count > 0)
CandidateClasses.Add(cds);
}
}
重要提示：生成器必须打包为.NET Standard 2.0库，且需要显式引用Microsoft.CodeAnalysis.CSharp和Microsoft.CodeAnalysis.Analyzers
3. 实战：构建DTO验证生成器
3.1 需求场景分析
假设我们有一个电商系统的Product类：
csharp复制public class Product {
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
public int Stock { get; set; }
}
希望自动生成如下验证规则：
csharp复制public class ProductValidator : AbstractValidator<Product> {
public ProductValidator() {
RuleFor(x => x.Id).GreaterThan(0);
RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
RuleFor(x => x.Price).GreaterThan(0);
RuleFor(x => x.Stock).GreaterThanOrEqualTo(0);
}
}
3.2 实现步骤详解
3.2.1 定义标记属性
首先创建用于标记需要生成验证的类：
csharp复制[AttributeUsage(AttributeTargets.Class)]
public class GenerateValidatorAttribute : Attribute {
public string Namespace { get; set; }
}
3.2.2 实现语法接收器
收集所有带[GenerateValidator]特性的类：
csharp复制class ValidatorSyntaxReceiver : ISyntaxReceiver {
public List<ClassDeclarationSyntax> Classes { get; } = new();
public void OnVisitSyntaxNode(SyntaxNode syntaxNode) {
if (syntaxNode is ClassDeclarationSyntax cds &&
cds.AttributeLists.Any(al =>
al.Attributes.Any(a => a.Name.ToString().Contains("GenerateValidator"))))
{
Classes.Add(cds);
}
}
}
3.2.3 核心生成逻辑
csharp复制public void Execute(GeneratorExecutionContext context) {
if (!(context.SyntaxReceiver is ValidatorSyntaxReceiver receiver)) return;
var compilation = context.Compilation;
foreach (var classDecl in receiver.Classes) {
var model = compilation.GetSemanticModel(classDecl.SyntaxTree);
var typeSymbol = model.GetDeclaredSymbol(classDecl);
var validatorCode = BuildValidatorCode(typeSymbol);
context.AddSource($"{typeSymbol.Name}Validator.g.cs",
SourceText.From(validatorCode, Encoding.UTF8));
}
}
private string BuildValidatorCode(INamedTypeSymbol classSymbol) {
var props = classSymbol.GetMembers()
.OfType<IPropertySymbol>()
.Where(p => !p.IsStatic);
var rules = new StringBuilder();
foreach (var prop in props) {
var rule = GenerateRuleForProperty(prop);
if (!string.IsNullOrEmpty(rule))
rules.AppendLine($" {rule}");
}
return $@"// <auto-generated/>
using FluentValidation;
namespace {GetNamespace(classSymbol)};
public partial class {classSymbol.Name}Validator : AbstractValidator<{classSymbol.Name}> {{
public {classSymbol.Name}Validator() {{
{rules}
}}
}}";
}
3.3 属性规则生成策略
针对不同属性类型生成对应验证规则：
csharp复制string GenerateRuleForProperty(IPropertySymbol prop) {
return prop.Type.SpecialType switch {
SpecialType.System_String =>
$"RuleFor(x => x.{prop.Name}).NotEmpty().MaximumLength(100);",
SpecialType.System_Int32 or SpecialType.System_Decimal =>
$"RuleFor(x => x.{prop.Name}).GreaterThan(0);",
_ => string.Empty
};
}
4. 高级应用技巧
4.1 增量生成优化
当项目规模较大时，可以使用增量生成器提高性能：
csharp复制[Generator(LanguageNames.CSharp)]
public class IncrementalGenerator : IIncrementalGenerator {
public void Initialize(IncrementalGeneratorInitializationContext context) {
var classDeclarations = context.SyntaxProvider
.CreateSyntaxProvider(
predicate: (s, _) => s is ClassDeclarationSyntax cds &&
cds.AttributeLists.Count > 0,
transform: (ctx, _) => (ClassDeclarationSyntax)ctx.Node)
.Where(cds => /* 过滤条件 */);
context.RegisterSourceOutput(classDeclarations,
(spc, source) => GenerateCode(spc, source));
}
}
4.2 多文件交互生成
有时需要生成相互引用的多个文件。这时可以使用AddSource的hintName参数控制生成顺序：
csharp复制context.AddSource("_GeneratedCodeFirst.cs", firstPart);
context.AddSource("_GeneratedCodeSecond.cs", secondPart);
4.3 调试技巧
在生成器中添加调试断点：
- 在生成器项目属性中添加：
xml复制<PropertyGroup>
<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
<CompilerGeneratedFilesOutputPath>Generated</CompilerGeneratedFilesOutputPath>
</PropertyGroup>
- 在launchSettings.json中添加：
json复制"env": {
"DEBUG_SOURCE_GENERATORS": "1"
}
5. 性能优化与问题排查
5.1 常见性能陷阱
-
过度分析语法树：只在必要时获取语义模型
csharp复制// 错误做法：为每个节点都获取语义模型 var model = compilation.GetSemanticModel(syntaxNode.SyntaxTree); // 正确做法：先做语法级筛选 if (syntaxNode is ClassDeclarationSyntax cds && cds.AttributeLists.Count > 0) { var model = compilation.GetSemanticModel(syntaxNode.SyntaxTree); // ... } -
未使用符号缓存：重复查询符号信息会导致性能下降
csharp复制// 使用此方法缓存常用符号 var disposableSymbol = compilation.GetTypeByMetadataName("System.IDisposable");
5.2 典型问题排查
问题1：生成器未触发
- 检查项目文件是否包含：
xml复制<ItemGroup>
<ProjectReference Include="..\YourGenerator\YourGenerator.csproj"
OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
</ItemGroup>
问题2：生成的代码有错误
- 在生成代码中添加#nullable enable
- 使用SyntaxFactory生成的代码建议先格式化：
csharp复制var formattedNode = SyntaxFactory.ParseCompilationUnit(code)
.NormalizeWhitespace();
问题3：IntelliSense不更新
- 清除VS缓存目录（位于%Temp%\VSGeneratedFiles）
6. 企业级应用实践
在某金融系统项目中，我们使用代码生成器实现了以下功能：
-
自动API客户端生成：
- 扫描Controller类
- 生成TypeScript客户端代码
- 包含JWT认证处理逻辑
-
数据库实体转换：
csharp复制[GenerateMapper] public class Account { public string Id { get; set; } public decimal Balance { get; set; } } // 自动生成 public static class AccountMapper { public static AccountDto ToDto(this Account entity) => new() { Id = entity.Id, Balance = entity.Balance }; } -
审计日志增强：
- 为标记[Auditable]的方法
- 自动生成入参/出参日志代码
- 集成公司内部的日志系统
实施后统计显示：
- 重复代码量减少65%
- 新功能开发效率提升30%
- 因手写错误导致的缺陷下降40%
7. 生态整合建议
7.1 与热门框架结合
ASP.NET Core集成：
csharp复制// 自动注册所有生成的Validator
services.AddValidatorsFromAssemblyContaining<ProductValidator>();
// 生成器端代码
var validatorRegistrations = $$"""
[assembly: {{typeSymbol.ContainingNamespace}}.{{typeSymbol.Name}}ValidatorRegistration]
namespace {{typeSymbol.ContainingNamespace}} {
public static partial class ValidatorRegistrations {
[global::Microsoft.Extensions.DependencyInjection.Extensions.ServiceCollectionExtensions.AddValidatorsFromAssemblyContaining]
public static class {{typeSymbol.Name}}ValidatorRegistration {
static {{typeSymbol.Name}}ValidatorRegistration() {
global::Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions
.AddValidatorsFromAssemblyContaining<{{typeSymbol.Name}}Validator>(services);
}
}
}
}
""";
7.2 代码生成器开发工具推荐
-
Roslyn Quoter：
- 将C#代码转换为SyntaxFactory调用
- 在线版：https://roslynquoter.azurewebsites.net/
-
Source Generators Explorer：
- VS扩展，实时查看生成结果
- 支持生成器调试
-
BenchmarkDotNet：
- 对生成器进行性能测试
- 特别适合增量生成器优化
8. 安全与维护建议
-
版本控制策略：
- 生成器与主项目使用独立版本号
- 在生成的代码中嵌入版本信息：
csharp复制// <auto-generated/> // Generator version: 1.2.0 // Generated at: {DateTime.UtcNow:yyyy-MM-dd} -
向后兼容处理：
csharp复制// 旧版本生成器生成的代码 public partial class ProductValidator { partial void CustomRules() { // 用户自定义规则 } } // 新版本生成器保留partial方法 public partial class ProductValidator { partial void CustomRules(); } -
安全校验：
- 检查生成的代码是否包含危险字符
- 对字符串属性值进行编码处理
csharp复制private string Sanitize(string input) { return input.Replace("\"", "\"\"") .Replace("\r", "") .Replace("\n", ""); }
在最近一次安全审计中，我们发现生成器需要特别注意：
- 避免使用动态编译（如CSharpScript）
- 对用户输入属性名进行严格校验
- 生成的文件名避免使用特殊字符