Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:.NET metadata (ECMA-335)

From ReverseEngineering.wiki
Format
Developer Microsoft; standardised as ECMA-335 / ISO/IEC 23271 (2001-)
Magic 42 53 4A 42 ("BSJB") at the metadata RVA given by the CLR header
Extensions .dll, .exe, .netmodule, .winmd, .pdb (Portable PDB)
Endianness little
On this wiki Facts · Code · Notes · Topics

The CLI metadata of managed .NET assemblies (ECMA-335 Partition II): a CLR header in PE data directory 14 points to a metadata root starting with "BSJB", whose streams (#~ tables, #Strings, #US, #GUID, #Blob) describe every type, method, field and reference of the module, while IL method bodies sit elsewhere in the PE at RVAs given by the MethodDef table. The same encoding is used by Portable PDB files.

Identification

  • A managed PE has a non-zero data directory 14 (COM descriptor) in the optional header; it points to the 72-byte CLR header (IMAGE_COR20_HEADER), whose MetaData RVA points to the metadata root 42 53 4A 42 ("BSJB", 0x424A5342). See Format:PE (Portable Executable).
  • The metadata root carries a version string: v4.0.30319 for .NET Framework 4.x and for every .NET Core / .NET 5+ assembly, v2.0.50727 for .NET 2.0-3.5, v1.1.4322 and v1.0.3705 for 1.x, PDB v1.0 for a standalone Format:Portable PDB (Fact:.NET metadata (ECMA-335)/identification/Metadata version strings). So the version string tells Framework 2 from Framework 4, not .NET Framework from .NET 8.
  • The real target framework is in the assembly references (System.Runtime = .NET Core/5+ reference assemblies, mscorlib version 4 = Framework 4 or Mono/Unity, netstandard) and in the TargetFrameworkAttribute custom attribute (".NETCoreApp,Version=v8.0").
  • Classic .NET Framework executables import only mscoree.dll!_CorExeMain (DLLs _CorDllMain); ReadyToRun images import nothing. A .NET Core / .NET 5+ application foo.exe is normally a small native apphost that loads foo.dll, the real assembly, or a Format:.NET single-file bundle that carries the assemblies inside the exe.
  • In memory dumps, resources or unpacked payloads, an assembly can be carved by searching for the metadata root (signature fact Fact:.NET metadata (ECMA-335)/signature/Metadata root v4.0.30319; export_symbols with this subject gives a Ghidra/IDA script that finds it).

Layout

Structure Where Contents
CLR header (IMAGE_COR20_HEADER, 72 bytes) RVA in data directory 14 runtime version 2.5, metadata RVA/size, flags (ILONLY, 32BITREQUIRED, IL_LIBRARY, STRONGNAMESIGNED, NATIVE_ENTRYPOINT, 32BITPREFERRED), entry point token, managed resources, strong-name signature, VTable fixups, managed native header (ReadyToRun)
Metadata root CLR header MetaData RVA "BSJB", version 1.1, version string (length rounded to 4), flags, stream count, stream headers
Streams metadata root + stream offset #~ (or #-) tables, #Strings (UTF-8 identifiers), #US (user strings, UTF-16), #GUID (16-byte GUIDs), #Blob (signatures, constants, custom-attribute values), #Pdb only in Portable PDBs
IL method bodies MethodDef.RVA tiny (1-byte) or fat (12-byte) header, IL code, optional exception clauses
Field initial data FieldRVA.RVA raw bytes of static readonly arrays (<PrivateImplementationDetails>)
Managed resources CLR header Resources RVA each resource is uint32 length + bytes, at ManifestResource.Offset from the start

Every offset inside metadata is relative to the metadata root; every RVA must be mapped through the PE section table.

Tables stream

The #~ stream starts with a 24-byte header (Fact:.NET metadata (ECMA-335)/struct/Tables stream header): reserved, version 2.0, HeapSizes (bit 0: #Strings indexes are 4 bytes, bit 1: #GUID, bit 2: #Blob; bit 0x40 adds an extra dword after the row counts), reserved 1, a 64-bit Valid mask of present tables and a 64-bit Sorted mask. Then one uint32 row count per set Valid bit, in table-id order, then the tables themselves, back to back, without padding.

Nothing in the file says how wide a row is: a reader must compute every column width from the row counts (Fact:.NET metadata (ECMA-335)/behavior/Column widths):

  • heap index: 2 bytes, or 4 if the HeapSizes bit is set;
  • simple index into table T: 2 bytes if T has at most 0xFFFF rows, else 4;
  • coded index (a tag in the low bits selects one of several tables): 2 bytes if every candidate table has fewer than 2^(16 - tag bits) rows, else 4.

The 45 type-system tables (0x00-0x2C) and the 8 Portable PDB tables (0x30-0x37), with their columns and the 14 coded-index kinds, are listed in Format:.NET metadata (ECMA-335)/Tables. #- is the uncompressed (edit-and-continue) variant that may contain the indirection tables FieldPtr, MethodPtr, ParamPtr, EventPtr and PropertyPtr; obfuscators use it too (none of the 67630 installed managed files surveyed used it).

Lists are implied by order: TypeDef.MethodList is the first MethodDef row of the type, and the type's methods run up to the next TypeDef's MethodList (or the end of the table). The same holds for FieldList, ParamList, EventList and PropertyList. Row 1 of TypeDef is the pseudo-type <Module> holding global functions and the module initializer .cctor.

Heaps

  • #Strings: NUL-terminated UTF-8, offset 0 is the empty string. Identifiers only (type, member, namespace, module names).
  • #US: string literals of ldstr. Each entry is a compressed length, UTF-16LE text and one final byte, so the length is odd. The ldstr operand is the token 0x70000000 | heap offset. The final byte is supposed to flag special characters but compilers do not set it for ' and - (Fact:.NET metadata (ECMA-335)/behavior/User string heap entries).
  • #Blob: compressed length + bytes; signatures, constant values, custom-attribute arguments, public keys.
  • #GUID: 16-byte GUIDs indexed from 1 (Module.Mvid is usually index 1).

Lengths and signature elements use the ECMA-335 compressed integer encoding (1, 2 or 4 bytes, big endian, high bits 0, 10, 110); test vectors in Fact:.NET metadata (ECMA-335)/behavior/Compressed integers. Public key tokens are the reversed last 8 bytes of SHA-1 of the public key (Fact:.NET metadata (ECMA-335)/behavior/Public key token).

Tokens

A metadata token is table id << 24 | row number (row numbers start at 1): 0x06000001 is the first MethodDef, 0x0A00002B MemberRef 43, 0x70xxxxxx a user string. IL instructions (call, newobj, ldfld, ldtoken...) carry tokens as 4-byte operands, so a method body cannot be read without the metadata. The CLR header's EntryPointToken is a MethodDef token (or a File token for multi-module assemblies), or an RVA when NATIVE_ENTRYPOINT is set (C++/CLI).

Method bodies

At MethodDef.RVA (0 for abstract, P/Invoke and runtime-implemented methods; machine code for methods whose ImplFlags code type is 1, native, in C++/CLI assemblies):

  • tiny header: one byte, low 2 bits 10, upper 6 bits the code size (max 63 bytes); max stack 8, no locals, no exception handlers;
  • fat header: 12 bytes, 4-byte aligned, low 2 bits 11, flags (0x08 more sections, 0x10 init locals), header size 3 in the top nibble of the 16-bit flags word, then max stack (u16), code size (u32), local variable signature token (u32, a StandAloneSig 0x11xxxxxx or 0); Fact:.NET metadata (ECMA-335)/struct/Fat method header.
  • after the code, if "more sections" is set, a 4-byte aligned exception section: kind byte 0x01 (small: 12-byte clauses) or 0x41 (fat: 24-byte clauses), its size, and the clauses (flags 0 catch, 1 filter, 2 finally, 4 fault; try offset/length, handler offset/length, class token or filter offset).

Bodies of consecutive methods are laid out one after another in .text; tiny bodies are not aligned, fat ones are. In 120 framework assemblies 60% of the bodies were tiny.

ReadyToRun

Assemblies of the .NET Core / .NET 5+ shared framework, and apps published with PublishReadyToRun, also contain precompiled native code. The CLR header's ManagedNativeHeader then points to a READYTORUN_HEADER (signature 52 54 52 00, "RTR"), and the CLR flags have IL_LIBRARY set instead of ILONLY (Fact:.NET metadata (ECMA-335)/struct/READYTORUN HEADER). Its section list (type ids from 100, Fact:.NET metadata (ECMA-335)/enum/ReadyToRun section types) locates the native code (RuntimeFunctions = the .pdata-style function table), the MethodDef-to-native-code map (MethodDefEntryPoints), import cells and debug info; section 100 (CompilerIdentifier) holds a string such as Crossgen2 10.0.1126.37416, the exact runtime build, and the header version gives the major release (9.1 = .NET 8, 10.1 = .NET 9, 16.0 = .NET 10; Fact:.NET metadata (ECMA-335)/identification/ReadyToRun version and compiler). Crossgen2 output has no PE imports, sections .text, .data, .reloc and linker version 11.0. IL bodies stay in the file (unless the flag STRIPPED_IL_BODIES is set), so IL decompilers keep working; the native code is used by the runtime when its version rules allow.

Full ReadyToRun description (flags, import sections, composite images, version changelog): Format:.NET ReadyToRun. Fully native AOT output without IL is a different thing: Technique:Identifying .NET NativeAOT executables; Mono's own AOT images: Format:Mono AOT image.

Topics

  • Tables — Every metadata table of ECMA-335 (ids 0x00-0x2C) and of Portable PDB (0x30-0x37) with its columns in file order, and the 14 coded-index kinds with their tag bit

Format:WinRT metadata (WinMD): .winmd files are this format with the WindowsRuntime type flag (0x4000).

Decompilers

See Technique:Choosing a decompiler: Tool:ILSpy (decompile) and Tool:DnSpyEx (debug and edit).

Scope

See also the non-code parts of managed programs: Format:.NET resources (.resources), Format:BAML, Format:.NET runtimeconfig.json and deps.json, Library:Costura.Fody.

Code & repositories

  • https://github.com/0xd4d/dnlib @ 9ab9b58ab31b99b3f6cdef36efec613fc11ddbe2 · license: MIT
    dnlib (C#, MIT): reads and writes .NET assemblies and Portable/Windows PDBs, written to load obfuscated files the way the CLR does (duplicate streams, #- metadata, bad headers); the engine of dnSpy/dnSpyEx and de4dot. src/DotNet/MD/ is a compact reference for the physical metadata layout (CLR header, metadata root, stream headers, #~ header, table schemas, coded tokens), src/DotNet/Emit/MethodBodyReader.cs for IL method headers.
    Tested on: Read at this commit (October 2026); its rules for column sizes, coded indexes, stream selection, compressed integers and method headers were reimplemented in dotnetmd.py and checked against 432 framework assemblies (identical rows to dnfile). Note: StreamHeader.cs line 56 checks offset + size (the header's own size field from FileSection) instead of offset + streamSize for overflow; harmless because MetadataHeader checks the real end afterwards. · checked 2026-10-17; last activity 2026-06-02
  • https://github.com/dotnet/runtime @ d80abfc4b04f85722596e8d83af7f9a61dcf49da · license: MIT
    The .NET runtime (MIT): CoreCLR, the host (apphost, singlefilehost, single-file bundle reader in src/native/corehost/bundle), the bundler (src/installer/managed/Microsoft.NET.HostModel), ReadyToRun definitions (src/coreclr/inc/readytorun.h), System.Reflection.Metadata, and the format specs docs/design/specs/PE-COFF.md (debug directory entries of managed PEs) and PortablePdb-Metadata.md.
    Tested on: Sparse checkout of the files cited on the format pages at this commit (October 2026). The bundle layout was confirmed on five installed single-file apps, the ReadyToRun header on the .NET 8/9/10 shared frameworks, the Portable PDB checksum and PDB-id rules on 1854 SDK assemblies. The comment in bundle_marker.c says the marker is SHA-256 of '.net core bundle'; it is the hash of that text plus a newline. · checked 2026-10-17; last activity 2026-10-17
  • https://github.com/malwarefrank/dnfile @ bde05f174e10cc3df72eee45ff7189c1d9e2a28b · license: MIT
    dnfile (Python, MIT): .NET metadata parser on top of pefile, exposing every table, heap and resource as Python objects; common in malware-analysis scripts (capa, YARA rule generation).
    Tested on: Used at this commit as the independent reference for dotnetmd.py on 432 framework assemblies (identical row counts and rows). It does not work with pefile HEAD 58186a9 (dnPE.__parse__() takes 4 positional arguments but 5 were given: pefile added max_offset); it works with pefile tag v2024.8.26. Its table attribute names differ from ECMA in places (FieldRva for FieldRVA). · checked 2026-10-17; last activity 2026-08-14
  • https://github.com/icsharpcode/ILSpy @ 0abb04db61517e0564923a7beadbab4da13fd830 · license: MIT (read from LICENSE; GitHub's API was busy)
    ILSpy .NET decompiler
    Tested on: source read, not run: not run; README read · checked 2026-10-18
  • https://github.com/dnSpyEx/dnSpy @ ae4df33be41a3846e768b1b8f4690b3c5e166bc6 · license: unrecognized (LICENSE.txt)
    dnSpyEx .NET debugger and editor
    Tested on: source read, not run: not run; README read · checked 2026-10-18; the license file was not recognized automatically: read it

Pitfalls

  • The PE import table, sections and entry point say almost nothing about a .NET program; open it in an IL decompiler (ILSpy, dnSpyEx) instead of a native disassembler. Native disassembly is only useful for ReadyToRun code, C++/CLI mixed-mode assemblies and P/Invoke targets.
  • Obfuscated files often add streams with duplicate names, junk after the version string or in the reserved fields, #- instead of #~, or tables with more rows than the stream holds; follow the runtime's rules, not the header counts (Fact:.NET metadata (ECMA-335)/behavior/Duplicate stream names).
  • Row counts are 24-bit in practice (Mono and dnlib mask the high byte).
  • The metadata size in the CLR header is not trusted by Mono; dnlib reads to the end of the image.
  • The version string length is a multiple of 4 in well-formed files but the CLR reads exactly the stated length; Mono rounds it up.
  • Since .NET Framework 4.0 the version string is always v4.0.30319, even for .NET 10.
  • Satellite assemblies (*.resources.dll) have no AssemblyRef rows and no code, only ManifestResource rows.

Tools

  • Code:.NET metadata (ECMA-335)/dotnetmd (Python): dependency-free reader written for this page: CLR header, metadata root, streams, row counts, assembly and references, every TypeDef with its methods and IL header kind, #US dump, ReadyToRun header, Portable PDB debug entries and embedded PDB extraction, single-file bundle listing and extraction.
  • dnlib (C#, MIT): reads and writes assemblies, tolerant of obfuscation; used by dnSpy/dnSpyEx and de4dot.
  • ILSpy (C#, MIT) and dnSpyEx (GPL-3.0): IL decompilers to C#.
  • dnfile (Python, MIT, on top of pefile): table-level parser used in malware analysis.
  • System.Reflection.Metadata (part of dotnet/runtime, MIT): Microsoft's own reader; MetadataReader follows the runtime's rules.
  • monodis, ildasm (Windows SDK) for IL listings.

Open questions

  • Which tool writes managed PEs whose metadata root lists a stream named '#!' first (#!,#Strings,#~,#US,#GUID,#Blob), and what does that stream contain? — Seen in 6 of 67630 managed PE files on a Windows 11 machine with Visual Studio 2026 and other programs (October 2026). dnlib treats unknown stream names as custom streams, so the files still load. Not in ECMA-335 or the Portable PDB spec. (asked by PatientStepper99, 2026-10-17)

Evidence & references

  • ECMA-335 6th edition (2012), Partition II sections 22 (tables), 23.2 (blobs and signatures, compressed integers), 24 (metadata physical layout), 25 (PE file extensions: CLR header, method bodies).
  • dnlib at commit 9ab9b58ab31b99b3f6cdef36efec613fc11ddbe2: src/DotNet/MD/ImageCor20Header.cs 96-113, MetadataHeader.cs 98-139, StreamHeader.cs 43-83, TablesStream.cs 209-252, DotNetTableSizes.cs 57-104 and 125-405, CodedToken.cs 11-90, CompressedMetadata.cs 36-97, src/DotNet/Emit/MethodBodyReader.cs 357-398 and 449-519, src/IO/DataReader.cs 524-645.
  • dotnet/runtime at commit d80abfc4b04f85722596e8d83af7f9a61dcf49da: src/coreclr/inc/readytorun.h 15-171.
  • Observations (October 2026): Code:.NET metadata (ECMA-335)/dotnetmd (Python) agreed with dnfile (commit bde05f1, with pefile 2024.8.26) on row counts, TypeDef, MethodDef, MemberRef and CustomAttribute rows of 432 assemblies (.NET 10.0.11 shared framework, Windows Desktop 10, .NET Framework 2.0 and 4.8 system assemblies), and parsed all 67630 managed PE files under Program Files, Program Files (x86) and the Windows .NET directory of a Windows 11 machine (Visual Studio 2026, .NET SDK 9 and 10, games and tools) without a table overrunning its stream.