.NET 诊断数据契约CDAC解读EcmaMetadata 契约如何为调试器重建 ECMA-335 元数据【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime本文是 .NET 运行时诊断数据契约Diagnostic Contracts for DAC简称 CDAC系列中的一篇聚焦于 EcmaMetadata 契约。该契约的目标是为给定模块Module提供一个符合 ECMA-335 规范的元数据视图使调试器、诊断工具与System.Reflection.Metadata能够以统一的方式读取运行时内存中的元数据。读完本文你将掌握 EcmaMetadata 契约的五个 API、只读/读写元数据三种获取路径的分派逻辑、底层数据描述符Data Descriptor布局以及它如何借助#JTD标记流还原 MDInternalRW 内部格式。契约定位诊断工具眼中的元数据在 .NET 运行时的传统设计中调试器Debugger通过 DACData Access Component读取目标进程的托管内存。新一代 CDAC 设计将其抽象为一组契约Contract每个契约声明一组类型化 API并依赖数据描述符Data Descriptor来定位运行时结构体中的字段。EcmaMetadata 契约正是这组契约中专门负责元数据访问的一员它的官方定义位于 docs/design/datacontracts/EcmaMetadata.md。契约的核心职责非常聚焦为给定的模块提供 ECMA-335 元数据的视图。这里的视图需要覆盖三种现实场景只读元数据模块加载后未被修改过的原始元数据例如从 PE 文件 CLI Header 的 Metadata 目录直接解析读写元数据已保存副本通过 Edit and ContinueEnC等机制动态更新后运行时保存的元数据快照读写元数据活动状态运行时内部以MDInternalRW格式维护的、可被持续修改的元数据。契约的最终产出是一个可以直接交给System.Reflection.Metadata.MetadataReader消费的内存镜像这意味着诊断工具可以复用托管层成熟的元数据解析器而不必自行解析运行时内部结构。契约 API 总览EcmaMetadata 契约暴露了五个方法定义见 docs/design/datacontracts/EcmaMetadata.mdbool HasReadWriteMetadata(TargetPointer peAssembly); TargetSpan GetReadOnlyMetadataAddress(ModuleHandle handle); TargetSpan GetReadWriteSavedMetadataAddress(ModuleHandle handle); System.Reflection.Metadata.MetadataReader? GetMetadata(ModuleHandle handle); byte[] GetReadWriteMetadata(ModuleHandle handle);各方法的职责API职责HasReadWriteMetadata(peAssembly)判断给定PEAssembly是否拥有可更新的元数据即MDImportIsRW标志是否非零GetReadOnlyMetadataAddress(handle)返回只读元数据在目标进程地址空间中的TargetSpan地址 大小GetReadWriteSavedMetadataAddress(handle)返回 EnC 过程中保存的动态元数据快照地址GetMetadata(handle)综合分派返回一个可用的MetadataReader取不到时返回nullGetReadWriteMetadata(handle)从MDInternalRW重建一份连续的 ECMA-335 元数据镜像并返回字节数组其中ModuleHandle并非本契约自有类型而是来自 Loader 契约。Loader 契约负责提供模块、程序集、AppDomain 的句柄与加载信息例如GetModuleHandleFromModulePtr、GetPEAssembly(handle)等EcmaMetadata 在此基础上按模块句柄取元数据。三种元数据可用形态AvailableMetadataType理解GetMetadata的分派逻辑是掌握本契约的关键。契约内部使用一个标志枚举来刻画当前模块可用的元数据形态[Flags] enum AvailableMetadataType { None 0, ReadOnly 1, ReadWriteSavedCopy 2, ReadWrite 4 }判定逻辑来自模块上的两个字段AvailableMetadataType GetAvailableMetadataType(ModuleHandle handle) { AvailableMetadataType flags AvailableMetadataType.None; TargetPointer dynamicMetadata Target.ReadPointer(handle.Address /* Module::DynamicMetadata offset */); uint metadataGeneration Target.Readuint(handle.Address /* Module::MetadataGeneration offset */); if (dynamicMetadata ! TargetPointer.Null) { flags | AvailableMetadataType.ReadWriteSavedCopy; } else if (metadataGeneration ! 0) { flags | AvailableMetadataType.ReadWrite; } else { flags | AvailableMetadataType.ReadOnly; } return flags; }判定优先级体现的是运行时状态的本质区别若Module::DynamicMetadata非空说明存在 EnC 过程中保存的动态元数据快照DynamicMetadata结构包含Data与Size两个字段优先使用已保存副本若Module::MetadataGeneration一个每次模块元数据变化时递增的计数器非零说明模块经历过元数据修改应读取活动状态的读写元数据否则模块元数据从未被修改直接使用只读元数据即可。这一设计确保了诊断工具总是拿到当前最准确的元数据状态同时优先选择代价最低的读取路径。只读路径从 PE 头定位元数据目录GetReadOnlyMetadataAddress的伪代码展示了从模块基址出发定位 ECMA-335 元数据的完整过程TargetSpan GetReadOnlyMetadataAddress(ModuleHandle handle) { TargetPointer baseAddress Target.ReadPointer(handle.Address /* Module::Base offset */); if (baseAddress TargetPointer.Null) { return default; } // 读取 CLR (COR20) header 的 RVA再读取其元数据目录RVA size位于偏移 8 ulong clrHeaderRVA ... // 按 ECMA-335 II.25.3.3 CLI Header 读取 Metadata 目录 ulong metadataDirectoryAddress baseAddress clrHeaderRva /* offset to Metadata */ int rva Target.Readint(metadataDirectoryAddress); ulong size Target.Readint(metadataDirectoryAddress sizeof(int)); return new(baseAddress rva, size); }值得注意的是伪代码中专门注释了一个特殊场景Webcil扁平镜像。例如 WASM 上以 ReadyToRun 形式存在的 corelib是经过剥离/重新包装的 PE无法按标准 PE 解析其文件头以WbIL魔术字开头。此时需要借助 webcil 头中的PeCliHeaderRva定位 CLICOR20头再从其元数据目录偏移 8 处的 RVA size定位元数据并且 RVA 的解析必须走 loader 的 webcil 感知的GetILAddr路径。这体现了契约对多样化运行时形态包括 WASM的完整覆盖。读写路径从 MDInternalRW 重建 ECMA-335 镜像GetReadWriteMetadata是整个契约中实现最复杂的部分。它的任务是把运行时内部以MDInternalRW格式维护的元数据重建为一份连续的、符合 ECMA-335 规范的内存镜像从而可以交给MetadataReader解析。重建流程的核心步骤均来自契约文档的伪代码注释通过 Loader 契约取得模块的PEAssembly进而读取PEAssembly::MDImport得到MDInternalRW沿指针链逐级深入MDInternalRW::Stgdb→CLiteWeightStgdbRW::MiniMd→CMiniMdRW::SchemaCMiniMdSchema校验CMiniMdRW::TableCount不超过 ECMA-335 的合法表数量从CMiniMdSchema::RecordCounts读取每张表的行数用CMiniMdSchema::Sorted的位掩码判断表是否有序解码CMiniMdSchema::Heaps判定字符串/GUID/blob 堆是否使用大索引记录CMiniMdRW::All4ByteColumns以便重建时保留定宽的可变列以存储池storage pool为单位读取各堆字符串堆StringHeap、Blob 堆BlobHeap、用户字符串堆UserStringHeap、GUID 堆GuidHeap以及每张表的记录存储池CMiniMdRW::Tables[i]读取CLiteWeightStgdbRW::MetadataAddress处的元数据版本字符串使用构造器写出元数据根头与版本字符串添加#Strings、#Blob、#GUID、#US及未压缩表流#-的流头依次追加各堆数据并回填流偏移编写#-表流写出表流头、堆大小标志、有效表掩码行数非零的表、排序表掩码、每张有效表的行数再按表号顺序追加各表的连续记录 Blob以模块当前的元数据代际计数器为键缓存重建结果。存储池的分段读取是其中的底层细节StgPool描述符给出头段的SegData与DataSize随后沿NextSegment链表遍历后续的StgPoolSeg节点把所有非空段的SegData/DataSize记录下来最后分配一块足以容纳所有段的字节数组按链表顺序把各段读入得到一段连续的 Blob。这与运行时元数据引擎中存储池可动态增长的实现是吻合的。#JTD 标记流固定宽度可变列的特殊编码重建过程中有一个非常关键的细节——#JTD标记流。当CMiniMdRW::All4ByteColumns表明所有可变宽度列都是 4 字节宽时重建器除了常规流外还会额外添加一个#JTD标记流。契约文档对此的解释是官方 ECMA-335 元数据格式并不以这种方式编码列宽但System.Reflection.Metadata在观察到#JTD标记流时支持这种编码变体。也就是说这是MetadataReader对 ECMA-335 标准之外的一种内部扩展格式的兼容支持读取方靠#JTD流的存在性来获知所有可变宽度列统一为 4 字节从而正确解析表流。这在 MetadataReader 的实现 中可以得到印证——该托管解析器同时支持标准变体与#JTD变体的表流解析。缓存与失效MetadataGeneration 计数器GetReadWriteMetadata的重建结果不是每次调用都重新计算。契约伪代码明确指出重建后的镜像按模块缓存直到该模块的元数据代际计数器Module::MetadataGeneration发生变化为止。这与GetAvailableMetadataType的判定逻辑互相呼应MetadataGeneration是每次模块元数据变更时递增的计数器。重建器在首次构建后记录当时的代际值后续调用若发现代际未变直接返回缓存的 Blob一旦发生 EnC 等元数据修改代际变化触发缓存失效并重新重建。这一机制在正确性始终反映最新元数据与性能避免反复重建大块内存镜像之间取得了平衡。数据描述符契约与运行时结构体的映射EcmaMetadata 契约的 v1 版本依赖一组数据描述符它们把契约中的逻辑字段映射到运行时实际结构体的成员偏移上。这些映射声明在运行时源码 src/coreclr/vm/datadescriptor/datadescriptor.inc 中例如CLiteWeightStgdbRWMetadataAddress指向元数据镜像的指针、MiniMd内嵌的CMiniMdRW模型地址CMiniMdRWSchema、TableCount、All4ByteColumns、Tables以及StringHeap/BlobHeap/UserStringHeap/GuidHeap四个存储池CMiniMdSchemaHeaps堆大小标志字节、Sorted排序表位掩码、RecordCounts内联的行数数组StgPool/StgPoolSegSegData、NextSegment、DataSize三段式存储池链表描述MDInternalRWStgdb指向读写存储数据库ModuleDynamicMetadataEnC 动态元数据指针与MetadataGeneration代际计数器PEAssemblyMDImport与MDImportIsRWDynamicMetadataData与Size。在数据描述符源码中可以看到这些类型的完整声明方式例如CMiniMdRW被声明为不确定大小CDAC_TYPE_INDETERMINATE的结构其字段通过cdac_dataCMiniMdRW::*绑定偏移StgPool与StgPoolSeg以链表字段NextSegment相互衔接Module::DynamicMetadata通过cdac_dataModule::DynamicMetadata定位。契约 v1 与这些数据描述符一一对应最终由CDAC_GLOBAL_CONTRACT(EcmaMetadata, c1)注册为全局契约。各字段的语义说明还可在>MetadataReader? GetMetadata(ModuleHandle handle) { AvailableMetadataType type GetAvailableMetadataType(handle); switch (type) { case AvailableMetadataType.None: return null; case AvailableMetadataType.ReadOnly: { TargetSpan address GetReadOnlyMetadataAddress(handle); byte[] data new byte[address.Size]; _target.ReadBuffer(address.Address, data); return MetadataReaderProvider.FromMetadataImage(ImmutableCollectionsMarshal.AsImmutableArray(data)).GetMetadataReader(); } case AvailableMetadataType.ReadWriteSavedCopy: { TargetSpan address GetReadWriteSavedMetadataAddress(handle); byte[] data new byte[address.Size]; _target.ReadBuffer(address.Address, data); return MetadataReaderProvider.FromMetadataImage(ImmutableCollectionsMarshal.AsImmutableArray(data)).GetMetadataReader(); } case AvailableMetadataType.ReadWrite: { byte[] data GetReadWriteMetadata(handle); return MetadataReaderProvider.FromMetadataImage(ImmutableCollectionsMarshal.AsImmutableArray(data)).GetMetadataReader(); } } }三种路径的最终产物完全一致通过MetadataReaderProvider.FromMetadataImage将内存镜像包装为MetadataReader。区别只在于镜像的来源与构造代价——只读路径直接映射 PE 中的元数据目录已保存副本路径直接映射DynamicMetadata快照而活动读写路径需要走完整的 MDInternalRW 重建流程。GetReadWriteSavedMetadataAddress的实现也因此非常简单从Module::DynamicMetadata读取指针取DynamicMetadata::Size作为大小返回DynamicMetadata::Data处的TargetSpan。小结契约设计带来的工程价值从诊断工具的视角看EcmaMetadata 契约实现了三个关键目标统一抽象无论模块元数据处于只读、EnC 快照还是活动读写状态调用方都只需面对一个MetadataReader复杂逻辑下沉MDInternalRW 内部格式到 ECMA-335 标准格式的转换、Webcil 特殊解析、存储池分段拼接等复杂细节全部封装在契约实现内部上层工具无需感知可组合性契约仅依赖 Loader 契约数据描述符声明与伪代码实现一一对应新增平台或运行时结构变化时只需更新对应描述符。对于想要深入源码的读者建议按以下路径继续研读先从 EcmaMetadata 契约文档 理解整体设计再对照 datadescriptor.inc 中CDAC_TYPE_BEGIN(CMiniMdRW)、StgPool/StgPoolSeg、DynamicMetadata、MDInternalRW、CLiteWeightStgdbRW等描述符确认字段映射最后在 MetadataReader.cs 中观察托管解析器如何消费这些镜像——尤其是#JTD标记流对应的表流解码分支从而把契约定义 → 数据描述符 → 托管解析这条链路完整串起来。【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考