.PDB File Format

Introduction

A portable PDB holds the debug information of a .NET assembly: for each method the source files and the sequence points that map IL offsets to lines, the local variables and constants with their scopes, the namespaces imported at each point, the state machines the compiler made for async and iterator methods, and custom information such as SourceLink. The .NET SDK writes one beside each assembly, or embeds it in the assembly (DebugType embedded). It is a separate format from the Windows PDB, which is a file system of numbered streams (MSF) and shares only the extension. A portable PDB has the same layout as .NET metadata: a root with the signature BSJB, streams, and tables.

The assembly and its PDB are matched by an ID: the PDB ID in the #Pdb stream (a GUID and a stamp) is stored in the assembly’s debug directory, so a debugger can pick the right file.

Structure

What the explorer shows

A file that starts with BSJB opens as a portable PDB (a .pdb starting Microsoft C/C++ MSF 7.00 is a Windows PDB and is named so). The tree shows the root, the streams, the PDB ID and the entry point, every row of every debug table with its columns decoded (documents, scopes, variable names), and the heaps. The problems list reports the same structure faults as for an assembly. An assembly built with an embedded PDB keeps a compressed copy of one in its debug directory; that copy is not unpacked yet.

The explorer’s reading was compared with Microsoft’s System.Reflection.Metadata field by field on the portable PDBs written by the C#, F# and Visual Basic compilers (see the .NET assembly page for the numbers).

Other formats that use .pdb

The portable PDB is a different format from the Windows PDB: they share only the extension.

• Microsoft program database (MSF) – the Windows PDB of C and C++ programs: numbered streams in an MSF container, a different format that also uses .pdb

Not described

Known, not yet covered

• Reference: the encodings inside the blobs: sequence points (compressed deltas), the Document name, import scope blobs, and the custom debug information kinds (SourceLink JSON, embedded source with its compression, state machine hoisted locals, edit-and-continue maps). They are in the portable PDB specification and are the next work (see the debug tables).
• Viewer: those blobs show as bytes; the debug directory entries of an assembly (including a compressed embedded PDB) are not read.

Also used for

• Microsoft program database – Debug symbols for Windows programs, in numbered streams.

Links