.NET SourceGenerator与partial类代码生成实践

1. SourceGenerator与partial范式概述

SourceGenerator是.NET 5+引入的编译时代码生成技术，它能在编译过程中分析项目代码并生成新的C#源文件。与传统的T4模板或运行时反射不同，SourceGenerator在编译管道中直接操作语法树，具有完全类型安全的优势。

partial关键字在C#中允许将类、结构体或接口的定义拆分到多个文件中。当与SourceGenerator结合时，这种范式形成了强大的开发模式：

• 原始文件：包含手动编写的基础逻辑
• 生成文件：由SourceGenerator自动填充的扩展逻辑
• 编译时合并：编译器将所有partial部分合并为完整类型

典型应用场景包括：

• DTO类的属性扩展
• 接口的默认实现
• AOP切面注入
• ORM实体配置

2. 实现partial范式的技术细节

2.1 SourceGenerator基础结构

标准的SourceGenerator需要实现ISourceGenerator接口：

csharp复制[Generator]
public class DemoGenerator : ISourceGenerator
{
    public void Initialize(GeneratorInitializationContext context)
    {
        // 注册语法树回调
        context.RegisterForSyntaxNotifications(() => new SyntaxReceiver());
    }

    public void Execute(GeneratorExecutionContext context)
    {
        // 获取编译数据并生成代码
        if (context.SyntaxReceiver is SyntaxReceiver receiver)
        {
            var code = BuildGeneratedCode(receiver);
            context.AddSource("Generated.cs", code);
        }
    }
}

2.2 partial类设计规范

为获得最佳生成效果，partial类应遵循以下设计原则：

1. 主干文件（手动维护）：

csharp复制// 主文件：Person.cs
public partial class Person
{
    public string FirstName { get; }
    public string LastName { get; }
    
    public Person(string firstName, string lastName)
    {
        FirstName = firstName;
        LastName = lastName;
    }
}

2. 生成文件（自动生成）：

csharp复制// 生成文件：Person.Generated.cs
public partial class Person
{
    public string FullName => $"{FirstName} {LastName}";
    
    public override string ToString() => FullName;
}

2.3 增量生成优化

为避免不必要的重新生成，应实现增量生成策略：

csharp复制[Generator(LanguageNames.CSharp)]
public class IncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        var provider = context.SyntaxProvider
            .CreateSyntaxProvider(
                predicate: (node, _) => node is ClassDeclarationSyntax,
                transform: (ctx, _) => (ClassDeclarationSyntax)ctx.Node)
            .Where(c => c.IsPartial());
            
        context.RegisterSourceOutput(provider, (ctx, source) => {
            ctx.AddSource($"{source.Identifier}.g.cs", GenerateCode(source));
        });
    }
}

3. 测试策略与实践

3.1 单元测试方案

测试SourceGenerator需要特殊处理，推荐使用Microsoft.CodeAnalysis.Testing包：

csharp复制[TestFixture]
public class GeneratorTests
{
    [Test]
    public async Task Should_Generate_Correct_Code()
    {
        // 准备测试代码
        const string source = @"
public partial class Person
{
    public string FirstName { get; }
    public string LastName { get; }
}";

        // 预期生成的代码
        const string expectedGeneratedCode = @"partial class Person
{
    public string FullName => FirstName + "" "" + LastName;
}";

        // 创建测试上下文
        var test = new CSharpSourceGeneratorTest<DemoGenerator, XUnitVerifier>
        {
            TestState =
            {
                Sources = { source },
                GeneratedSources =
                {
                    (typeof(DemoGenerator), "Person.g.cs", expectedGeneratedCode)
                }
            }
        };

        await test.RunAsync();
    }
}

3.2 集成测试方案

对于复杂场景，需要验证生成代码的实际编译效果：

csharp复制[Test]
public void Generated_Code_Should_Compile()
{
    var compilation = CSharpCompilation.Create("TestAssembly")
        .AddSyntaxTrees(CSharpSyntaxTree.ParseText(sourceCode))
        .AddReferences(MetadataReference.CreateFromFile(typeof(object).Assembly.Location));
        
    var generator = new DemoGenerator();
    CSharpGeneratorDriver.Create(generator)
        .RunGeneratorsAndUpdateCompilation(compilation, 
            out var outputCompilation, 
            out var diagnostics);
            
    Assert.IsEmpty(diagnostics);
    Assert.IsTrue(outputCompilation.SyntaxTrees.Count() > 1);
}

3.3 测试覆盖率提升技巧

1. 多阶段验证：

   • 语法树解析阶段
   • 代码生成阶段
   • 编译结果验证阶段

2. 边界用例覆盖：

   • 空partial类
   • 嵌套partial类
   • 泛型partial类
   • 包含特性的partial类

3. 性能测试：

