How to Write a Visual Studio Visualizer : CSharp Feeds

How to Write a Visual Studio Visualizer

by Keyvan Nayyeri via Keyvan Nayyeri on 11/1/2006 7:37:57 PM

You already know that visualizers are good tools to debug your code in Visual Studio 2005. Each visualizer works for a specific type and lets you to monitor some specific properties of an instance of classes in a visual manner.

Fortunately there are many built-in visualizers as well as visualizers that are written by community for common types. One of cool and famous visualizers is created by Roy Osherove for Regular Expressions and I had blogged about it before.

But there are some cases when you need to write your own visualizer for your own types. The process is simple and I talk about it in this post by walking through a step by step guide to write a visualizer for Stream type to show the text content of a Stream in a dialog box.

Create a Project for Visualizer

In order to create a visualizer, you need to create a Class Library project and add a Debugger Visualizer item to your project. Debugger Visualizer is an item template which helps you to create a visualizer quicker and easier. When you add a new Debugger Visualizer item to your project, it opens a file with following code in place:

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Windows.Forms;
using Microsoft.VisualStudio.DebuggerVisualizers;
 
namespace SampleVisualizer
{ 
    public class StreamVisualizer : DialogDebuggerVisualizer
    {
        protected override void Show(IDialogVisualizerService windowService, IVisualizerObjectProvider objectProvider)
        {
            // TODO: Get the object to display a visualizer for.
            //       Cast the result of objectProvider.GetObject() 
            //       to the type of the object being visualized.
            object data = (object)objectProvider.GetObject();
 
            // TODO: Display your view of the object.
            //       Replace displayForm with your own custom Form or Control.
            using (Form displayForm = new Form())
            {
                displayForm.Text = data.ToString();
                windowService.ShowDialog(displayForm);
            }
        }
 
        // TODO: Add the following to your testing code to test the visualizer:
        // 
        //    StreamVisualizer.TestShowVisualizer(new SomeType());
        // 
        /// <summary>
        /// Tests the visualizer by hosting it outside of the debugger.
        /// </summary>
        /// <param name="objectToVisualize">The object to display in the visualizer.</param>
        public static void TestShowVisualizer(object objectToVisualize)
        {
            VisualizerDevelopmentHost visualizerHost = new VisualizerDevelopmentHost(objectToVisualize, typeof(StreamVisualizer));
            visualizerHost.ShowVisualizer();
        }
    }
}

As you see visualizers are derived from DialogDebuggerVisualizer which is available in Microsoft.VisualStudio.DebuggerVisualizers.

There are two methods in this class:

Show: The main method to show visualizer to end user. This overridden method has two parameters which lets you to have access to your object's properties.
TestShowVisualizer: This static method is a help method to let you test your visualizer easily.

What you need to develop a visualizer is adding your own logic to Show() method.

Write Your Logic for Visualizer

First step to write your logic is to replace general object type:

// TODO: Get the object to display a visualizer for.
//       Cast the result of objectProvider.GetObject() 
//       to the type of the object being visualized.
object data = (object)objectProvider.GetObject();

with the type you want to monitor. For my example, I must replace it with Stream:

Stream data = (Stream)objectProvider.GetObject();

Second step is to add your logic to retrieve your desire properties from object and show them in a dialog. I show string equivalent of my Stream in a TextBox in a dialog.

using (Form displayForm = new Form())
{
    TextBox textbox = new TextBox();
    textbox.Width = 400;
    textbox.Height = 300;
    textbox.Multiline = true;
    textbox.ScrollBars = ScrollBars.Both;
    displayForm.Controls.Add(textbox);
 
    StreamReader reader = new StreamReader(data);
    textbox.Text = reader.ReadToEnd();
 
    displayForm.Width = 420;
    displayForm.Height = 340;
    displayForm.MaximizeBox = false;
 
    displayForm.Text = data.ToString() + " Visualizer";
    windowService.ShowDialog(displayForm);
}

