Customize the VS debugger display of your data

As a software developer, I spend much of my time looking at code, learning how it works, and figuring out how to modify or fix it. A very good tool to help examine code is the Visual Studio debugger.

(Even if you’re not a hard core programmer, the following tutorial shows some of the power of the Visual Studio components, such as the project system, build system, debugger, working together.)

At a breakpoint I can examine local variables in the Watch, Auto or Locals window to see their values and types. If it’s a class or structure, the debugger will show a “+” that indicates it can be expanded and the first couple members of that structure. Structures submembers or inherited values can be examined. These structures can get very deep. Sometimes I need to inspect a value that’s dozens of levels down in a hierarchy. That’s a lot of complicated tree navigation in the debugger. Other times I need to take a local variable name (or a member of that variable if it’s a structure/class), drag and drop it to a new line in the Watch Window, then type cast it to a value that’s more meaningful. As I step through code, the variable might go out of scope, or it might have a different name in a subroutine, so I’d have to repeat the typecasting steps in the watch window with the different variable name.

For example, suppose one of the variables is called VBLine and is an internal representation of a line of VB.NET code. It’s much more meaningful to see “Dim MyVar As String”, then a bunch of hex numbers in the debugger. I drag/drop it to the watch window, typecast it to a “DIM” statement, and expand/navigate the results to find “MyVar”. Then, I step into the next called function, with VBLine passed as an argument. The receiving function names the parameter VBStatement, so my watch window drilldown needs to be modified to use the different variable name.

This gets very cumbersome. Let’s improve it!

Here’s a simple demonstration of how you can control what the debugger displays.

Start Visual Studio (2003 or 2005. (It also works in VS7, although the steps might be slightly different.)

Choose File->New->Projects

Choose Visual C++->Win32 Console Application, call it Test

Click Finish on the wizard.

Now paste in some sample code to debug:

#include “windows.h”

int _tmain(int argc, _TCHAR* argv[])

{

OSVERSIONINFOEX osinfo;// Declare a structure

ZeroMemory(&osinfo, sizeof(osinfo));// init it to 0

osinfo.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);// set the size

GetVersionEx((LPOSVERSIONINFO) &osinfo);// call WinAPI to fill it in

WIN32_FIND_DATAFAR ffd;// Declare a structure

FindFirstFile(“c:\\windows\\system32\\k*.exe”,&ffd);// Find the first file starting with “k”

return 0;//set bpt here

}

This sample code just calls the Windows API functions GetVersionEx and FindFirstFile, which fill structures that we can examine in the debugger.

To make things simple, let’s use ANSI rather than Unicode chars (VS2005 defaults to Unicode). Choose Project->Properties->Configuration Properties->General->Character Set and change it to “Use Multi-Byte Character set” rather than “Use Unicode Character Set”

This is a big improvement: we’ve told the debugger which members of the structure to show and how to format them! We can still click on the “+” to drill down the member hierarchy.

When starting a debug session, the debugger reads the AutoExpand file and if the left of the equals matches the type in the Type column of the Locals/Watch/Auto window, then the right side will direct how to format the displayed string. The comments at the beginning of AutoExp.dat give more details, including more formatting options.

This is great, but it’s nothing compared to what we’ll do next!

You can write code that executes in the debugger process that can read the memory of the debugee! AutoExp.dat controls this feature too.

The $ADDIN(DllName,FunctionName) syntax means that the DLL named will be loaded, the FunctionName export in the DLL will be called. (Ignore the gobbledygook: it’s just C++ name decorating indicating the calling convention, the parameters, etc.) If any error occurs, like the DLL can’t be found, the export can’t be found, or the DLL caused an exception, the displayed string will be “{???}”

Now let’s create the project that will build MyDbg.DLL and add it to the current solution.

Choose File->New->Project->Visual C++ Win32 Project, call it MyDbgEE and choose to Add to solution (rather than to Create New Solution).

In the Win32 App Wizard that appears, change the Application Type to a DLL.

Change the project properties as above to non-Unicode and no 64 bit issues.

Now we need to tell VS where to put the built DLL so the debugger can find it. We can use the build events in the project.

For the DLL project, choose Project->Properties->Configuration Properties->Build Events->Post Build Event->Command Line. Put incopy $(TargetPath) “$(DevEnvDir)” Make sure you have the quotes and parentheses right. If you put in a description string, then that string will be echoed to the Output Window when building. Now when you rebuild, the debug dll will be copied to the same dir as Devenv.exe.

Now hit F5 and see the values in the debug window! Bring up Task Manager and notice that the Process ID shown is the same as that of the Devenv.exe debugger process.

To make things more interesting, let’s see how our debug code can read the debugger memory. We’ll add some code to obscure a desired value, but we’ll dig for it in the debug dll. Add this code after the “#include windows.h”line in the main Test code

struct MyClass {// normally this will go in #include file

int mymem1;// make the 1st few members irrelevant, so debugger won’t show interesting info

int mymem2;

int mymem3;

int mymem4;

int mymem5;

short *str;// make this not a string, so debugger won’t show it as a string

MyClass * m_pNextClass;// self referential, perhaps like a linklist

};

Now add this code to just before the “return” statement:

MyClass * pMyClass = new MyClass();// declare a new instance of MyClass

Now hit the F5 button and Bingo! You can still drill down into the class manually as before, so you haven’t lost any functionality.

The debug DLL can be rebuilt even while debugging: it’s loaded/unloaded as needed by the debugger. That means persisting values might be cumbersome. I’ve used custom registry keys for persisting values, like global variables.