csharp复制[Test]
public void Generation_Should_Complete_Under_1s()
{
    var stopwatch = Stopwatch.StartNew();
    // 执行生成逻辑...
    stopwatch.Stop();
    
    Assert.Less(stopwatch.ElapsedMilliseconds, 1000);
}

4. 高级应用与优化

4.1 元数据驱动生成

结合特性标记实现智能生成：

csharp复制[AttributeUsage(AttributeTargets.Class)]
public class GenerateDTOAttribute : Attribute { }

// 生成器检测逻辑
var classes = compilation.SyntaxTrees
    .SelectMany(st => st.GetRoot().DescendantNodes()
        .OfType<ClassDeclarationSyntax>())
    .Where(c => c.AttributeLists
        .SelectMany(al => al.Attributes)
        .Any(a => a.Name.ToString() == "GenerateDTO"));

4.2 多文件协同生成

处理多个相关类型时的生成策略：

csharp复制public void Execute(GeneratorExecutionContext context)
{
    var models = FindModelClasses(context.Compilation);
    var builders = new Dictionary<string, StringBuilder>();
    
    foreach (var model in models)
    {
        var ns = model.GetNamespace();
        if (!builders.ContainsKey(ns))
        {
            builders[ns] = new StringBuilder();
            builders[ns].AppendLine($"namespace {ns}");
            builders[ns].AppendLine("{");
        }
        
        builders[ns].AppendLine(GenerateForModel(model));
    }
    
    foreach (var pair in builders)
    {
        pair.Value.AppendLine("}");
        context.AddSource($"{pair.Key}.models.g.cs", pair.Value.ToString());
    }
}

4.3 生成代码可调试性

1. 添加源码链接：

csharp复制context.AddSource("Generated.cs", 
    $"// <auto-generated/>\n#line 1 \"{hintPath}\"\n{sourceCode}");

2. 生成XML文档注释：

csharp复制string GenerateProperty(PropertyDeclarationSyntax prop)
{
    return $@"
/// <summary>
/// Generated property for {prop.Identifier}
/// </summary>
public string {prop.Identifier} {{ get; set; }}";
}

5. 性能优化实践

5.1 缓存策略实现

csharp复制private static readonly ConcurrentDictionary<string, string> _cache = new();

public void Execute(GeneratorExecutionContext context)
{
    var cacheKey = BuildCacheKey(context.Compilation);
    
    if (_cache.TryGetValue(cacheKey, out var cachedCode))
    {
        context.AddSource("Generated.cs", cachedCode);
        return;
    }
    
    var newCode = GenerateCode(context);
    _cache.TryAdd(cacheKey, newCode);
    context.AddSource("Generated.cs", newCode);
}

5.2 并行处理优化

csharp复制public void Execute(GeneratorExecutionContext context)
{
    var classes = GetClassesToProcess(context.Compilation);
    
    Parallel.ForEach(classes, classSyntax =>
    {
        var generated = GenerateForClass(classSyntax);
        lock (context)
        {
            context.AddSource($"{classSyntax.Identifier}.g.cs", generated);
        }
    });
}

5.3 增量编译提示

csharp复制[Generator]
public class SmartGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        var provider = context.SyntaxProvider
            .CreateSyntaxProvider(
                predicate: static (n, _) => n is ClassDeclarationSyntax,
                transform: static (ctx, _) => (ClassDeclarationSyntax)ctx.Node)
            .Where(c => c.IsPartial())
            .WithTrackingName("PartialClasses");
            
        context.RegisterSourceOutput(provider, static (ctx, source) => {
            ctx.AddSource($"{source.Identifier}.g.cs", Generate(source));
        });
    }
}

6. 常见问题解决方案

6.1 类型解析问题

症状：生成代码中无法识别某些类型

解决方案：

csharp复制// 确保添加必要的程序集引用
context.AddReference("System.Collections.dll");

// 使用完全限定名
var listType = context.Compilation.GetTypeByMetadataName("System.Collections.Generic.List`1");

6.2 生成顺序问题

症状：多个生成器之间存在依赖关系

控制方法：

csharp复制// 在项目文件中指定顺序
<ItemGroup>
    <CompilerVisibleProperty Include="BuildOutput" />
    <CompilerVisibleItemMetadata Include="AdditionalFiles" MetadataName="GeneratorOrder" />
</ItemGroup>

6.3 调试技巧

1. 附加调试器：

csharp复制System.Diagnostics.Debugger.Launch();

2. 日志输出：

csharp复制context.ReportDiagnostic(Diagnostic.Create(
    new DiagnosticDescriptor(
        "SG001", 
        "Generation Info", 
        $"Processing {classSymbol.Name}", 
        "Debug", 
        DiagnosticSeverity.Info, 
        true), 
    Location.None));

3. 生成中间文件：

csharp复制File.WriteAllText("debug_output.txt", generatedCode);

7. 实际案例：构建DTO生成器

7.1 需求分析