Test Your Visualizer

TestShowVisualizer static method is a handy method to help you test your visualizer. You can simply call this static method by passing an instance of your object to test your visualizer.

I create a Console Application and a simple text file to test my visualizer. Following simple code is all of what I do to test my visualizer in this Console Application. Don't forget that you must have a reference to Microsoft.VisualStudio.DebuggerVisualizers in order to be able to test your visualizer.

static void Main(string[] args)
{
    Stream stream = new MemoryStream
        (File.ReadAllBytes(@"C:\Documents and Settings\Keyvan Nayyeri\Desktop\MyFile.txt"));
 
    SampleVisualizer.StreamVisualizer.TestShowVisualizer(stream);
}

Once I run this code, can see the content of my text file in a TextBox in a dialog:

Deploy Your Visualizer

Deploying a visualizer is a simple process but there is just an important point: before compiling your Class Library project into an assembly, you must add an assembly attribute to your visualizer code in order to enable this visualizer and map it to a specified type. Below is the code to do this for my visualizer:

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Windows.Forms;
using Microsoft.VisualStudio.DebuggerVisualizers;
using System.IO;
 
[assembly: DebuggerVisualizer(typeof(SampleVisualizer.StreamVisualizer),
    Target = typeof(Stream),
    Description = "Stream Visualizer")]
namespace SampleVisualizer
{ 
    public class StreamVisualizer : DialogDebuggerVisualizer

So this is the final code for my visualizer:

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Windows.Forms;
using Microsoft.VisualStudio.DebuggerVisualizers;
using System.IO;
 
[assembly: DebuggerVisualizer(typeof(SampleVisualizer.StreamVisualizer),
    Target = typeof(Stream),
    Description = "Stream Visualizer")]
namespace SampleVisualizer
{ 
    public class StreamVisualizer : DialogDebuggerVisualizer
    {
        protected override void Show(IDialogVisualizerService windowService, 
            IVisualizerObjectProvider objectProvider)
        {
            Stream data = (Stream)objectProvider.GetObject();
 
            using (Form displayForm = new Form())
            {
                TextBox textbox = new TextBox();
                textbox.Width = 400;
                textbox.Height = 300;
                textbox.Multiline = true;
                textbox.ScrollBars = ScrollBars.Both;
                displayForm.Controls.Add(textbox);
 
                StreamReader reader = new StreamReader(data);
                textbox.Text = reader.ReadToEnd();
 
                displayForm.Width = 420;
                displayForm.Height = 340;
                displayForm.MaximizeBox = false;
 
                displayForm.Text = data.ToString() + " Visualizer";
                windowService.ShowDialog(displayForm);
            }
        } 
 
        public static void TestShowVisualizer(object objectToVisualize)
        {
            VisualizerDevelopmentHost visualizerHost = 
                new VisualizerDevelopmentHost(objectToVisualize, typeof(StreamVisualizer));
            visualizerHost.ShowVisualizer();
        }
    }
}

After adding this attribute, you can compile your visualizer into an assembly and add it to your Visual Studio by copying the DLL file to $\My Documents\Visual Studio 2005\Visualizers (to enable it only for your user) or to $\Microsoft Visual Studio 8\Common7\Packages\Debugger\Visualizers (to enable it for all users on a machine). After restarting your Visual Studio, you'll be able to use this visualizer to debug your code.

Now I remove the call to TestShowVisualizer from my Console Application code and instead, add a new line of code and finally put a Breakpoint on this newly added line:

static void Main(string[] args)
{
    Stream stream = new MemoryStream
        (File.ReadAllBytes(@"C:\Documents and Settings\Keyvan Nayyeri\Desktop\MyFile.txt"));
 
    stream.Flush();
    stream.Close();
    //SampleVisualizer.StreamVisualizer.TestShowVisualizer(stream);
}