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:Portable PDB

From ReverseEngineering.wiki
Format
Developer Microsoft (.NET Foundation), 2015-
Magic 42 53 4A 42 ("BSJB") at 0, version string "PDB v1.0"; embedded: 4D 50 44 42 ("MPDB")
Extensions .pdb
Endianness little
On this wiki Facts · Code · Notes · Topics

The cross-platform debug symbol format of .NET (Roslyn, .NET Core and later; spec v1.0): a standalone Format:.NET metadata (ECMA-335) image whose root has the version string "PDB v1.0", a #Pdb stream (20-byte PDB id, entry point, row counts of the referenced type-system tables) and the tables 0x30-0x37 (documents, sequence points, local scopes, variables, constants, imports, state machines, custom debug info). It replaces the Windows MSF-based Format:PDB (Program Database) for managed code and is often embedded in the PE, deflate-compressed, as debug directory entry type 17.

Identification

  • A file starting with 42 53 4A 42 ("BSJB") is metadata, not a Windows PDB (Microsoft C/C++ MSF 7.00\r\n\x1aDS). The root's version string is PDB v1.0 and the stream list contains #Pdb and #~, usually also #Strings, #US, #GUID, #Blob (their own heaps, not those of the assembly).
  • In the PE, a CodeView debug entry (type 2, RSDS) whose MinorVersion is 0x504D ("PM") refers to a Portable PDB; MajorVersion is the Portable PDB version (0x0100), the Age is 1 (Fact:Portable PDB/identification/Portable CodeView entry). A Windows-PDB CodeView entry has minor version 0. ReadyToRun assemblies can carry both: a Windows PDB <name>.ni.pdb for the native code and a portable <name>.pdb for IL.
  • Debug entry type 17 is an embedded Portable PDB: "MPDB", uint32 uncompressed size, then the PDB compressed with raw DEFLATE (no zlib header); Fact:Portable PDB/struct/Embedded Portable PDB blob. Type 19 is a PDB checksum: a NUL-terminated algorithm name (SHA256) and the hash. See also Format:PE (Portable Executable)/Debug directory.

#Pdb stream

Offset Size Field
0 20 PDB id: 16-byte GUID + 4-byte stamp, equal to the CodeView entry's GUID and TimeDateStamp
20 4 EntryPoint MethodDef token (same as the CLR header), or 0
24 8 ReferencedTypeSystemTables: bit mask of type-system tables (0x00-0x2C) of the assembly
32 4 x popcount TypeSystemTableRows: row count of each referenced table, in table-id order

Column widths of the PDB's own tables are computed with the normal rules (Fact:.NET metadata (ECMA-335)/behavior/Column widths), except that indexes into type-system tables (e.g. LocalScope.Method, StateMachineMethod) use the row counts from TypeSystemTableRows, because those tables live in the assembly, not in the PDB. Layout fact: Fact:Portable PDB/struct/Pdb stream.

Debug tables

Id Table Contents
0x30 Document Name (blob: separator char + list of blob indexes of UTF-8 path parts), HashAlgorithm GUID, Hash, Language GUID
0x31 MethodDebugInformation one row per MethodDef (same row number): Document, SequencePoints blob (IL offset to line/column deltas)
0x32 LocalScope Method, ImportScope, VariableList, ConstantList, StartOffset, Length
0x33 LocalVariable Attributes (1 = debugger hidden), slot Index, Name
0x34 LocalConstant Name, Signature (type + value)
0x35 ImportScope Parent, Imports blob (using directives)
0x36 StateMachineMethod MoveNext method to kickoff (async/iterator source) method
0x37 CustomDebugInformation Parent (HasCustomDebugInformation coded index), Kind GUID, Value: Source Link JSON, embedded source, compilation options and references, EnC maps, dynamic locals, tuple names

MethodDebugInformation is indexed by MethodDef row, so sequence points give source lines for an IL offset; StateMachineMethod maps compiler-generated <Foo>d__5.MoveNext back to the async method Foo. CustomDebugInformation with the "Compilation Options" kind holds the compiler version, language version, optimisation level and define symbols of a Roslyn build, and "Compilation Metadata References" lists every referenced assembly with its MVID, enough to reproduce the build.

PDB id and checksum

The checksum (type 19) is computed over the whole PDB with the 20 PDB-id bytes set to zero, and in deterministic builds the PDB id itself is derived from that hash (Fact:Portable PDB/behavior/PDB id derived from the checksum). So a PDB found on a symbol server or in a NuGet symbol package can be matched to a DLL from the DLL alone: compare the CodeView GUID + stamp with the #Pdb id, or the type-19 hash with SHA-256 of the PDB with its id zeroed. Unverified: symbol servers index Portable PDBs under <name>.pdb/<GUID as 32 hex digits>FFFFFFFF/<name>.pdb (age replaced by FFFFFFFF); check against dotnet-symbol or symchk output.

Tools

  • Code:.NET metadata (ECMA-335)/dotnetmd (Python) lists the debug entries of a PE, extracts an embedded PDB (--pdb out.pdb) and parses a standalone PDB (streams, #Pdb fields, row counts of the debug tables).
  • System.Reflection.Metadata MetadataReaderProvider.FromPortablePdbStream, dnlib SymbolReaderFactory, ILSpy (shows sequence points and can generate PDBs), dotnet-symbol (downloads PDBs), Pdb2Pdb / symreader-converter (converts between Windows and Portable PDB).

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

Evidence & references

  • dotnet/runtime at commit d80abfc4b04f85722596e8d83af7f9a61dcf49da: docs/design/specs/PortablePdb-Metadata.md (format, #Pdb stream lines 33-52, tables 0x30-0x37), docs/design/specs/PE-COFF.md lines 15-106 (CodeView 0x504D entry, embedded PDB type 17, checksum type 19 and how it is computed).
  • dnlib at commit 9ab9b58ab31b99b3f6cdef36efec613fc11ddbe2: src/DotNet/MD/PdbStream.cs 31-44, src/DotNet/Pdb/Portable/SymbolReaderFactory.cs 49-89 (MPDB reader), src/DotNet/Writer/PortablePdbConstants.cs line 19 (0x504D).
  • Observed (October 2026) on the .NET SDK 10.0.400 and shared-framework files installed on a Windows 11 machine: 1867 assemblies with a portable CodeView entry (all with age 1); 61 embedded PDBs that inflate to the stated size, whose #Pdb id equals the CodeView GUID + stamp and whose SHA-256 with the id zeroed equals the type-19 checksum.