{"id":7031,"date":"2015-09-28T14:27:00","date_gmt":"2015-09-28T14:27:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/vcblog\/2015\/09\/28\/debug-visualizers-in-visual-c-2015\/"},"modified":"2021-10-11T13:31:44","modified_gmt":"2021-10-11T13:31:44","slug":"debug-visualizers-in-visual-c-2015","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/debug-visualizers-in-visual-c-2015\/","title":{"rendered":"Debug Visualizers in Visual C++ 2015"},"content":{"rendered":"

When debugging your native applications, it is often useful to view the values of the objects in memory in a specific way, whether that be with custom string formatting, or even performing an operation on the data to make it more meaningful and easy to interpret.  Since VS2012, Visual Studio had provided the .natvis visualizer format<\/a> for declaring custom visualizations for different C\/C++ types.   Visualized types change the way objects are shown in the native expression evaluator which populates the watch and variable windows, as well as debug data tips. For additional information on the expression evaluator beyond what is needed for reading this post, consult this documentation<\/a> and this blog post<\/a>.<\/p>\n

Writing a Simple Visualizer<\/strong><\/span><\/p>\n

Let’s start by creating a native for the following Volcano class:<\/p>\n

using namespace std;

class Volcano
{
 private:
     string m_EnglishName;
     string m_nativeName;
     string m_meaning;Publish<\/a>
     int m_elevation; 

\/\/...rest of class definition 
}<\/code><\/pre>\n
Natvis Item Template<\/strong><\/p>\n
Adding new .natvis files to a project is easy in VS2015 with the new built-in template which can be found under Project->Add New Item<\/em>->Visual C++->Utility-><\/em>Debugger visualization file (.natvis)<\/em>:<\/p>\n
\"Image<\/a><\/p>\n
In order to make our Volcano objects easier to debug, we will make the display string<\/em> equal to the English name since that is the most recognizable entity where referring to a volcano object.  The we will create an expand<\/em> view to display the contained members.  To remove quotations on the first two strings we will apply the sb format specifier<\/a> to both the native and English names, but will leave it off the meaning member since quotation marks will help differentiate the definition when debugging.  Since our integer m_elevation is already clearly readably, we will simply list the variable without modification.<\/p>\n
Below is the simple .natvis visualizer for displaying our Volcano objects as desired in the C++ expression evaluator when debugging.  Notice that the curly brace operator on the <DisplayString><\/span> node which relays values from application being debugged.  This allows for use of regular text in the output as well as debuggee values:<\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?>
 <AutoVisualizer xmlns=\"http:\/\/schemas.microsoft.com\/vstudio\/debugger\/natvis\/2010<\/a>\">
   <Type Name=\"Volcano\">
     <DisplayString>Name: {m_EnglishName,sb}<\/DisplayString>
     <Expand>
       <Item Name=\"Native name\">m_nativeName,sb<\/Item>
       <Item Name=\"Meaning\">m_meaning<\/Item>
       <Item Name=\"Elevation\">m_elevation<\/Item>
     <\/Expand>
   <\/Type>
 <\/AutoVisualizer><\/code><\/pre>\n
In order to make our Volcano objects easier to debug, we will make the display string<\/em> equal to the English name since that is the most recognizable entity where referring to a volcano object.  Notice that the curly brace operator on the DisplayString node which relays values from application being debugged, which allows for use of regular text in the output as well as debuggee values.  Then we will create an expand<\/em> view to display the contained members.  To remove quotations on the first two strings we will apply the sb format specifier<\/a> to both the native and English names, but will leave it off the meaning member since quotation marks will help differentiate the definition when debugging.  Since our integer m_elevation is already clearly readable, we will simply list the variable without modification.<\/p>\n
Visualized View of a Volcano Object<\/strong><\/p>\n
Once the .natvis file is integrated into the project, a Volcano object will be the visualized as shown in the watch window below.  The [Raw View] node can be expanded to easily see the default view:<\/p>\n
\"Image<\/a><\/p>\n
For more information on writing type visualizers inside .natvis files, check out the full documentation<\/a> of writing basic type visualizers.<\/p>\n
New Visualization Features in VS2015<\/strong><\/span><\/p>\n
Project Integration of Natvis Files<\/strong><\/p>\n
As shown with the above template and in an earlier preview of VS2015<\/a>, .natvis files can now be added to projects or solutions and benefit from source control, as well as the ability to link into the PDB during a build for future consumption by the debugger. Besides individual projects, you can also add a .natvis file as a top-level solution item for .exe projects<\/a>.  Manually copying .natvis files to the special directories is longer necessary!<\/p>\n
If multiple valid entries are encountered for the same type, the first one in the following list will be used:<\/p>\n