Create custom data visualizers

A visualizer is part of the Visual Studio debugger user interface that displays a variable or object in a manner appropriate to its data type. For example, an HTML visualizer interprets an HTML string and displays the result as it would appear in a browser window. A bitmap visualizer interprets a bitmap structure and displays the graphic it represents. Some visualizers let you modify as well as view the data.

The Visual Studio debugger includes six standard visualizers. The text, HTML, XML, and JSON visualizers work on string objects. The WPF Tree visualizer displays the properties of a WPF object visual tree. The dataset visualizer works for DataSet, DataView, and DataTable objects.

More visualizers may be available for download from Microsoft, third parties, and the community. You can also write your own visualizers and install them in the Visual Studio debugger.

In the debugger, a visualizer is represented by a magnifying glass icon VisualizerIcon. You can select the icon in a DataTip, debugger Watch window, or QuickWatch dialog box, and then select the appropriate visualizer for the corresponding object.

Write custom visualizers

Note

To create a custom visualizer for native code, see the SQLite native Debugger Visualizer sample. Custom visualizers are not supported for UWP and Windows 8.x apps.

You can write a custom visualizer for an object of any managed class except for Object and Array.

The architecture of a debugger visualizer has two parts:

  • The debugger side runs within the Visual Studio debugger, and creates and displays the visualizer user interface.

  • The debuggee side runs within the process Visual Studio is debugging (the debuggee). The data object to visualize (for example, a String object) exists in the debuggee process. The debuggee side sends the object to the debugger side, which displays it in the user interface you create.

The debugger side receives the data object from an object provider that implements the IVisualizerObjectProvider interface. The debuggee side sends the object through the object source, which is derived from VisualizerObjectSource.

The object provider can also send data back to the object source, which lets you write a visualizer that can edit data. You override the object provider to talk to the expression evaluator and the object source.

The debuggee side and debugger side communicate with each other through Stream methods that serialize a data object into a Stream and deserialize the Stream back into a data object.

You can write a visualizer for a generic type only if the type is an open type. This restriction is the same as the restriction when using the DebuggerTypeProxy attribute. For details, see Use the DebuggerTypeProxy attribute.

Custom visualizers may have security considerations. See Visualizer security considerations.

The following steps give a high-level overview of visualizer creation. For detailed instructions, see Walkthrough: Write a visualizer in C# or Walkthrough: Write a visualizer in Visual Basic.

To create the debugger side

To create the visualizer user interface on the debugger side, you create a class that inherits from DialogDebuggerVisualizer, and override the DialogDebuggerVisualizer.Show method to display the interface. You can use IDialogVisualizerService to display Windows forms, dialogs, and controls in your visualizer.

  1. Use IVisualizerObjectProvider methods to get the visualized object on the debugger side.

  2. Create a class that inherits from DialogDebuggerVisualizer.

  3. Override the DialogDebuggerVisualizer.Show method to display your interface. Use IDialogVisualizerService methods to display Windows forms, dialogs, and controls in your interface.

  4. Apply DebuggerVisualizerAttribute, giving it the visualizer to display (DialogDebuggerVisualizer).

To create the debuggee side

You specify debuggee-side code by using the DebuggerVisualizerAttribute.

  1. Apply DebuggerVisualizerAttribute, giving it a visualizer (DialogDebuggerVisualizer) and an object source (VisualizerObjectSource). If you omit the object source, the visualizer will use a default object source.

  2. To let the visualizer edit as well as display data objects, override the TransferData or CreateReplacementObject methods from VisualizerObjectSource.

See also