Per-project natvis files in Visual Studio “14”

Visual Studio 2012 introduced a new framework for writing debugger visualizers for C++ types that replaced the old autoexp.dat file. The new framework offers xml syntax, better diagnostics, versioning and multiple file support.

Visualizers are defined in XML files with extension .natvis. These visualizers are loaded each time the debugger starts. That means if you make a change to visualizers, it is not necessary to re-start Visual Studio, just re-start the debugger (for instance detach and re-attach the debugger to the process you debug).

These files can be located under one of these locations:

• %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers (requires admin access)
• %USERPROFILE%\My Documents\Visual Studio 2012\Visualizers\
• VS extension folders

In Visual Studio “14” CTP (in response to a UserVoice request) these files can also be added to a Visual C++ project for easier management and source control integration. All you have to do is add the .natvis file to your .vcxproj file.

Here is an example. Suppose we have the following code:

struct point
{
   double x;
   double y;
   double z;
};

int main()
{
   point p { 1.0, 2.0, 3.0 };

	return 0;
}

If you run this in debugger you can inspect the value of p and it looks like this:

To change the way the point objects are visualized create a file called point.natvis with the following content:

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
   
  <Type Name="point">
    <DisplayString>{{point X={x}, Y={y}, Z={z}}}</DisplayString>
    <Expand>
      <Item Name="axis-X">x</Item>
      <Item Name="axis-Y">y</Item>
      <Item Name="axis-Z">z</Item>
    </Expand>     
  </Type>
   
</AutoVisualizer>

Add this file to the project.

When you run the application in debugger again the point object is visualized according to the per-project .natvis file.

UPDATE
There are two things to note:

• changes in the natvis files are now picked up automatically by the debugger; you no longer need to stop the debugging session and then start again if you make changes to a natvis file
• natvis files from the project are evaluated after all the other files from the other possible locations; that means you can override existing (general) visualizers with project-specific visualizers

For more see Project Support for Natvis.