How to: Write a Visualizer
This topic applies to:
Visual Studio Edition |
Visual Basic |
C# |
C++ |
J# |
Express |
Yes |
Yes |
Managed only |
Yes |
Standard |
Yes |
Yes |
Managed only |
Yes |
Pro/Team |
Yes |
Yes |
Managed only |
Yes |
You can write a custom visualizer for an object of any managed class except for Object or Array.
The architecture of a debugger visualizer has two parts:
The debugger side runs within the Visual Studio debugger. The debugger-side code creates and displays the user interface for your visualizer.
The debuggee side runs within the process Visual Studio is debugging (the debuggee).
The data object that you want to visualize (a String object, for example) exists in the debuggee-process. So, the debuggee side has to send that data object to the debugger side, which can then display it using a user interface you create.
The debugger side receives this data object to be visualized from an object provider that implements the IVisualizerObjectProvider interface. The debuggee side sends the data object through the object source, which is derived from VisualizerObjectSource. The object provider can also send data back to the object source, which enables you to write a visualizer that edits, as well as displays, data. The object provider can be overridden to talk to the expression evaluator and, therefore, to the object source
The debuggee side and debugger side communicate with one another through Stream. Methods are provided to serialize a data object into a Stream and deserialize the Stream back into a data object.
The debuggee side code is specified using the DebuggerVisualizer attribute (DebuggerVisualizerAttribute).
To create the visualizer user interface on the debugger side, you must create a class that inherits from DialogDebuggerVisualizer and override the Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show(Microsoft.VisualStudio.DebuggerVisualizers.IDialogVisualizerService,Microsoft.VisualStudio.DebuggerVisualizers.IVisualizerObjectProvider) method to display the interface.
You can use IDialogVisualizerService to display Windows forms, dialogs, and controls from your visualizer.
Support for generic types is limited. You can write a visualizer for a target that is a generic type only if the generic type is an open type. This restriction is the same as the restriction when using the DebuggerTypeProxy attribute. For details, see Using DebuggerTypeProxy Attribute.
Custom visualizers may have security considerations. See Visualizer Security Considerations.
The procedures below, give a high-level view of what you need to do to create a visualizer. For a more detailed explanation, see Walkthrough: Writing a Visualizer.
To create the debugger side
Use IVisualizerObjectProvider methods to get the visualized object on the debugger side.
Create a class that inherits from DialogDebuggerVisualizer.
Override the Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show(Microsoft.VisualStudio.DebuggerVisualizers.IDialogVisualizerService,Microsoft.VisualStudio.DebuggerVisualizers.IVisualizerObjectProvider) method to display your interface. Use IDialogVisualizerService methods to display Windows forms, dialogs, and controls as part of your interface.
Apply DebuggerVisualizerAttribute, giving it a visualizer (DialogDebuggerVisualizer).
To create the debuggee-side
Apply DebuggerVisualizerAttribute, giving it a visualizer (DialogDebuggerVisualizer) and an object source (VisualizerObjectSource). If you omit the object source, a default object source will be used
If you want your visualizer to be able to edit data objects, as well as display them, you will need to override the
TransferDataorCreateReplacementObjectmethods from VisualizerObjectSource.
See Also
Tasks
How to: Install a Visualizer
How to: Test and Debug a Visualizer
Concepts
Visualizer Security Considerations