为什么 .NET 中的自定义属性（Custom Attributes）让我夜不能寐

背景

在 .NET 生态系统中，虽然许多开发者认为作者是 .NET 的拥趸（尤其是在之前的文章之后），但作为 PE（Portable Executable）解析库 AsmResolver 的核心维护者，作者对 .NET 二进制文件的解剖结构有着深入的了解。基于这种底层视角，作者指出微软在 .NET 文件格式设计中存在一些令人费解且极具挫败感的选择。

其中，自定义属性（Custom Attributes） 的底层存储机制被作者视为微软在 .NET 历史上做出的最糟糕的设计决策之一。这一设计在过去几年中给 AsmResolver 的维护带来了巨大的痛苦，以至于在核心维护者群体中，这已经成为一个梗（meme）。作者坚信，自定义属性是“万恶之源”，甚至因此产生了心理阴影。

核心内容

什么是自定义属性？

自定义属性是附加在类、方法、字段、参数等元素上的额外元数据片段。它们通常用于指示 C# 编译器执行额外的操作。

• 经典示例：ObsoleteAttribute。当用户代码中使用了标记了该属性的对象时，编译器会生成警告。
• 自定义扩展：开发者可以定义自己的自定义属性，并为其定义参数。
• 应用场景：它们是扩展函数、变量或类型周围正常元数据的好方法，主要被分析器（analyzers）、源生成器（source generators）以及动态初始化/检查使用。它们在元编程以及对象的自动序列化/反序列化等场景中非常有用。

自定义属性的解剖结构

在 .NET 文件格式中，所有数据都存储在元数据表（metadata tables）数据库中。类型、字段、方法、参数等各自拥有独立的表，通过元数据令牌（metadata token，即表索引+行索引）进行高效引用。

在 CustomAttribute 表中，每一行代表一个属性的实例化。它包含：

1. 对被附加属性的成员（Member）的引用。
2. 对属性构造函数的引用。
3. 指向 Blob 流（blob stream）的索引，该 Blob 引用了调用构造函数所需的参数数组。

Blob 签名是本文关注的重点。在自定义属性签名中，所有参数都被序列化为二进制表示并依次连接。这种二进制表示完全由属性构造函数的参数类型隐含决定。例如，如果第一个参数类型是 int，前四个字节编码整数；如果是 string，则跟随一个长度前缀的字符数组。

自定义属性中的枚举值（Enum Values）

大多数自定义属性并不接受 int 或 string 等原始参数，而是包含定义为 enum 类型的参数。

根据 ECMA 规范，枚举值以其**基础类型（underlying type）**的方式序列化。

• 如果枚举隐式继承自 int，实例化时将占用 4 字节。
• 如果枚举继承自 short，则仅占用 2 字节。

为了正确读取枚举参数，解析器必须知道枚举的基础类型，并从签名中读取相应数量的字节。否则，后续参数的字节解释将出错。

确定枚举基础类型的巨大代价

确定枚举的基础类型是一个极其昂贵的操作，原因如下：

1. 缺乏直接指示：属性本身或其构造函数的签名中没有任何迹象表明枚举的基础类型。因此，必须解析枚举类型本身以检查其元数据结构。
2. 类型解析（Type Resolution）的复杂性：
   • 程序集解析（Assembly Resolution）：首先需要确定类型存储在哪一个程序集中。这涉及在磁盘的各种目录中探测 DLL 文件（使用复杂的探测算法，不同 .NET 版本可能不同，有时需要解析二进制文件附带的 JSON 或 XML 文件），解析相关头文件，遍历元数据流，并验证名称、版本、公钥令牌等。
   • 类型树遍历（Type Tree Traversal）：找到候选程序集后，需搜索匹配的类型。这意味着遍历 TypeDef 表（对于 mscorlib.dll 这样的大型 DLL，可能有数千行），解析每个条目的名称并检查匹配。
   • 嵌套类型（Nested Types）：如果枚举是嵌套类型，TypeDef 表仅指定 Name 和 Namespace（嵌套类型通常为 null），不存储父类型信息。必须查阅 NestedClass 表，该表将嵌套类型与其直接封闭类型关联。这需要递归处理（例如，类 C 被 B 包含，B 被 A 包含，需遍历两行 NestedClass 表）。
   • 类型转发（Type Forwarders）：类型可能并未定义在刚找到的程序集中，而是转发到另一个程序集。例如，使用 System.DebuggableAttribute.DebuggingModes 会引用 System.Runtime.dll，但该程序集中并未定义此类型，而是通过导出类型表将其转发到 System.Private.CoreLib.dll。理论上，可以有任意多层转发，每层都会触发新的程序集和类型解析。

结论：类型解析是一项非平凡的操作。即使实施重度缓存（如程序集和类型解析缓存），其复杂度和出错概率也远高于直接读取一个字节。

遍历枚举类型

即使最终解析了枚举类型，确定其基础类型仍然困难：

• 在 TypeDef 表中，枚举类型的 Extends 列始终设置为 System.Enum，而非其基础类型。
• 必须找到枚举类型中定义的隐藏非静态字段（通常名为 value__）。这需要迭代另一个表（Field 表）的子集。
• 找到该字段后，需解析其字段签名以确定字段类型。

只有完成这一系列繁琐步骤，才能决定从签名中消耗 1、2、4 或 8 个字节来处理单个基于枚举的参数。如果自定义属性定义了另一个枚举参数，这一过程将重复执行。

关键要点

• 设计缺陷：.NET 自定义属性的 Blob 签名机制缺乏对枚举基础类型的内联指示，导致解析器无法直接读取数据。
• 高昂的解析成本：为了确定枚举的基础类型，解析器必须执行完整的“类型解析”流程，包括程序集探测、DLL 头解析、TypeDef 和 NestedClass 表遍历，以及处理 Type Forwarders。
• 递归与嵌套复杂性：嵌套枚举类型需要递归查询 NestedClass 表，而类型转发机制可能导致链式解析，进一步增加计算开销。
• 缺乏元数据指引：枚举的基础类型信息隐藏在 value__ 字段的签名中，而非直接在类型定义或属性签名中体现，迫使解析器进行额外的元数据探索。
• 维护者的痛点：对于像 AsmResolver 这样的 PE 解析库维护者而言，这种设计导致了大量的边界情况处理、性能瓶颈和潜在的解析错误，是底层开发中的主要噩梦来源。

意义与影响

这一分析揭示了 .NET 元数据设计在“易用性”与“底层解析效率”之间的巨大失衡。虽然自定义属性为 C# 开发者提供了强大的元编程能力，但其底层的存储格式设计忽视了二进制解析器的需求。

对于工具开发者（如反编译器、静态分析工具、序列化库）而言，这意味着处理 .NET 二进制文件时，必须承担极高的计算成本来解析简单的属性参数。这种设计不仅影响了工具的性能，还增加了实现的复杂性和出错概率。它提醒我们，在构建高级抽象时，底层数据格式的灵活性不应以牺牲解析的可预测性和效率为代价。对于 .NET 生态的未来版本，优化自定义属性的存储格式或提供解析辅助信息，将是提升工具链性能的关键方向。