Debug Visualizers and the XNA Framework

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:

• https://msdn.microsoft.com/msdnmag/issues/04/05/VisualStudio2005Debugging/
• https://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvs05/html/simplevisualizercreation.asp
• https://channel9.msdn.com/showpost.aspx?postid=164928

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!

Comments

• Anonymous
  September 08, 2006
  PingBack from http://www.gamedevnews.com/?p=122

• Anonymous
  September 10, 2006
  I assume that debug visualizers are much more powerful than what was shown here. I don't know. This is the first time I read about them but I will just fire away anyway risking looking stupid.
  
  I have two problems with this blog entry:
  
  1. I don't understand why I should do everything described here instead of going to the watch-view in the debugger and add "graphics.IsFullScreen".
  
  2. "This code looks more complicated than it is" is quite right. The code looks complicated and it does something simple from the user's point of view and that's exactly the problem. Code should look as simple as possible. Is there a need for three kinds of brackets in one and a half lines of code?
  
  Since this is my first post, I also wanted to add that I think it's great that Microsoft wants to simplify game development and make it more attractive. So far it looks pretty good. I am also looking forward to programming the Xbox.
  
  I am programming for a few years now but haven't bothered really learning DirectX because I needed a week to learn and understand setting up a DirectX window as opposed to copying 6 "glut" lines from the OpenGL Red Book to initialize an OpenGL window. I also hate the Hungarian notation. It makes code unreadable.

• Anonymous
  September 10, 2006
  Pasco,
  
  You are right in that there is a lot more to debugger visualizers - this is just the simple part.
  
  As to your points:
  
  1. Yes you could indeed type in graphics.IsFullScreen and get the same effect. Of course in order for this to work every time you would need to change the variable name every time is was different. You would also have to always have the watch window visible as you don't get to see this view in the other debugger windows (autos, locals etc).
  
  2. I can understand your confusion with the brackets. Attributes are a very powerful mechanism and their syntax can take some getting used to.
  
  One of the reasons that I like really this simple level of customization is that it gives you the power to describe how you want to look at data in the debugger. There are not many systems out there, that allow you to control how you want to view something in the debugger to the degree that Visual Studio 2005 allows you.
  
  Thanks
  
  Joe

• Anonymous
  September 12, 2006
  Thanks for clarifying. I'll have to dig into it when I have a little more time.
  
  Paschalis Armoutsis

• Anonymous
  September 12, 2006
  PingBack from http://www.xnatutorial.com/?p=5

• Anonymous
  September 14, 2006
  While working with Joe to get his entry on the XNA Team Blog, we kept wanting an easier way to do it....

• Anonymous
  October 04, 2006
  While working with Joe to get his entry on the XNA Team Blog , we kept wanting an easier way to do it.

• Anonymous
  March 07, 2009
  While working with Joe to get his entry on the XNA Team Blog , we kept wanting an easier way to do it. No worrying about copying and pasting text, uploading images, previewing. Just type something up and post it. Apparently our answer has been out there

• Anonymous
  June 16, 2009
  PingBack from http://lowcostcarinsurances.info/story.php?id=1055