I’ve been using this debug expression evaluator architecture for years for huge projects, including Visual Foxpro and Visual Basic.Net, and I find it indispensable and a huge time saver.

Finally!! I’ve been trying for a day to find the magic incantations to make eeaddin work under VS 8. I stumbled across your example and it all worked beautifully the first time.

Thanks so much for that.

Now I need to go to a new level – Unicode. When I convert your sample code and MyDbg to Unicode, it all seems to work except that a string in pResult that might say "Test" gets displayed in the debugger as "T". Obviously, someone is interpreting the second byte of the Unicode "T" as a null terminator, but I can’t figure out where I can control that.

VS7 had a switch in the debugger settings that told the debugger that strings should be displayed as Unicode, but this does not seem to be around or even necessary in VS8.

Do you have any suggestions for improving the performance of this as with real world code, there is a noteable delay when stepping through code?

In a typical session where the type I am interested in debugging is used a lot, sysinternal’s File Monitor showed several tens of thousand accesses to the addin dll when the ‘Locals’ window is open in Visual Studio 2005. This translated into a 3 second delay stepping through the code. What is noticeable is that Visual Studio loads and unloads the dll hundreds of times. This seems rather inefficient to me and perhaps there is a way to force it to stay in memory during a debugging session?

I hard coded the path to the addin dll in autoexp.bat to remove searching for the dll in the path, but it didn’t speed up access. I also cut the code down to a bare minimum in the addin function and this made it no faster. Conclusion: the repetitive loading and unloading of the dll slows the debugging down.

I use this debugging architecture daily on the entire VB, Fox and C# source code (I think these are real-world applications) with no performance problems. I single step through code with many DLL debug expression evaluations (and I have dozens of them: my autoexp.dat is huge!) with no noticeable delay.

How many locals invoke your DLL? Can you get to a point where there is 1 and see how many times the DLL is loaded/unloaded? (Just toggling Hexadecimal display is enough to refresh the display which reloads the DLL)

If you hide the Locals Window, then the DLL won’t be invoked for any expressions in that window.

Are you sure you’re reading the output of FileMon correctly? It can display multiple events per file, such as Open, Cleanup, Close

Try this: put a bpt on some code where there are NO types that would invoke the DLL. Then add a single item in the watch window like this: "(YourCustomType *)0" where YourCustomType would invoke your DLL. How many times is your DLL loaded then? If you add that same item once again, then how many times is it loaded? (I only see one load/close per item)

Try stepping in a function that references the DLL only with one local.

Try making your DLL do nothing but return a simple string.

Did you build it with optimizations? Did you minimize dependencies (like CRT)?

Loading/unloading a DLL is not necessarily slow, with OS caching this is probably not a disk hit.

Try writing some sample standalone C code that just Loads/unloads your DLL in a loop to get a feel for how long it takes to load/unload the DLL "hundreds of times". Does this time approach the 3 seconds delay you’re seeing?

The final two are looking for the .Manifest and .Config file, but the above is basically a sequence of opening the dll to read information about the dll then read the contents (the 5 READ sequences towards the end).

I’m not sure the tool is 100% as the last action is never a close, say when shutting Visual Studio down. In my real life debugging session, there are over 2000 OPENs when the Locals window gets updated. As there are 7 OPENs per variable, there should be 2000/7 = 300 approx of ‘MyType’.

If I hide the Locals window nothing appears in File Monitor – correct.

The other thing I did was rename the addin dll so that visual studio cannot find it. The 3 second delay practically disappeared then, but I had no useful debugging info :(. Simply renaming it back to the correct name gets debugging working again for ‘MyType’.

The timings can also be confirmed as I’ve also loaded and unloaded the dll in a C program and it does takes 3 seconds to load and unload it 300 times (using LoadLibrary() and FreeLibrary() ). So it takes about 0.01ms to load and unload the dll for each instance of ‘MyType’.

I also put the dll on a local drive to make sure there are no network delays. There was no speedup, but as you point out it will be loaded from memory after the first time.

I think the dll is being called many times due to usage of std::vector. If I have a std::vector<MyType> mt and type in mt into the Watch window, the sequence is run once for each element within the vector (up to max of 12 elements). The same is true for std::list, but not for C arrays where just 1 element is shown.

Basically for all your suggestions, the set of sequences is repeated for each instance of ‘MyType’ showing in the debugger. The conclusion is as before… the dll is loaded and read for each variable instance. You’d think it would make more sense to load it once per Watch/Locals window, then the delay would be 0.01ms rather than 3s.

Any other workarounds/suggestions for speeding this up or is this something that the visual studio team can fix?

maybe I’m being very stupid, but I can’t make this work. I’ve put eeaddin.dll in C:Program FilesMicrosoft Visual Studio 8Common7PackagesDebugger and modified autoexp.dat. I don’t see anything but {???} in the local/auto/watch windows. I can interrogate the dll using LoadLibrary and GetProcAddress to find the functions programmatically and using depends and they are exported from the eeaddin.dll.

OK, ReadDebuggeeMemory always seems to return null and doesn’t seem to read the correct number of bytes. Unfortunately since this is entirely undocumented I have no way of know what ReadDebuggeeMemory is meant to return. I guess its kind of telling that Calvin doesn’t do any error checking in his code…

Great article. Trying to use addin to display custom array elements which are stored in heap memory. As soon as I set my array object's pointer to the elements heap address, the ReadDebuggeeMemoryEx call fails to return my array object that contains the heap pointer. Prior to setting the pointer it read it fine. Thanks for any suggestions.