Debug symbols

jbevain edited this page Apr 4, 2011 · 4 revisions

Cecil support of debug symbols lives in two assemblies: Mono.Cecil.Pdb.dll and Mono.Cecil.Mdb.dll. They are used to read and write symbol store files for .net, the pdb files, and for Mono, the mdb files.

  • Mono.Cecil.Mdb is a purely managed assembly that will work on both .net and Mono, on any platform.
  • Mono.Cecil.Pdb has a managed pdb reader, but a writer that uses COM interop. It means that you can use it to read pdb symbols everywhere, but that you need to run on windows to emit pdb files. The managed reader uses code from the CCI project.

From an API standpoint, there are two ways of interacting with debug symbols. The easiest is to simply pass `True` to ReaderParameters.ReadSymbols or WriterParameters.WriteSymbols. Cecil will try to load the debug store support assembly depending on the runtime (pdb on .net, mdb on Mono) and read and write the appropriate symbols.

The following example shows how to read and write an assembly with symbol file being rewritten.

var readerParameters = new ReaderParameters { ReadSymbols = true };
var assemblyDefinition = AssemblyDefinition.ReadAssembly (fileName, readerParameters);

// make required changes.

var writerParameters = new WriterParameters { WriteSymbols = true };
assemblyDefinition.Write (outputFile, writerParameters);

If you need more control, you can specify ReaderParameters.SymbolReaderProvider and WriterParameters.SymbolWriterProvider. Those interfaces control respectively the creation of a Mono.Cecil.Cil.ISymbolReader and a Mono.Cecil.Cil.ISymbolWriter specific to the module.