Format:Portable PDB
| 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 isPDB v1.0and the stream list contains#Pdband#~, 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.pdbfor the native code and a portable<name>.pdbfor IL. - Debug entry type 17 is an embedded Portable PDB:
"MPDB",uint32uncompressed 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, dnlibSymbolReaderFactory, 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.mdlines 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.cs31-44,src/DotNet/Pdb/Portable/SymbolReaderFactory.cs49-89 (MPDB reader),src/DotNet/Writer/PortablePdbConstants.csline 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.