Outline:
- Problem
- Inadequate Solutions
- A Better Way
- Step 1: Create the pdb2xml Database
- Step 2: Query the pdb2xml Database Using the IL Offset
- Step 3: Have Your Application Log the IL Offset
- Download the source code and demo
- Conclusion
----
Problem
Enterprise applications will inevitably throw exceptions. The ideal thing to do with these exceptions is to log them, send the results back to the appropriate developer, and then have that developer fix the code. Part of the problem is that the production (i.e. release-mode) logs are often missing helpful information that developers take for granted in debug mode, like the source file and line number.
Inadequate Solutions
One approach is to just settle and not get the extra info. For easy bugs it is sufficient to just have the callstack (from calling the exception’s ToString method) and some extra arbitrary parameters from a custom logger. But what about the bugs that aren't easy?
Another approach is to just dump the PDB files into your production environment. If you put the PDB (program database) files right next to the corresponding DLLs, then .Net will automatically generate the file and line numbers for you in every exception callstack. Recall that the PDB files contain information to reverse-engineer your code, such that a debugger could step through it. So you almost never want to give those files out to the public. That means this approach only works for applications you host, such as an ASP.Net app. But even still, it could be a security risk, or your IT department or deployment team may have a policy against it.
A Better Way
Looking at these inadequate solutions, it makes us appreciate the ideal solution, which would full the two criteria:
- Provide you the PDB info like file name and line number
- Not require you to ship or deploy the PDB files.
.Net allows you to do this. The “trick” is to get the “IL Offset” and use that to lookup in the PDB files for the exact info you need. Recall that all .Net code gets compiled to Intermediate Language (IL); therefore the IL Offset is just the line number in the IL code. The PDB maps the IL code to your source code. So, this approach has three main steps:
- Create the pdb2xml database, this maps your IL to your source code.
- Query the pdb2xml database using the IL Offset.
- Have your application log the IL Offset.
This approach fulfills our criteria, so let’s explore it in more detail.
Step 1: Create the pdb2xml Database
The PDB files are not plain text, so they’re hard to work with for most people. However, the MSDN debugging team wrote a free tool that lets you convert the PDB files to XML (special thanks to Mike Stall for helping me better understand Pdb2Xml), such that you can easily look up info in them. You can download the “pdb2xml” converter tool from MSDN: http://www.microsoft.com/downloads/details.aspx?familyid=38449a42-6b7a-4e28-80ce-c55645ab1310&displaylang=en
When running the pdb2xml tool, it creates an xml file like so:
<symbols file="TestLoggerApp.Core.dll">
<files>
<file id="1" name="C:\Temp\MyApp.Core\Class1.cs" ... />
<file id="2" name="C:\Temp\MyApp.Core\Class2.cs" ... />
files>
<methods>
<method name="MyApp.Core.Class3.Start3" token="0x6000002">
<sequencepoints total="1">
<entry il_offset="0x4" start_row="17" start_column="7"
end_row="17" end_column="54" file_ref="1" />
sequencepoints>
<locals />
method>
…
This lists all the files, classes, and method involved. Each method can be looked up via the unique token. The
In order to get the exact
- Xml file to lookup at, where each xml file maps to a .Net assembly.
- Method, which we can obtain from the token. The method name is just extra info for convenience.
- IL Offset, which is stored as a hex value.
Because real application usually have many assemblies, ideally we could just point to a bin directory full of pdb files, and have a tool (like an automated build) dynamically generate all the corresponding xml files. We can write a wrapper for pdb2xml to do this.
The biggest issue when writing such a wrapper tool is that pdb2xml, which uses Reflection to dynamically load the assemblies, will get choked up when loading one assembly which contains a class that inherits a class in a different assembly. The easiest way to solve this is to just copy all the targeted assemblies (that you want to generate your xml files for) to the bin of pdb2xml. You could use the ReflectionOnlyAssemblyResolve event to handle resolution errors, but that will provide other problems because you need a physical file, but the event properties only give you the assembly name. While most of the time they’re the same, it will be one more problem to solve when they’re not.
Pdb2xml should handle a variety of cases – assemblies with strong names, third-party references, compiled in release mode, or files that are even several MB big.
ASP.Net applications are a little trickier. Starting with .Net 2.0, ASP allows another compilation model, where every page can get compiled to its own DLL. The easiest way to collect all these DLLs is to run the aspnet_compiler.exe tool, which outputs all the assemblies (and PDBs) to the web’s bin directory. You can read about the aspnet_compiler here: http://msdn.microsoft.com/en-us/library/ms229863(VS.80).aspx, or its MSBuild task equivalent: http://msdn.microsoft.com/en-us/library/ms164291.aspx.
Note that when using the aspnet_compiler, you need to include the debug ‘-d’ switch in order to generate the PDB files. A sample call (ignoring the line breaks) could look like:
aspnet_compiler.exe
-v /my_virtualDir
-p C:\Projects\MyWeb\
-f
-d
-fixednames C:\Projects\precompiledweb\MyWeb\
For convenience, I’ve attached a sample tool - PdbHelper.Cmd.Test (from the download) which will mass-generate these xml files for you. This solves the first step – converting the pdb files to an xml format that we can then query. You can now put those xml files anywhere you want, such as on a shared developer machine.
Step 2: Query the pdb2xml Database Using the IL Offset
Given an xml data island, we can easily query that data. The only thing we need is a key. In this case, we can have the application’s logger generate an xml snippet which some tool or process can then scan for and use it to lookup in the pdb2xml database. Let’s say that our logger gave us the following xml snippet (we’ll discuss how in the next step):
<ILExceptionData>
<Point module='TestLoggerApp.Core.dll' classFull='TestLoggerApp.Core.Class2'
methodName='Start2' methodSignature='Int32 Start2(System.String, Boolean)'
methodToken='0x6000005' ILOffset='11' />
...
ILExceptionData>
For each line in the stack trace, our this XML snippet contains a
- module – the .Net module, which directly maps to an xml file.
- methodToken – the token, which uniquely identifies the method
- ILOffset – The line, in IL, that threw the exception. Our logger wrote this as decimal, but we can easily convert it to hex.
These values are just included for convenience:
- classFull – the full, namespace-qualified, name of the class
- methodName – the actual method’s name
- methodSignature – the signature, to help troubleshoot overloaded methods
Given this xml snippet, we can have any tool or process consume it. In this case, I wrote a sample WinForm app (PdbHelper.Gui, from the Download) that takes a directory to the pdb2xml database, as well as the Xml Snippet, and performs the lookup. The logic is straightforward, perhaps the only catch is the IL Offset is not always exact; therefore if there is no exact match in the pdb2xml file, round down – i.e. find the previous entry node.
So, the developer could run this app, and it returns the file, line, and column.
While this is a manual GUI app, the logic could be automate for a console app, or other process.
Step 3: Have Your Application Log the IL Offset
The last step is to generate the Xml snippet. Given any Exception, you can use the System.Diagnostics.StackTrace object to determine the IL Offset, method, and module. You first need to create a new StackTrace object using the current Exception. You can then cycle through each StackFrame, getting the relevant data. This logic could be abstracted to its own assembly such that you could easily re-use it across all your applications.
public static string CreateXmlLog(Exception ex)
{
try
{
//Get offset:
System.Diagnostics.StackTrace st = new System.Diagnostics.StackTrace(ex, true);
System.Diagnostics.StackFrame[] asf = st.GetFrames();
StringBuilder sb = new StringBuilder();
sb.Append("
int[] aint = new int[asf.Length];
for (int i = 0; i < aint.Length; i++)
{
System.Diagnostics.StackFrame sf = asf[i];
sb.Append(string.Format("
sf.GetMethod().Name, sf.GetILOffset(), sf.GetMethod().Module, sf.GetMethod().ReflectedType.FullName,
sf.GetMethod().ToString(), GetILHexLookup(sf.GetMethod().MetadataToken)));
}
sb.Append("\r\n");
return sb.ToString();
}
catch (Exception ex2)
{
return "Error in creating ILExceptionData: " + ex2.ToString();
}
}
private static string GetILHexLookup(int intILOffsetDec)
{
return "0x" + intILOffsetDec.ToString("X").ToLower();
}
Download the source code and demo
You can download the complete source code, and an automated demo here.
The package has the following folders:
- BuildScripts - automated scripts to run everything. This is useful if you wan to integrate the PdbHelper into your own processes.
- mdbg - the pdb2xml application, with the compiled binaries. This was downloaded from MSDN.
- PdbHelper.Cmd.Test - the command line tool to create all the xml files from pdb (this wraps the MSDN pdb2xml code)
- PdbHelper.Core - reusable logic that the command line and GUI both use.
- PdbHelper.Gui - the windows GUI to easily look up debugging info in the pdb-generated xml files.
- PdbHelper.Logger - a reusable logger component that takes in an Exception and returns an xml snippet containing the IL offset.
- TestLoggerApp - a test application to demonstrate all this.
There's not much code to all of this, so you could just reverse engineer it all. But to make it easy, go to the BuildScripts folder and you're see 4 bat files, numbered in order:
- 0_DeleteBins.bat - cleans up things to "reset" everything (delete bin and obj folders). This is optional, but useful when developing.
- 1_CompileFramework.bat - compile the PdbHelper framework (you could just open the solution in VS)
- 2_RunTestApp.bat - runs the test console app, whose whole purpose is to throw an exception, display the IL offset xml snippet, and then write it out to a file for easy use.
- 3_LookupException.bat - Run the windows GUI app. This passes in command line arguments to automatically populate the xml directory and the IL offset snippet generated in the previous step. You just need to click the "Lookup" button, and it should show you the debug info.
Several of these scripts call MSBuild to run certain tasks. Also, by default, this dumps the pdb2xml files in C:\Temp\pdb2xml.
Conclusion
Using these three steps allows an application to log additional info, from which we can then query the pdb files to find the source file and line number. This extra info can be very useful when debugging, helping to reduce the total cost of ownership.
