.NET源码生成器开发指南：提升C#开发效率

1. .NET源码生成器开发背景与核心价值

在.NET生态中，源码生成器(Source Generator)正逐渐成为提升开发效率的利器。它能在编译期间动态生成C#代码，与手动编写的代码无缝融合。这种技术特别适合解决重复性编码问题，比如DTO转换、API客户端生成等场景。我最近在一个电商平台项目中，就用源码生成器自动生成了200多个实体类的GraphQL类型定义，节省了近两周的手动编码时间。

partial类(部分类)是这项技术的黄金搭档。它允许我们将一个类的定义分散在多个文件中，源码生成器生成的代码可以作为一个独立的部分类文件存在。这种范式既保持了代码整洁，又避免了生成代码与手写代码的冲突。想象一下，你有一个User类，手动编写的业务逻辑放在User.cs，而自动生成的序列化代码放在User.g.cs，两者通过partial机制在编译时合并，就像拼图一样完美契合。

NuGet打包则是分享源码生成器的最佳方式。通过NuGet包，我们可以将生成器分发给团队其他成员或开源社区，使用者只需安装包就能获得代码生成能力，无需关心实现细节。这比直接复制源代码更规范，也便于版本管理。最近帮一个金融客户打包的报文生成器，通过NuGet发布后，团队协作效率提升了40%。

2. 源码生成器开发环境准备

2.1 开发工具选型

工欲善其事，必先利其器。我习惯使用Visual Studio 2022进行源码生成器开发，它提供了最完整的.NET开发体验。特别是17.3版本后对源码生成器的调试支持更加完善。如果更喜欢轻量级环境，VSCode配合C#插件也是不错的选择，但需要手动配置tasks.json来支持生成器调试。

项目模板选择很关键。推荐使用dotnet new classlib创建类库项目，然后修改项目文件为SDK风格。这是我常用的项目文件配置：

<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <LangVersion>9.0</LangVersion> <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.3.1" PrivateAssets="all" /> <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.3" PrivateAssets="all" /> </ItemGroup> </Project>

注意几个关键点：

• TargetFramework设为netstandard2.0确保最大兼容性
• EnforceExtendedAnalyzerRules启用更严格的分析器规则
• 分析器包使用PrivateAssets="all"避免传递依赖

2.2 项目结构规划

良好的项目结构能提升代码可维护性。我通常采用这样的目录结构：

/src /MyGenerator # 生成器主项目 /Models # 数据模型 /Templates # 代码模板 /Utilities # 工具类 MyGenerator.cs # 生成器主类 /MyGenerator.Tests # 单元测试项目

在Templates文件夹中，我会存放Razor模板或字符串模板用于代码生成。对于复杂模板，Razor引擎是不错的选择，虽然需要引入Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation包，但模板可读性更好。简单场景下，直接使用字符串插值或StringBuilder更轻量。

3. 核心生成器实现详解

3.1 ISourceGenerator接口实现

每个源码生成器都必须实现ISourceGenerator接口。这是我的典型实现骨架：

[Generator] public class MySourceGenerator : ISourceGenerator { public void Initialize(GeneratorInitializationContext context) { // 注册语法接收器 context.RegisterForSyntaxNotifications(() => new MySyntaxReceiver()); } public void Execute(GeneratorExecutionContext context) { if (!(context.SyntaxContextReceiver is MySyntaxReceiver receiver)) return; // 1. 收集类型信息 var targetTypes = GetTargetTypes(context, receiver); // 2. 生成源代码 foreach (var type in targetTypes) { var sourceCode = GenerateSource(type); context.AddSource($"{type.Name}.g.cs", SourceText.From(sourceCode, Encoding.UTF8)); } } }

关键点说明：

• [Generator]特性标记这是源码生成器
• Initialize方法中注册语法接收器收集编译信息
• Execute方法是生成核心，通过context.AddSource输出代码

3.2 语法分析与类型收集

语法接收器(Syntax Receiver)是生成器的"眼睛"，用于在编译过程中收集我们需要处理的类型信息。这是我常用的增强版接收器：

class MySyntaxReceiver : ISyntaxReceiver { public List<ClassDeclarationSyntax> CandidateClasses { get; } = new(); public void OnVisitSyntaxNode(SyntaxNode syntaxNode) { if (syntaxNode is ClassDeclarationSyntax classDecl && classDecl.Modifiers.Any(m => m.IsKind(SyntaxKind.PartialKeyword))) { CandidateClasses.Add(classDecl); } } }

这个接收器会收集所有partial类定义。在实际项目中，我通常会添加更多过滤条件，比如：

• 带有特定特性的类
• 继承特定基类的类
• 位于特定命名空间的类

收集到语法节点后，还需要获取完整的语义模型信息：

INamedTypeSymbol GetTypeSymbol(GeneratorExecutionContext context, ClassDeclarationSyntax classDecl) { var model = context.Compilation.GetSemanticModel(classDecl.SyntaxTree); return model.GetDeclaredSymbol(classDecl) as INamedTypeSymbol; }

3.3 代码生成策略

代码生成有多种实现方式，根据复杂度不同我通常分三个层级：

1. 字符串拼接：适合简单场景

string GenerateSimpleClass(string className) { return $@" namespace Generated {{ public partial class {className} {{ public string GeneratedProperty {{ get; set; }} }} }}"; }

2. 模板引擎：中等复杂度

string GenerateWithTemplate(TypeInfo type) { var template = @" public partial class @Model.TypeName { @foreach(var prop in Model.Properties) { public @prop.Type @prop.Name { get; set; } } }"; return Engine.Razor.RunCompile(template, type); }

3. SyntaxFactory：完全控制语法树

CompilationUnitSyntax CreateCompilationUnit(string className) { return SyntaxFactory.CompilationUnit() .AddMembers( SyntaxFactory.NamespaceDeclaration(SyntaxFactory.ParseName("Generated")) .AddMembers( SyntaxFactory.ClassDeclaration(className) .AddModifiers(SyntaxFactory.Token(SyntaxKind.PublicKeyword)) .AddMembers( SyntaxFactory.PropertyDeclaration( SyntaxFactory.ParseTypeName("string"), "GeneratedProperty") .AddAccessorListAccessors( SyntaxFactory.AccessorDeclaration(SyntaxKind.GetAccessorDeclaration) .WithSemicolonToken(SyntaxFactory.Token(SyntaxKind.SemicolonToken)), SyntaxFactory.AccessorDeclaration(SyntaxKind.SetAccessorDeclaration) .WithSemicolonToken(SyntaxFactory.Token(SyntaxKind.SemicolonToken)) ) ) ) ); }

在最近的一个ORM项目中，我混合使用了这三种方式：用SyntaxFactory构建基础结构，模板引擎生成常规属性，字符串拼接处理特殊场景，取得了很好的灵活性和可维护性平衡。

4. NuGet打包与分发策略

4.1 项目配置优化

正确的项目配置是打包成功的前提。这是我的典型配置：

<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <IsPackable>true</IsPackable> <PackageId>My.Awesome.Generator</PackageId> <Version>1.0.0</Version> <IncludeBuildOutput>false</IncludeBuildOutput> <DevelopmentDependency>true</DevelopmentDependency> <NoPackageAnalysis>true</NoPackageAnalysis> </PropertyGroup> <ItemGroup> <None Include="$(OutputPath)\$(AssemblyName).dll" Pack="true" PackagePath="analyzers/dotnet/cs" Visible="false" /> </ItemGroup> </Project>

关键配置解析：

• IncludeBuildOutput=false避免将生成器本身作为常规程序集打包
• DevelopmentDependency=true标记为开发依赖
• 将DLL放入analyzers/dotnet/cs目录，这是源码生成器的标准位置

4.2 多目标框架支持

为了扩大兼容范围，我通常会支持多目标框架：

<TargetFrameworks>netstandard2.0;netcoreapp3.1;net5.0;net6.0</TargetFrameworks>

同时需要在代码中使用条件编译：

#if NETSTANDARD2_0 // 兼容性代码 #elif NET5_0_OR_GREATER // 使用新特性 #endif

4.3 依赖管理

依赖处理需要特别注意：

• 分析器依赖必须设为PrivateAssets="all"
• 如果生成器依赖第三方库，需要仔细考虑是否要传递这些依赖

<ItemGroup> <PackageReference Include="Newtonsoft.Json" Version="13.0.1" PrivateAssets="all" /> <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.3.1" PrivateAssets="all" /> </ItemGroup>

4.4 符号包与源码链接

为了更好的调试体验，我会配置符号包和源码链接：

<PropertyGroup> <PublishRepositoryUrl>true</PublishRepositoryUrl> <EmbedUntrackedSources>true</EmbedUntrackedSources> <IncludeSymbols>true</IncludeSymbols> <SymbolPackageFormat>snupkg</SymbolPackageFormat> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="all" /> </ItemGroup>

这样使用者调试时能看到生成器的源码，极大简化问题排查。

5. 高级应用场景与性能优化

5.1 增量生成策略

大规模项目中，增量生成能显著提升性能。.NET 6引入了IncrementalGenerator，这是我在当前项目中的实现：

[Generator] public class MyIncrementalGenerator : IIncrementalGenerator { public void Initialize(IncrementalGeneratorInitializationContext context) { var provider = context.SyntaxProvider .CreateSyntaxProvider( predicate: (node, _) => node is ClassDeclarationSyntax c && c.Modifiers.Any(m => m.IsKind(SyntaxKind.PartialKeyword)), transform: (ctx, _) => (ClassDeclarationSyntax)ctx.Node) .Where(c => c != null); context.RegisterSourceOutput(provider, (spc, syntax) => { var source = GenerateSource(syntax); spc.AddSource($"{syntax.Identifier.Text}.g.cs", source); }); } }

实测在一个包含2000个类的项目中，增量生成将编译时间从28秒降到了9秒。

5.2 跨项目生成策略

当需要在一个解决方案中跨项目生成代码时，我采用这种模式：

1. 定义共享接口项目(Contracts)

public interface ICodeGenerationTarget { string Namespace { get; } string ClassName { get; } }

2. 在生成器项目中分析标记了该接口的类型
3. 生成的代码输出到共享的"Generated"文件夹

项目文件需要添加：

<ItemGroup> <Compile Include="..\Shared\Generated\*.g.cs" Link="Generated\%(Filename)%(Extension)" /> </ItemGroup>

5.3 缓存与性能优化

对于复杂生成器，我实现了多层缓存：

1. 语法分析结果缓存

private static readonly ConcurrentDictionary<string, TypeModel> _typeCache = new(); TypeModel GetCachedType(INamedTypeSymbol symbol) { return _typeCache.GetOrAdd(symbol.GetDocumentationCommentId(), id => BuildTypeModel(symbol)); }

2. 模板编译缓存

void EnsureTemplateCached(string templateName) { if (!Engine.Razor.IsTemplateCached(templateName, null)) { var templateContent = LoadTemplate(templateName); Engine.Razor.AddTemplate(templateName, templateContent); Engine.Razor.Compile(templateName, null); } }

3. 生成结果缓存（基于文件哈希）

string GetFileHash(string path) { using var sha = SHA256.Create(); using var stream = File.OpenRead(path); return Convert.ToBase64String(sha.ComputeHash(stream)); }

这些优化使一个实体类生成器的执行时间从平均120ms降到了35ms。

6. 调试与问题排查实战

6.1 调试技巧

调试源码生成器有几种实用方法：

1. Debugger.Launch()（简单粗暴）

public void Execute(GeneratorExecutionContext context) { Debugger.Launch(); // 生成代码... }

2. 日志输出（更优雅）

context.ReportDiagnostic(Diagnostic.Create( new DiagnosticDescriptor( "SG0001", "Debug Info", $"Processing {type.Name}", "Debug", DiagnosticSeverity.Info, true), Location.None));

3. 文件转储（复杂场景）

File.WriteAllText("D:\\debug_output.txt", generatedCode);

6.2 常见错误处理

这是我整理的错误速查表：

6.3 单元测试策略

为生成器编写测试很具挑战性。我的测试框架包含：

1. 语法树测试：验证生成的语法树结构

[Test] public void GeneratesCorrectClassStructure() { var generator = new MyGenerator(); var input = TestHelper.CreateClassSyntax("MyClass"); var output = generator.Generate(input); Assert.That(output.Members, Has.Exactly(1).TypeOf<ClassDeclarationSyntax>()); var cls = (ClassDeclarationSyntax)output.Members[0]; Assert.That(cls.Identifier.Text, Is.EqualTo("MyClass")); }

2. 编译测试：确保生成的代码可编译

[Test] public void GeneratedCodeShouldCompile() { var compilation = TestHelper.CreateCompilation(""); var generator = new MyGenerator(); GeneratorDriver driver = CSharpGeneratorDriver.Create(generator); driver = driver.RunGeneratorsAndUpdateCompilation(compilation, out var outputCompilation, out var diagnostics); Assert.That(diagnostics, Is.Empty); Assert.That(outputCompilation.GetDiagnostics(), Is.Empty); }

3. 端到端测试：模拟真实项目环境

[Test] public void EndToEndTest() { var project = TestHelper.CreateProject() .WithDocument("MyClass.cs", """ public partial class MyClass { } """); var compilation = await project.GetCompilationAsync(); // 执行生成器并验证结果... }

7. 实际项目经验分享

在最近的一个微服务项目中，我开发了一个gRPC服务端生成器，可以根据接口定义自动生成服务实现骨架。这个生成器显著提升了团队效率，但也遇到了一些挑战：

挑战1：复杂类型支持处理嵌套泛型类型时，最初的生成器会丢失类型参数。解决方案是递归处理所有类型参数：

string GetFullTypeName(ITypeSymbol type) { if (type is INamedTypeSymbol namedType && namedType.IsGenericType) { var args = string.Join(", ", namedType.TypeArguments.Select(GetFullTypeName)); return $"{namedType.Name}<{args}>"; } return type.Name; }

挑战2：多项目协作当生成器需要跨多个项目收集信息时，我建立了一个中央注册表模式：

1. 定义一个注册表接口

public interface ITypeRegistry { void RegisterType(TypeInfo info); IEnumerable<TypeInfo> GetRegisteredTypes(); }

2. 每个项目中的生成器部分将信息注册到共享文件
3. 主生成器读取共享文件生成最终代码

性能调优经验在生成2000+DTO类的场景下，原始实现需要45秒。通过以下优化降到8秒：

1. 并行处理独立类型
2. 缓存反射结果
3. 使用StringBuilder池减少内存分配

重要提示：在团队中推广源码生成器时，一定要提供完善的文档和示例。我通常会创建两个示例项目：一个展示基本用法，另一个演示高级场景。同时维护一个"生成代码预览"文档，帮助团队成员理解自动生成的代码。