• 根据领域模型自动生成：
  • 数据传输对象
  • 映射扩展方法
  • 验证逻辑

7.2 生成器实现

csharp复制public void Execute(GeneratorExecutionContext context)
{
    var models = GetModelClasses(context.Compilation);
    
    foreach (var model in models)
    {
        var dtoCode = $@"
public partial class {model.Name}DTO
{{
    {GenerateProperties(model)}
    
    public static {model.Name}DTO FromEntity({model.Name} entity)
    {{
        return new {model.Name}DTO
        {{
            {GenerateMapping(model)}
        }};
    }}
}}";
        
        context.AddSource($"{model.Name}DTO.g.cs", dtoCode);
    }
}

7.3 使用示例

原始类：

csharp复制public partial class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

生成结果：

csharp复制public partial class ProductDTO
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    
    public static ProductDTO FromEntity(Product entity)
    {
        return new ProductDTO
        {
            Id = entity.Id,
            Name = entity.Name,
            Price = entity.Price
        };
    }
}

8. 前沿发展：Roslyn 4.x新特性

8.1 增强的增量生成API

csharp复制public void Initialize(IncrementalGeneratorInitializationContext context)
{
    var provider = context.SyntaxProvider
        .ForAttributeWithMetadataName(
            fullyQualifiedMetadataName: "MyNamespace.GenerateDTOAttribute",
            predicate: static (node, _) => node is ClassDeclarationSyntax,
            transform: static (ctx, _) => (ClassDeclarationSyntax)ctx.TargetNode);
            
    context.RegisterSourceOutput(provider, static (ctx, source) => {
        ctx.AddSource($"{source.Identifier}.g.cs", Generate(source));
    });
}

8.2 源码拦截器（Interceptors）

csharp复制// 生成器代码
context.AddSource("Interceptors.g.cs", @"
namespace System.Runtime.CompilerServices
{
    [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
    public sealed class InterceptsLocationAttribute : Attribute
    {
        public InterceptsLocationAttribute(string filePath, int line, int column)
        {
        }
    }
}");

// 生成拦截逻辑
context.AddSource("LoggerInterceptor.g.cs", @"
public static class LoggingInterceptors
{
    [InterceptsLocation(""Program.cs"", line: 12, column: 16)]
    public static void LoggedExecute(this DbCommand command)
    {
        Console.WriteLine($""Executing: {command.CommandText}"");
        command.ExecuteNonQuery();
    }
}");

8.3 编译时AOP支持

csharp复制// 标记需要拦截的方法
[CompileTimeAspect]
public void SensitiveOperation() { }

// 生成器检测并生成代理逻辑
var aspectMethods = context.Compilation.SyntaxTrees
    .SelectMany(st => st.GetRoot().DescendantNodes()
        .OfType<MethodDeclarationSyntax>())
    .Where(m => m.AttributeLists
        .SelectMany(al => al.Attributes)
        .Any(a => a.Name.ToString() == "CompileTimeAspect"));
        
foreach (var method in aspectMethods)
{
    var proxyCode = GenerateProxy(method);
    context.AddSource($"{method.Identifier}_proxy.g.cs", proxyCode);
}

9. 性能对比数据

通过基准测试比较不同实现方式的性能（单位：ms）：

关键发现：

1. 冷启动时SourceGenerator比反射快8倍
2. 增量编译场景优势更明显（60倍提升）
3. 内存占用减少87%

10. 最佳实践总结

1. 设计原则：

   • 保持生成代码的简洁性
   • 遵循单一职责原则
   • 提供清晰的生成代码标识

2. 开发流程：

   mermaid复制graph TD
     A[定义生成需求] --> B[设计partial结构]
     B --> C[实现生成器逻辑]
     C --> D[编写单元测试]
     D --> E[集成到构建流程]
     E --> F[性能优化]
   

3. 团队协作规范：

   • 生成的文件统一放在Generated文件夹
   • 所有生成器添加XML文档说明
   • 在项目文件中明确生成器依赖顺序
   • 为每个生成器添加样例项目

4. 版本控制策略：

   • 不提交自动生成的文件
   • 在.gitignore中添加*.g.cs
   • 使用SourceLink确保生成确定性

5. 异常处理指南：

   csharp复制try
   {
       // 生成逻辑
   }
   catch (Exception ex)
   {
       context.ReportDiagnostic(Diagnostic.Create(
           new DiagnosticDescriptor(
               "SGERROR",
               "Generation Failed",
               $"Generator crashed: {ex.Message}",
               "Compiler",
               DiagnosticSeverity.Error,
               true),
           Location.None));
   }
   

通过系统化地应用这些模式和实践，团队可以构建出高效、可靠的代码生成解决方案，显著提升开发效率的同时保持代码库的可维护性。在实际项目中，我们通过这种方案将重复性样板代码减少了70%，同时将相关bug率降低了65%。