Debug Visualizers and the XNA Framework

  • Article

Debugging visualizers are a cool feature of Visual Studio 2005 available to C# developers. I’d like to show you how to add some simple debugger visualizers to the Beta version of the XNA Framework.

 

You can find general information about debugger visualizers through the following links:

For those of you not familiar with debugger visualizers, they essentially allow you to customize how the debugger shows variables while debugging. Many of you are familiar with the current debugger display of “Name”, “Value” and “Type” columns in the various debugger windows (Locals, Watch, Autos etc). Debugger visualizers allows you to customize the value column to be more useful when debugging. One of the best attributes of debugger visualizers is that you can customize existing types (ones that you don’t have the source code to) which can make your debugging simpler and more relevant to you. Chances are that you are using a debugger visualizer and you don’t even realize it!

 

The best way to show something is by example so let’s add some visualizers to a type in the Beta version of the XNA Framework.

 

The view today

 

Let’s look at the current debug view for an existing type today. Create a new “Windows Game (XNA)” project. Set a breakpoint at the end of the Draw method, it should look something like this:

 

 

Debug the game (hit F5) and you should hit the breakpoint. Open the Locals window and expand the “this“ variable. You should see the following information:

 

 

 

Right now the default value for the graphics member of the Game type is simply the type of the variable, not particularly interesting. Note that if you expand the graphics node you can see it’s members and suddenly the information is very relevant:

 

 

 

Let’s create a debug visualizer that shows some of the expanded information about the GraphicsComponent without having to expand the graphics object.

 

Creating a Debugger Visualizer

 

1. Open a new instance of C# Express.

2. Create a new project using the “Windows Game Library (XNA)” project template. Although you can call this project anything, I recommend calling the DLL something like “MyDebuggerVisualizers”

3. Change the generated source code for Class1.cs to have the following code:

 

using System;

using System.Diagnostocs;

 

[assembly: DebuggerDisplay(@"IsFullScreen = {IsFullScreen}",

Target = typeof(Microsoft.Xna.Framework.Components.GraphicsComponent))]

This code looks more complicated than it is. The first two using statements (System and System.Diagnostics) brings in the Debugger Visualizer attributes – in this case we are using only DebuggerDisplay.

The DebuggerDisplay attribute provides the basic functionality for customizing the value. The first parameter is the string that we want to display when the debugger shows a variable of this type. In the example above we simply list one of the properties of the GraphicsComponent – IsFullScreen. You specify that you want the debugger to evaluate a property on the current object by putting the property between the pair of brackets – “{IsFullScreen}” in the example above. Once you have specified the display string, you attach this debugger visualizer to the type you want by using the Target property.

4. Once you have this code in place, compile the project. This will result in a DLL being generated.

 

5. In order for the debugger to use the visualizer you just created, you need to put the DLL in a well known place. The debugger looks in several places, but the easiest place to put the DLL is in your “My Documents” folder inside “My Documents\Visual Studio 2005\Visualizers”. Visual Studio created this directory when it installed and you might notice that it already contains some DLL’s and their relevant source code. You need to copy the DLL you just created to this directory and while you could do it manually, it might be better to simply use a Project Post Build Event to do this automatically.

 

6. Select the project and right click to bring up the project properties. Click the “Build Events” tab and you will see a page that looks like this:

 

 

In the post-build event command line section you want to add a command to copy the DLL to the directory specified above. Luckily you can use the macros inside the Post Build events to make this simple. Select the “Edit Post-build” button to get to the editor for post build rules. You will see the following dialog (click the Macros button to see the Macro values you can use):

 

 

In the top field add the following command:

copy "$(TargetPath)" "C:\Documents and Settings\ <YourName> \My Documents\Visual Studio 2005\Visualizers"

7. Build the project. This should build the project and copy the DLL to the Visualizer directory so the debugger can now pick up your visualizer.

The new view

Go back to the project with the Game Application in it and restart a debugging session. Now when you hit the breakpoint and expand the “this” variable you should see:

 

 

The debugger now uses the visualizers that you specified for this type. Note that you don’t have to close down C# Express to test new visualizers, the debugger will detect that a new visualizer is available between debugging sessions. Typically when I am working on visualizers I have two versions of C# Express open, one for the debugger visualizer DLL and one for my “real” code. Once I see something I want to change, I simply add a new attribute in the debugger visualizer project, rebuild the project (which copies the DLL) and then start a new debug session in the other C# Express. It’s a very effective way to make your debugging more productive.

Summing Up

Debugger Visualizers are a cool new feature of VS 2005. The DebuggerDisplay attribute can be used to quickly and easily display values inside the debugger, with the best part being that you can add them to existing types. There are more advanced debugger attributes available – we’ve just scratched the surface! BTW check out the existing debugger visualizers in your “My Documents” folder – there might be some good examples you can apply somewhere else.

Let us know what you think of this feature and what your favorite visualizers are for the XNA Framework.

Thanks

 

Joe Nalewabau

XNA Shaman

 

PS This really cool feature was added by the debugger team and the C# team in Visual Studio 2005. While I worked closely with the relevant teams on this feature, the main people that pushed the feature and the implementation through were Anson Horton, Mike Montwill, Scott Nonnenberg, Luke Hoban and Jim Griesmer on the C# and Debugger teams. I think they did a great job – thanks again guys!