Convert Mono PDB Symbols to MDB Files with pdb2mdb

You will convert a Microsoft-format Program Database file associated with a .dll or .exe into the older Mono debugging format, then check that the resulting .mdb file sits beside the assembly. The examples use pdb2mdb from Ubuntu's mono-devel package, version 6.8.0.105+dfsg-3.6ubuntu2.

Allow about ten minutes. You need a shell, a readable managed assembly with its matching .pdb file, and permission to write in that directory. This workflow changes the symbol files in the assembly's directory, but it does not modify the assembly itself. Do not run it against a production directory until you have a backup or a rebuild path.

1. Confirm the installed tool

Check which executable will run and record the package version. These are ordinary read-only commands and do not need elevated privileges:

$ command -v pdb2mdb
/usr/bin/pdb2mdb
$ dpkg-query -W -f='${Package} ${Version}\n' mono-devel
mono-devel 6.8.0.105+dfsg-3.6ubuntu2
$ pdb2mdb --help
Mono pdb to mdb debug symbol store converter
Usage: pdb2mdb assembly

The installed command describes its argument as an assembly, not as a standalone PDB path. Give it the path to the related .dll or .exe. The converter uses the PDB associated with that assembly and writes Mono debugging information next to it.

2. Inspect the assembly and symbol pair

Change to a working copy or build-output directory, then list the files without changing them:

$ cd /path/to/build-output
$ ls -l MyLibrary.dll MyLibrary.pdb
-rw-r--r-- 1 alice alice  9216 Sep 25 10:20 MyLibrary.dll
-rw-r--r-- 1 alice alice  4096 Sep 25 10:20 MyLibrary.pdb

Replace /path/to/build-output and MyLibrary with real values. The names must match the assembly and its PDB. A PDB from a different build can still look plausible while giving misleading line numbers, so keep the pair from one compiler output.

Do not assume that a file ending in .pdb is enough. The manpage describes PDB files as being associated with a library or executable, and the installed program accepts the assembly as its input. If either file is missing or unreadable, fix the build output or permissions first. Do not use sudo as a first response.

3. Preserve the existing MDB file

Before running a conversion, check whether an MDB file already exists:

$ ls -l MyLibrary.dll.mdb
ls: cannot access 'MyLibrary.dll.mdb': No such file or directory

No output file is the simplest case. If the file exists, do not overwrite it blindly. The command is a converter, not a versioned backup system. Make a recoverable copy in the same directory, retaining its metadata:

$ cp --preserve=all -- MyLibrary.dll.mdb MyLibrary.dll.mdb.before-pdb2mdb
$ ls -l MyLibrary.dll.mdb MyLibrary.dll.mdb.before-pdb2mdb

This copy changes the directory, so check the destination before using it and make sure you have enough free space. If the conversion produces an unwanted result, restore the backup only after stopping any process that may be reading the symbols:

$ mv -- MyLibrary.dll.mdb.before-pdb2mdb MyLibrary.dll.mdb

4. Convert the assembly's PDB

Run the converter with the assembly path. This is an ordinary user command when the build directory is writable:

$ pdb2mdb ./MyLibrary.dll
$ printf 'exit status: %s\n' "$?"
exit status: 0

A successful run normally has no progress output. The useful result is the new MDB file alongside the assembly:

$ ls -l MyLibrary.dll MyLibrary.pdb MyLibrary.dll.mdb
-rw-r--r-- 1 alice alice  9216 Sep 25 10:20 MyLibrary.dll
-rw-r--r-- 1 alice alice  4096 Sep 25 10:20 MyLibrary.pdb
-rw-r--r-- 1 alice alice  3584 Sep 25 10:21 MyLibrary.dll.mdb

The exact sizes and timestamps will differ. Check the exit status immediately after the converter, because another command will replace $?. A zero status says the converter completed; it does not prove that the PDB matched the assembly or that every debugger will use the symbols.

5. Check the output and the runtime layout

Confirm that the output is a regular, non-empty file and that it is beside the assembly rather than in a separate symbols directory:

$ test -s MyLibrary.dll.mdb && echo 'MDB file is non-empty'
MDB file is non-empty
$ file MyLibrary.dll.mdb
MyLibrary.dll.mdb: data

The description from the manpage is the key layout rule: Mono debugging information resides side-by-side with the program executable or library. Keep MyLibrary.dll and MyLibrary.dll.mdb together when copying the application to a test machine. Do not rename only one of them.

Now exercise the assembly under the Mono runtime or debugger that needs the symbols. A stack trace with source line numbers is a more useful end-to-end check than relying on the file size. Use the application's normal test command, not a production service, and keep the original PDB until the result is accepted.

6. Diagnose a failed conversion

For a missing or invalid input, the installed wrapper prints its usage and returns a non-zero status:

$ pdb2mdb /tmp/does-not-exist.dll
Mono pdb to mdb debug symbol store converter
Usage: pdb2mdb assembly
$ printf 'exit status: %s\n' "$?"
exit status: 1

Check the exact assembly path, then check both read and write access without changing ownership or permissions:

$ test -r ./MyLibrary.dll && echo 'assembly is readable'
$ test -r ./MyLibrary.pdb && echo 'PDB is readable'
$ test -w . && echo 'directory is writable'

If the directory is not writable, use a writable build copy or have its owner perform the conversion. Avoid running the command as root merely to hide a permissions problem. Elevated privileges can leave root-owned output behind and make the next build fail.

If the command succeeds but the debugger has no line information, first check that the MDB is beside the exact assembly being executed. Then rebuild the assembly and PDB together and rerun the conversion. Do not copy a symbol file from another build based only on matching filenames.