聊一聊.NET里的Source Generator。很多刚开始用源生成器的人,最大的困惑不是怎么写generator,而是生成的代码怎么跟手写的代码“拼”在一起。答案其实早就写在语言里了:partial。我自己的经验是,只要你把partial的几个使用范式玩顺,源生成器就从“魔法黑盒”变成一个相当顺手的编译期工具。这篇文章会从partial在源生成器里的两种核心角色讲起,带一个可以直接跑的示例,再聊聊怎么给生成器写自动化测试,最后分享几个踩坑点。适合正在写或准备写源生成器的朋友。
这里的“范式”不是数据库三范式,而是指写Source Generator时沉淀下来的几种固定套路:一种是partial class,生成器往用户已有的类型里补成员;另一种是partial method,用户只写方法声明,生成器负责生成实现。两者可以单独用,也能组合用。理解了这两种范式的边界,就能明白什么时候该让用户写partial关键字、什么时候生成器只需静默补文件,整个设计思路会清晰很多。
1. 为什么partial和Source Generator是天生一对
先回到编译器的视角。Roslyn源生成器的执行流程是:先把用户代码解析成语法树,再构建语义模型,然后运行生成器,最后把生成器输出的源码当成额外的语法树,和用户源码一起参与编译。也就是说,生成器本质上是在“编译过程的中途”往程序集里塞新代码,它不能回头去改用户写好的那个文件。
那问题就来了:生成器塞进来的代码,怎么和用户手写的类无缝合并?最直接的语言机制就是partial。一个班级的人分两拨写作业,最后合成一份完整的作业,靠的是“partial”这个约定:编译器知道同一个类型的定义可以分散在多个文件里,合并时把成员汇总到一起。所以从语言设计的角度说,partial就是给代码生成器预留的官方接口。
没有partial之前,想给一个已有类补充成员,只能继承、扩展方法或者改源代码,代价都不小。有了partial之后,生成器可以很自然地生成一个“配套文件”,用户代码里写半个类,生成器补另外半个,编译器负责合并。这也就是为什么所有与Source Generator相关的模板和官方示例,几乎都离不开partial关键字。
1.1 partial在Source Generator里的双重角色
partial在源生成器里有两个角色,很多人一开始会混淆。
第一个角色是partial type,也就是partial class、partial struct、partial interface、partial record。它的作用是让“类型定义可以分散到多个源文件”。用户在自己的文件里写public partial class Foo,生成器在另一个文件里也生成public partial class Foo,两个文件里的成员会被合并成一个类型。通过这种方式,生成器可以往用户类里添加属性、字段、方法、嵌套类型等。
第二个角色是partial method,也就是partial void DoSomething();这种声明。它的特点是:在一个文件中只写方法签名,在另一个文件中写实现。C# 9之前,partial方法有严格限制,必须返回void、不能有访问修饰符、不能有out参数;如果始终没人提供实现,编译器会自动移除方法以及所有调用点。C# 9之后放开了一大截,partial方法可以有返回值、可以带访问修饰符,但一旦带了这些,编译器就要求必须有实现部分。
对源生成器来说,partial type解决的是“代码合并到哪”的问题,partial method解决的是“用户怎么预留钩子、生成器怎么补全逻辑”的问题。两者正好对应了两种典型的设计思路:前者适合生成器主动往类型里塞东西,后者适合用户主动声明一个契约、由生成器来履约。
1.2 清楚了“范式”这个词,很多设计就顺了
我一直觉得“范式”这个词听起来玄,实际就是在说“固定的写法套路”。源生成器领域的partial范式,主要就是围绕“谁声明、谁实现、谁触发”这三个关系展开的。
- partial class范式:用户声明一个partial类型,生成器在同一类型名下生成额外成员。触发条件通常是某个Attribute,或者就是“碰到partial类就生成”。这种范式的特点是生成器占主导,用户只需要提供一个空壳类。
- partial method范式:用户声明一个或多个带partial的方法签名,生成器扫描这些签名并生成实现。触发条件是方法本身带partial且没有实现体。这种范式的特点是用户占主导,调用点写在用户代码里,生成器负责把方法体的“坑”填上。
- 组合范式:用户声明partial class,类里放若干partial方法声明,生成器同时生成类成员和partial方法实现。这是最完整的用法,既补类型又补逻辑。
把这几种范式放在一起看,你会发现它们之间的关系是“由表及里”的:partial class决定骨架,partial method决定逻辑。写生成器之前先想清楚自己属于哪一种,代码结构几乎就定了一半。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. partial class与partial method:两种最常用的源生成器范式
2.1 partial class范式:给已有类型“续写代码”
partial class范式的核心是“合并”,适用场景非常广。最典型的例子是INotifyPropertyChanged。用户写一个包含属性的partial类,生成器扫描到这些属性后,在同一类型的另一个partial文件里生成属性变更事件、旧值比较、OnPropertyChanged调用等。整个过程中,用户类原本的代码基本不用改,生成器只负责补全。
我遇到过一个真实案例:项目里有个几十个属性的配置类,手写INotifyPropertyChanged不仅枯燥还容易漏,改一个属性名要动三四个地方。后来我用partial class范式写了个生成器,用户代码只需要声明属性,生成器负责生成完整的通知逻辑。最爽的是,每次改动属性,重新编译就生效,不会再出现“改了属性忘了通知界面”这种低级错误。
partial class范式有几个要点:
- 用户类必须显式声明partial,否则生成器生成的第二份类声明会触发CS0260(缺少partial修饰符)。生成器没办法在编译期修改用户文件,只能靠约定和文档提醒。
- 生成的文件建议统一加
partial,并且文件名以.g.cs结尾。这样IDE会把它识别为生成代码,默认折叠,也方便排查问题。 - 生成器侧通常还要加一些标记特性,比如
[global::System.CodeDom.Compiler.GeneratedCode("MyGenerator", "1.0.0")],避免代码分析工具对生成文件做重复检查。
2.2 partial method范式:让用户写好钩子,生成器补全实现
partial method范式的思路完全反过来:用户先写“钩子”,生成器来填实现。
这种范式常见于需要“可插拔”逻辑的场景。比如你在一个partial类里写:
csharp复制public partial class Logger
{
partial void WriteLog(string message);
}
然后在同一个类的另一个方法里调用WriteLog(...)。生成器扫描到WriteLog只有声明没有实现,就自动生成一个实现,把日志输出到控制台、文件或者某个日志框架。如果未来想换实现,只需要删掉生成器或者换一个生成策略,用户代码完全不用动。
这个模式还有一个特别好用的点:旧式partial方法(void、无修饰符)在“没有实现”时,编译器会移除调用点,相当于调用什么都不发生。这意味着生成器没接上的时候,程序也能正常编译运行,只是功能缺失;接上生成器后,功能立刻生效。这种“渐进式增强”体验非常友好,尤其适合库作者给用户提供可选能力。
2.3 C# 9给partial method带来的变化,直接影响生成器怎么写
写生成器之前必须搞清楚C# 9前后的语法差异,否则生成的代码可能编译不过。
C# 9之前,partial方法必须满足这几个条件:返回类型必须是void;不能有访问修饰符(默认private);不能有out参数;不能有virtual、abstract、override等修饰符。声明和实现都必须带partial关键字。如果只有声明没有实现,编译器会悄悄把调用点从代码里抹掉。
C# 9开始,partial方法允许有非void返回类型、允许有访问修饰符、允许带out参数。但一旦你用了这些新特性,就必须提供实现部分,不能再依赖“未实现就移除调用点”的旧行为。换句话说,C# 9的partial method更像是“严格的契约”:声明了就必须实现,不实现就编译报错。
对生成器来说,这两套规则都要兼容。判断一个partial方法是否需要生成实现,核心逻辑是看它有没有对应的实现部分。有就不生成,没有再生成。我在生成器里的判断方式是:
