Walkthrough: Writing a Visualizer

Article
11/03/2006

This topic applies to:

Visual Studio Edition	Visual Basic	C#	C++	J#
Express	No	Yes	No	No
Standard	No	Yes	No	No
Pro/Team	No	Yes	No	No

This walkthrough shows how to write a simple visualizer using C#. The visualizer you will create in this walkthrough displays the contents of a string using a Windows forms message box. This simple string visualizer is not terribly useful in itself, but it shows the basic steps you must follow to create more useful visualizers for other data types.

Note
The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Visual Studio Settings.

Visualizer code must be placed in a DLL, which will be read by the debugger. So, the first step is to create a Class Library project for the DLL.

Create a Class Library Project

From the File menu, choose New and click New Project.
In the New Project dialog box, under Project Types, select Visual C#.
In the Templates box, choose Class Library.
In the Name box, give the class library an appropriate name, such as MyFirstVisualizer.
Click OK.

Once you have created the class library, you must add a reference to Microsoft.VisualStudio.DebuggerVisualizers.DLL, so that you can use the classes defined there. First, though, you will do a little renaming, just so things have meaningful names.

Rename Class1.cs and Add Microsoft.VisualStudio.DebuggerVisualizers

In Solution Explorer, right-click on Class1.cs and choose Rename from the context menu.
Edit the name from Class1.cs to something appropriate, like DebuggerSide.cs.

Notice that Visual Studio automatically changes the class declaration in DebuggerSide.cs to match the new file name.
In Solution Explorer, right-click on References and choose Add Reference from the context menu.
In the Add Reference dialog box, on the .NET tab, choose Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Click OK.
In DebuggerSide.cs, add the following statement to the using statements:
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

Now, you're ready to create the debugger-side code. This is the code that runs within the debugger to display the information you want to visualize. First, you need to change the declaration of the DebuggerSide object so that inherits from the base class DialogDebuggerVisualizer.

Inherit from DialogDebuggerVisualizer

In DebuggerSide.cs, go to the following line of code:
```
public class DebuggerSide
```

Edit the code to:

public class DebuggerSide : DialogDebuggerVisualizer

DialogDebuggerVisualizer has one abstract method (Show) that you must override.

Override the DialogDebuggerVisualizer.Show method

In public class DebuggerSide, add the following method:

override protected void Show(IDialogVisualizerService windowService, IVisualizerObjectProvider objectProvider)
{
}

The Show method contains the code that actually creates the visualizer dialog box (or other user interface) and displays the information that has been passed to the visualizer from the debugger. You must add the code that creates the dialog box and displays the information. In this walkthrough, you will do this using a Windows forms message box. First, you must add a reference and using statement for System.Windows.Forms.

Add System.Windows.Forms

In Solution Explorer, right-click on References and choose Add Reference from the context menu.
In the Add Reference dialog box, on the .NET tab, choose System.Windows.Forms.DLL.
Click OK.
In DebuggerSide.cs, add the following statement to the using statements:
```
using System.Windows.Forms;
```

Now, you will add some code to create and show the user interface for your visualizer. Because this is your first visualizer, we will keep the user interface simple and use a Message Box.

Show the Visualizer Output in a Dialog Box

In the Show method, add the following line of code:
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
This example code does not include error handling, which you ought to include in a real visualizer (or any other sort of application).
From the Build menu, choose Build MyFirstVisualizer. The project should build successfully. Correct any build errors before continuing

That's the end of the debugger side code. There is one more thing to add, however: The attribute that tells the debuggee side which collection of classes makes up the visualizer.

Add the Debuggee-Side Code

Add the following attribute code to DebuggerSide.cs, after the using statements but before namespace MyFirstVisualizer:

[assembly:System.Diagnostics.DebuggerVisualizer(
typeof(MyFirstVisualizer.DebuggerSide),
typeof(VisualizerObjectSource),
Target  = typeof(System.String),
Description  = "My First Visualizer")]

From the Build menu, choose Build MyFirstVisualizer. The project should build successfully. Correct any build errors before continuing.

At this point, your first visualizer is done. If you have followed the steps correctly, you should be able to build the visualizer and install it into Visual Studio. Before you install a visualizer into Visual Studio, however, you should test it to make sure it runs correctly. You will now create a test harness to run the visualizer without installing it into Visual Studio.

Add a Test Method to Show the Visualizer

Add the following method to class public DebuggerSide():

public static void TestShowVisualizer(object objectToVisualize)
{
   VisualizerDevelopmentHost visualizerHost = new VisualizerDevelopmentHost(objectToVisualize, typeof(DebuggerSide));
   visualizerHost.ShowVisualizer();
}

From the Build menu, choose Build MyFirstVisualizer. The project should build successfully. Correct any build errors before continuing

Next, you must create an executable project to call your visualizer DLL. For simplicity, we will use a Console Application project.

Add a Console Application Project to the Solution

From the File menu, choose Add and click New Project.
In the Add New Project dialog box, Templates box, choose Console Application.
In the Name box, give the console application a meaningful name, such as MyTestConsole.
Click OK.

Now, you must add the necessary references so MyTestConsole can call MyFirstVisualizer.

Add Necessary References to MyTestConsole

In Solution Explorer, right-click on MyTestConsole and choose Add Reference from the shortcut menu.
In the Add Reference dialog box, .NET tab, choose Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Click OK.
Right-click on MyTestConsole and choose Add Reference again.
In the Add Reference dialog box, click on the Projects tab and select MyFirstVisualizer.
Click OK..

Now, you will add the code to finish the test harness.

Add Code to MyTestConsole

In Solution Explorer, right-click on Program.cs and choose Rename from the context menu.
Edit the name from Program.cs to something appropriate, like TestConsole.cs.

Notice that Visual Studio automatically changes the class declaration in TestConsole.cs to match the new file name.
In TestConsole.cs, add the following to the using statements:
```
using MyFirstVisualizer;
```

In method Main, add the following code:

String myString = "Hello, World";
DebuggerSide.TestShowVisualizer(myString);

Now, you are ready to test your first visualizer.

Test the Visualizer

In Solution Explorer, right-click on MyTestConsole and choose Set as Startup Project from the shortcut menu.
From the Debug menu, choose Start.

The console application starts. After a moment, the Visualizer appears, displaying the string "Hello, World."

Congratulations. You have just built and tested your first visualizer.

If you wanted to user your visualizer in Visual Studio rather than simply calling it from the test harness, you would need to install it. (For details, see How to: Install a Visualizer.)

Using the Visualizer Item Template

So far, this Walkthrough has shown you how to create a visualizer manually. This was done as a learning exercise. Now that you know how a simple visualizer works, there is an easier way to create one: using the visualizer item template.

First, you need to create a new class library project.

Create a New Class Library

From the File menu, choose Add and click New Project.
In the Add New Project dialog box, under Project Types, select Visual C#.
In the Templates box, choose Class Library.
In the Name box, give the class library an appropriate name, such as MySecondVisualizer.
Click OK.

Now, you can add a visualizer item to it:

Add a Visualizer Item

In Solution Explorer, right-click on MySecondVisualizer.
From the shortcut menu, choose Add and click New Item.
In the Add New Item dialog box, under Templates, Visual Studio Installed Templates, select Debugger Visualizer.
In the Name box, enter an appropriate name, such as SecondVisualizer.cs.
Click Add.

That's all there is to it. Take a look at the file SecondVisualizer.cs and see code the template added for you. Go ahead and experiment with the code. Now that you know the basics, you are on your way to creating more complex and useful visualizers of your own.

Share via