chinboy
6.4 KiB
AtomUI.Generator 模块概览
AtomUI.Generator 是 AtomUI 的普通 Roslyn 源生成器项目，TargetFramework 为 netstandard2.0。它不作为运行时依赖使用，而是以
Analyzer 方式被多个项目引用。AOT/Trim usage、Sidecar 和 Application Plan 位于独立的 linked-publish Analyzer 中，只在对应
发布构建或 Package Manifest Pack 时加载。
职责
- 根据 Global Token 定义生成强类型 schema、资源键和投影代码。
- 根据 public 可主题化 Control、无参数
[ControlDesignToken]标记的可选 Own Token 类型和命名/目录约定生成独立 Control identity 与 descriptor；Attribute 只负责 Token 发现，不携带 Control 类型、identity 或 ID。 - Control Token 定义继承要求 Generator 区分无 identity 的标记抽象层与
sealed终端类型，将跨程序集 继承属性扁平化到终端 schema，并在构建期验证继承链、属性冲突和默认计算 base 调用。 - 分析构建系统提供的
Themes/**/*.axaml，生成 ControlTheme asset owner、引用 identity、Semantic Part 契约和 包级 manifest；不收集 Global Token 消费白名单。 - 为每个 Control 包生成包级注册 helper 和 manifest，由真实
UseXxxControls()入口调用；不要求逐 Control 或逐 Theme 手工注册。 - 根据统一
AtomUIRegistrationGranularity策略生成 Package/Directory Unit identity 和 leaf fragment；普通包默认单一 Package Unit，大型包才显式按目录拆分。 - linked-publish Generator 从 C#/AXAML 直接证据生成 Sidecar UnitEdge/Usage，在应用编译期计算 closure/SCC 并输出静态计划。
- 根据
[LanguageCatalog]enum 与 XLIFF 2.1 生成强类型资源扩展、Catalog/Bundle 注册和应用 bootstrap。 - 消除 Control 包对 Token、主题资产和语言手工清单及运行时程序集扫描的依赖。
生成器
| 生成器 | 说明 |
|---|---|
TokenResourceKeyGenerator |
分析 Global Token、可主题化 Control、[ControlDesignToken] Own Token 和主题资产输入，生成 exact CLR type/identity、强类型资源键、descriptor、asset manifest 与包级注册代码 |
LocalizationGenerator |
编译 Catalog/XLIFF，生成强类型 Markup Extension、模块注册与应用语言包 bootstrap |
LanguageTagsGenerator |
从固定语言数据生成常用 BCP 47 LanguageTags 和标准 LanguageDefinition 元数据 |
DataMemberAccessorGenerator |
根据数据模型 Attribute 生成 AOT 友好的数据成员访问器注册 |
ScopedResourceHostGenerator |
根据 [GenerateScopedResourceHost] 为非 Visual AvaloniaObject 生成 scoped 资源宿主生命周期样板代码 |
| Linked-publish generators | 只在 AOT/Trim 或 Package Manifest Pack 中生成 Sidecar、usage 和 Application Plan；不进入普通编译 |
关键目录
| 目录 | 说明 |
|---|---|
DesignToken/ |
Token Walker、TokenInfo、资源键和类型池 Writer |
Localization/ |
Catalog symbol、XLIFF、Bundle 编译、模块注册、应用 bootstrap 与 BCP 47 数据生成 |
DataMemberAccessors/ |
数据成员访问器 Generator、Analyzer 和 SourceWriter |
ResourceHost/ |
非 Visual AvaloniaObject scoped resource host Generator、TypeInfo 和 SourceWriter |
LinkedRegistration/ |
Package 粒度、入口 identity、leaf Unit fragment 和共享协议模型 |
TargetMarkConstants.cs |
生成器识别的 Attribute 元数据名 |
专题文档
- Control Design Token 继承架构：抽象/终端类型模型、 跨程序集属性扁平化、diagnostic、schema revision 和运行时/AOT 边界。
- Scoped Resource Host Generator：目标识别、生成输出、生命周期状态机、diagnostic 和测试契约。
- Scoped Resource Host 开发规范：Control 作者的适用场景、owner 生命周期、验证和 review 规则。
- Semantic Part Generator 设计：Control 语义区域的声明、AXAML 校验、descriptor、 diagnostics、增量生成和 AOT 边界。
- AOT 与裁剪架构：linked publish、Registration Unit、Application Plan 和安全 fallback。
- Linked Registration Generator：Analyzer 物理隔离、候选增量分析、Sidecar、leaf fragment、 Application Plan 和性能预算。
- AOT Linked Registration Pipeline：Sidecar 资产边界、 构建模式、运行时不变量和验证契约。
- AOT Registration Unit 粒度：粒度策略、资源归属、 第一方 Package 映射和第三方包契约。
- 第三方 AtomUI Control Package 指南：包作者的最小项目、入口和验证步骤。
维护注意
新增可主题化 Control、带 [ControlDesignToken] 的可选 Own Token、Themes/**/*.axaml 资产、Catalog enum 或 XLIFF 后，应检查对应项目的
GeneratedFiles/AtomUI.Generator/ 输出，确认 exact CLR type/identity、强类型 Token key、descriptor、asset manifest、本地化表和包级注册
结果完整。Control 没有 Own Token 时仍必须生成 identity、XxxTokenResource 和零 Own Token descriptor。由于生成
目录被 <Compile Remove=...> 排除且默认被 .gitignore 忽略，不应把生成文件当成普通源码维护；只有被结构测试
明确读取的 GalleryBase 快照才需要同步提交。
新增或修改 Generator 时，应同时检查 writer 代码、诊断规则和生成物稳定性。linked registration 不得全树遍历、递归进入
callee body 或生成 Unit 间调用；普通 Debug/Release 必须从 compiler command line 上完全排除 linked analyzer。对于非 Visual
AvaloniaObject 资源宿主类需求，按 Scoped Resource Host 开发规范
管理 owner 生命周期，并由本模块的 Generator 生成样板代码。
实现 Control Token 定义继承时，抽象层不得生成 identity、descriptor、resource key、Registration Unit 或 linked fragment； 只有终端 Token 产生运行时输出。声明层类型、程序集和继承深度不得进入终端 schema fingerprint。