1. 理解.NET源码生成器的核心价值
在.NET生态中，源码生成器（Source Generators）正逐渐成为提升开发效率的利器。它允许我们在编译过程中动态生成C#代码，这种技术特别适合解决那些需要大量重复模板代码的场景。想象一下，当你需要为几十个DTO类编写相同的序列化逻辑时，手动编码不仅枯燥低效，还容易出错。而源码生成器就像一位不知疲倦的助手，能自动完成这些机械性工作。
partial类（部分类）是这个机制的最佳搭档。通过将生成的代码与手写代码分离到不同的partial类文件中，我们既保持了代码的整洁性，又避免了生成代码覆盖手工代码的风险。这种范式让源码生成器可以安全地"注入"代码，而不会干扰开发者的正常工作流程。
NuGet打包则是分享这种生产力的关键。将源码生成器打包为NuGet包后，团队其他成员只需简单安装就能获得相同的代码生成能力，无需复杂配置。这大大降低了技术共享的门槛，使得最佳实践能在团队中快速传播。
2. 搭建源码生成器开发环境
2.1 项目结构规划
一个标准的源码生成器解决方案通常包含三个项目：
- 生成器项目：实际的源码生成器实现（必须为.NET Standard 2.0）
- 测试项目：验证生成器功能的单元测试（.NET Core 3.1+）
- 消费项目：演示如何使用生成器的示例项目
使用Visual Studio 2022或Rider创建新解决方案时，建议采用以下目录结构：
code复制SourceGeneratorDemo/
├── src/
│ ├── DemoGenerator/ # 生成器项目
│ └── DemoConsumer/ # 消费项目
└── tests/
└── DemoGenerator.Tests/ # 测试项目
2.2 必备NuGet包引用
在生成器项目中，需要添加这些关键包引用：
xml复制<ItemGroup>
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.3.1" PrivateAssets="all" />
<PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.3" PrivateAssets="all" />
</ItemGroup>
重要提示：务必设置PrivateAssets="all"，避免这些分析器包传递到消费项目
2.3 开发工具配置
推荐安装这些VS扩展提升开发效率：
- Roslynator - 提供丰富的Roslyn API代码补全
- Syntax Visualizer - 可视化查看代码语法树
- Source Generator Explorer - 实时预览生成的代码
对于调试，需要在launchSettings.json中配置：
json复制"compilerOptions": {
"plugins": ["path/to/your/generator.dll"]
}
3. 实现源码生成器的核心逻辑
3.1 创建生成器骨架
每个源码生成器都需要继承自ISourceGenerator接口：
csharp复制[Generator]
public class DemoGenerator : ISourceGenerator
{
public void Initialize(GeneratorInitializationContext context)
{
// 注册语法接收器
context.RegisterForSyntaxNotifications(() => new SyntaxReceiver());
}
public void Execute(GeneratorExecutionContext context)
{
// 核心生成逻辑
}
}
3.2 使用SyntaxReceiver收集目标类型
SyntaxReceiver像是一个侦察兵，在编译过程中识别我们感兴趣的代码模式：
csharp复制class SyntaxReceiver : ISyntaxReceiver
{
public List<ClassDeclarationSyntax> CandidateClasses { get; } = new();
public void OnVisitSyntaxNode(SyntaxNode syntaxNode)
{
if (syntaxNode is ClassDeclarationSyntax classDecl &&
classDecl.AttributeLists.Count > 0)
{
CandidateClasses.Add(classDecl);
}
}
}
3.3 基于partial范式生成代码
假设我们要为标记了[GenerateHelper]的类生成扩展方法：
csharp复制string GenerateExtensionClass(ClassDeclarationSyntax classDecl)
{
string namespaceName = GetNamespace(classDecl);
string className = classDecl.Identifier.Text;
return $$"""
// <auto-generated/>
namespace {{namespaceName}};
public static partial class {{className}}Extensions
{
public static void PrintInfo(this {{className}} obj)
{
Console.WriteLine("自动生成的扩展方法");
}
}
""";
}
关键点：
- 生成的类名遵循"原类名+Extensions"的约定
- 使用partial允许后续手动扩展
- 必须包含
标记
4. 高级生成技巧与优化
4.1 增量生成提升性能
对于大型项目，使用IncrementalGenerator可以显著提升编译速度：
csharp复制[Generator(LanguageNames.CSharp)]
public class IncrementalDemoGenerator : IIncrementalGenerator
{
public void Initialize(IncrementalGeneratorInitializationContext context)
{
var classDeclarations = context.SyntaxProvider
.CreateSyntaxProvider(
predicate: static (s, _) => IsTargetClass(s),
transform: static (ctx, _) => GetClassInfo(ctx))
.Where(static m => m is not null);
context.RegisterSourceOutput(classDeclarations,
static (spc, source) => Execute(source, spc));
}
}
4.2 处理多文件依赖关系
当生成代码需要跨文件引用时，可以使用AddSource的hintName参数：
csharp复制context.AddSource($"Helpers.{className}.g.cs",
SourceText.From(code, Encoding.UTF8));
4.3 与编译时诊断集成
可以在生成过程中添加警告或错误提示：
csharp复制if (hasError)
{
context.ReportDiagnostic(Diagnostic.Create(
new DiagnosticDescriptor(
"SG001",
"Invalid attribute usage",
"标记为[GenerateHelper]的类必须是partial类",
"Design",
DiagnosticSeverity.Error,
true),
location: null));
}
5. NuGet打包与发布策略
5.1 正确的包结构配置
.csproj文件中需要特殊配置：
xml复制<PropertyGroup>
<IncludeBuildOutput>false</IncludeBuildOutput>
<EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
</PropertyGroup>
<ItemGroup>
<None Include="$(OutputPath)\$(AssemblyName).dll"
Pack="true"
PackagePath="analyzers/dotnet/cs"
Visible="false" />
</ItemGroup>
5.2 版本控制策略
建议采用语义化版本控制：
- 主版本号：破坏性变更
- 次版本号：新增功能但向下兼容
- 修订号：Bug修复
对于预览版：
xml复制<Version>1.0.0-preview.3</Version>
5.3 本地测试包的最佳实践
使用本地NuGet源进行测试：
bash复制dotnet pack --configuration Release
nuget add bin/Release/DemoGenerator.1.0.0.nupkg -Source ~/local-nuget-source
然后在消费项目中添加本地源引用：
xml复制<PackageReference Include="DemoGenerator" Version="1.0.0" />
6. 实际应用场景解析
6.1 DTO自动映射
为数据库实体生成ToDto()方法：
csharp复制public static partial class UserExtensions
{
public static UserDto ToDto(this User entity) => new()
{
Id = entity.Id,
Name = entity.UserName,
// 自动复制所有匹配属性...
};
}
6.2 API响应包装器
自动生成统一响应格式：
csharp复制[GenerateResponseWrapper]
public class UserController : ControllerBase { }
// 生成结果
public static class UserControllerResponseExtensions
{
public static ApiResponse<T> OkResponse<T>(this UserController _, T data)
{
return new ApiResponse<T> { Data = data, Success = true };
}
}
6.3 领域事件生成
为领域模型生成事件相关代码：
csharp复制[GenerateDomainEvents]
public partial class Order
{
public void Cancel() => AddDomainEvent(new OrderCancelledEvent(this));
}
// 自动生成
public partial class Order
{
private readonly List<IDomainEvent> _domainEvents = new();
public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();
protected void AddDomainEvent(IDomainEvent @event) => _domainEvents.Add(@event);
public void ClearDomainEvents() => _domainEvents.Clear();
}
7. 调试与问题排查指南
7.1 常见编译错误处理
问题1：生成器未执行
- 检查是否标记了[Generator]特性
- 确认项目引用了Microsoft.CodeAnalysis.CSharp包
- 检查生成器项目的TargetFramework是否为netstandard2.0
问题2：类型找不到
- 确保消费项目引用了生成器所需的所有依赖
- 检查生成代码的namespace是否正确
7.2 使用日志诊断
在生成器中添加日志输出：
csharp复制if (!context.AnalyzerConfigOptions.GlobalOptions.TryGetValue(
"build_property.TargetFramework", out var targetFramework))
{
context.ReportDiagnostic(Diagnostic.Create(
new DiagnosticDescriptor(
"SG100",
"Configuration error",
"无法获取TargetFramework属性",
"Configuration",
DiagnosticSeverity.Warning,
true),
Location.None));
}
7.3 实时调试技巧
- 在生成器项目中设置Debugger.Launch()
- 配置MSBuild诊断日志：
bash复制dotnet build /v:diag > build.log
- 使用Source Generator Explorer查看中间结果
8. 性能优化与进阶技巧
8.1 缓存策略实现
利用CompilationProvider实现数据缓存：
csharp复制var compilationProvider = context.CompilationProvider.Select(
(compilation, _) => GetCacheableData(compilation));
context.RegisterSourceOutput(compilationProvider,
(spc, data) => GenerateUsingCache(data, spc));
8.2 并行生成处理
对于独立代码生成任务，可以使用Parallel.ForEach：
csharp复制Parallel.ForEach(classDeclarations, classDecl =>
{
var code = GenerateCode(classDecl);
lock (context)
{
context.AddSource($"Gen_{Guid.NewGuid()}", code);
}
});
8.3 与AOP框架集成
结合PostSharp等AOP框架：
csharp复制[PSerializable]
public class LoggingGenerator : ISourceGenerator
{
[IntroduceInterface(typeof(ILoggable))]
public void ImplementInterface(Type targetType)
{
// 生成ILoggable实现...
}
}
9. 安全注意事项与最佳实践
9.1 输入验证
对所有输入语法节点进行严格验证：
csharp复制if (classDecl.BaseList?.Types.Any(t => t.ToString() == "IDisposable") == true)
{
context.ReportDiagnostic(Diagnostic.Create(
// 警告不能为IDisposable实现生成代码...
));
return;
}
9.2 避免命名冲突
为生成成员添加特殊前缀：
csharp复制private const string GeneratedPrefix = "__sg_";
string GenerateFieldName(string original) => $"{GeneratedPrefix}{original}";
9.3 处理符号冲突
使用完全限定名避免歧义：
csharp复制var typeSymbol = context.Compilation.GetTypeByMetadataName(
"System.Collections.Generic.List`1");
10. 版本兼容性策略
10.1 多框架支持
在生成器中检查目标框架：
csharp复制var isNetCore = context.ParseOptions.PreprocessorSymbolNames
.Contains("NETCOREAPP");
10.2 处理API差异
使用反射处理不同版本的API：
csharp复制var method = typeof(SyntaxNode).GetMethod("GetDiagnostics");
if (method != null)
{
// 新版本API逻辑
}
else
{
// 回退逻辑
}
10.3 废弃策略
通过诊断信息提示用户迁移：
csharp复制context.ReportDiagnostic(Diagnostic.Create(
new DiagnosticDescriptor(
"SG200",
"Deprecated feature",
"此特性将在下个主版本移除，请使用NewFeature替代",
"Deprecation",
DiagnosticSeverity.Warning,
true),
location: node.GetLocation()));
在实际项目中，我发现源码生成器最适合那些有明确模式且变化不大的场景。对于业务逻辑多变的部分，过度依赖代码生成反而会增加维护成本。一个好的经验法则是：如果你发现自己在第三次复制粘贴相似的代码块，就该考虑使用源码生成器了。
调试生成器时，建议先用小规模代码测试核心逻辑，再逐步扩大范围。记住，生成的代码最终会成为项目的一部分，所以它的质量应该和你手写的代码一样高。我通常会为生成的代码编写对应的单元测试，确保生成逻辑的可靠性。
关于NuGet发布，内部建议维护两个源：一个用于开发中的预览包，一个用于稳定版本。这样团队可以在不影响主开发线的情况下测试新特性。每次发布前，务必在干净环境中测试包的安装和使用流程，避免依赖项缺失等问题。