Merge pull request #273 from Microsoft/brpeek-tfs384493

Fix escaped characters and missing code snippets

Author: ghogen

docs/debugger/create-custom-views-of-native-objects.md

@@ -10,11 +10,11 @@ ms.tgt_pltfrm: ""
 ms.topic: "article"
 f1_keywords: 
   - "natvis"
-dev_langs: 
-  - "FSharp"
-  - "VB"
-  - "CSharp"
-  - "C++"
+#dev_langs: 
+#  - "FSharp"
+#  - "VB"
+#  - "CSharp"
+#  - "C++"
 ms.assetid: 2d9a177a-e14b-404f-a6af-49498eff0bd7
 caps.latest.revision: 19
 author: "mikejo5000"
@@ -66,8 +66,7 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  The basic structure of a .natvis file is one or more `Type` elements, where each `Type` element represents a visualization entry for a type whose fully qualified name is specified in the `Name` attribute.  
 
-```xml  
-  
+```xml
 <?xml version="1.0" encoding="utf-8"?>  
 <AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">  
   <Type Name="MyNamespace::CFoo">  
@@ -125,10 +124,10 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
  To control how an expression is displayed in a variable window, you can use any of the format specifiers that are described in the [Format Specifiers](../debugger/format-specifiers-in-cpp.md#BKMK_Visual_Studio_2012_format_specifiers) section of the [Format Specifiers in C++](../debugger/format-specifiers-in-cpp.md) topic. Note that format specifiers are ignored when the virtualization entry is used internally by Natvis, such as the `Size` expression in in a [ArrayItems expansion](../debugger/create-custom-views-of-native-objects.md#BKMK_ArrayItems_expansion).  
 
 ## Natvis views  
- Natvis views allow you to see any type in more than one way. For example, you can define a view named **simple** that gives you a simplified view of a type. For example, here is the visualization of `std::vector`:  
+ Natvis views allow you to see any type in more than one way. For example, you can define a view named **simple** that gives you a simplified view of a type. For example, here is the visualization of `std::vector`:
 
-```xml  
-<Type Name="std::vector<*>">  
+```xml
+<Type Name="std::vector&lt;*&gt;">  
     <DisplayString>{{ size={_Mylast - _Myfirst} }}</DisplayString>  
     <Expand>  
         <Item Name="[size]" ExcludeView="simple">_Mylast - _Myfirst</Item>  
@@ -153,7 +152,7 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ###  <a name="BKMK_AutoVisualizer"></a> AutoVisualizer element  
  The `AutoVisualizer`  element is the root node of the .natvis file and contains the namespace `xmlns:` attribute.  
 
-```xml  
+```xml
 <?xml version="1.0" encoding="utf-8"?>  
 <AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">  
 .  
@@ -164,14 +163,13 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ###  <a name="BKMK_Type"></a> Type element  
  A basic Type looks like this:  
 
-```xml  
+```xml
 <Type Name="[fully qualified type name]">  
   <DisplayString Condition="[Boolean expression]">[Display value]</DisplayString>  
   <Expand>  
     ...  
   </Expand>  
 </Type>  
-  
 ```  
 
  It specifies:  
@@ -184,8 +182,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  **Templated classes** The `Name` attribute of the `Type` element accepts an asterisk `*` as a wildcard character that can be used for templated class names:  
 
-```xml  
-<Type Name="ATL::CAtlArray<*>">  
+```xml
+<Type Name="ATL::CAtlArray&lt;*&gt;">  
     <DisplayString>{{Count = {m_nSize}}}</DisplayString>  
 </Type>  
 
@@ -201,8 +199,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 #### Inheritable attribute  
  You can specify whether a visualization applies only to a base type or to a base type and all derived types with the optional `Inheritable` attribute. In the following, the visualization applies only to the `BaseClass` type:  
 
-```xml  
-<Type Name="Namespace::BaseClass" Inheritable=“true”>  
+```xml
+<Type Name="Namespace::BaseClass" Inheritable="true">  
     <DisplayString>{{Count = {m_nSize}}}</DisplayString>  
 </Type>  
 ```  
@@ -216,17 +214,17 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  In the following example, we will first parse the entry that matches the 2015 STL, and if that fails to parse, we will use the alternate entry for the 2013 version of the STL:  
 
-```xml  
+```xml
 <!-- VC 2013 -->  
-<Type Name="std::reference_wrapper<*>" Priority="MediumLow">  
+<Type Name="std::reference_wrapper&lt;*&gt;" Priority="MediumLow">  
      <DisplayString>{_Callee}</DisplayString>  
     <Expand>  
         <ExpandedItem>_Callee</ExpandedItem>  
     </Expand>  
 </Type>  
 
 <!-- VC 2015 -->  
-<Type Name="std::reference_wrapper<*>">  
+<Type Name="std::reference_wrapper&lt;*&gt;">  
     <DisplayString>{*_Ptr}</DisplayString>  
     <Expand>  
         <Item Name="[ptr]">_Ptr</Item>  
@@ -237,7 +235,7 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ####  <a name="BKMK_Versioning"></a> Version element  
  Use the `Version` element to scope visualizations to specific modules and their versions so that name collisions can be minimized and different visualizations can be used for different versions of the types. For example:  
 
-```xml  
+```xml
 <Type Name="DirectUI::Border">  
   <Version Name="Windows.UI.Xaml.dll" Min="1.0" Max="1.5"/>  
   <DisplayString>{{Name = {*(m_pDO->m_pstrName)}}}</DisplayString>  
@@ -252,7 +250,7 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 #### Optional attribute  
  The `Optional` attribute can appear on any node. If any sub-expression inside an optional node fails to parse, that node is ignored, but the rest of the Type element is still valid. In the following type, `[State]` is non-optional, but `[Exception]` is optional.  This means that if `MyNamespace::MyClass` contains a field named _`M_exceptionHolder`, you will still both `[State]` node and the `[Exception]` node, but if the `_M_exceptionHolder` is missing, you will see only the `[State]` node.  
 
-```xml  
+```xml
 <Type Name="MyNamespace::MyClass">  
     <Expand>  
       <Item Name="[State]">_M_State</Item>  
@@ -264,8 +262,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ###  <a name="BKMK_Condition_attribute"></a> Condition attribute  
  The optional `Condition` attribute is available for many visualization elements and specifies when a visualization rule should be used. If the expression inside the condition attribute resolves to `false`, then the visualization rule specified by the element is not applied. If it evaluates to true, or if there is no `Condition` attribute, then the visualization rule is applied to the type. You can use this attribute for `if-else` logic in the visualization entries. For example, the visualization below has two `DisplayString` elements for a smart pointer type:  
 
-```xml  
-<Type Name="std::auto_ptr<*>">  
+```xml
+<Type Name="std::auto_ptr&lt;*&gt;">  
   <DisplayString Condition="_Myptr == 0">empty</DisplayString>  
   <DisplayString>auto_ptr {*_Myptr}</DisplayString>  
   <Expand>  
@@ -280,8 +278,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ### IncludeView and ExcludeView attributes  
  These attributes specify elements that are to be displayed or not displayed in different views. For example, given the Natvis specification of `std::vector`:  
 
-```xml  
-<Type Name="std::vector<*>">  
+```xml
+<Type Name="std::vector&lt;*&gt;">  
     <DisplayString>{{ size={_Mylast - _Myfirst} }}</DisplayString>  
     <Expand>  
         <Item Name="[size]" ExcludeView="simple">_Mylast - _Myfirst</Item>  
@@ -301,7 +299,7 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ###  <a name="BKMK_DisplayString"></a> DisplayString  
  A `DisplayString` element specifies the string to be shown as the value of the variable. It accepts arbitrary strings mixed with expressions. Everything inside curly braces is interpreted as an expression. For instance, a `DisplayString` entry like this:  
 
-```xml  
+```xml
 <Type Name="CPoint">  
   <DisplayString>{{x={x} y={y}}}</DisplayString>   
 </Type>  
@@ -320,11 +318,10 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ###  <a name="BKMK_StringView"></a> StringView  
  The `StringView` element defines the expression whose value is going to be sent to the built-in text visualizer. For example, suppose we have the following visualization for the `ATL::CStringT` type:  
 
-```xml  
-<Type Name="ATL::CStringT<wchar_t,*>">  
+```xml
+<Type Name="ATL::CStringT&lt;wchar_t,*&gt;">  
   <DisplayString>{m_pszData,su}</DisplayString>  
-</Type>  
-  
+</Type>
 ```  
 
  The `CStringT` object looks like:  
@@ -335,12 +332,11 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  Adding a `StringView` element will indicate to the debugger that this value can be viewed by a text visualization:  
 
-```  
-<Type Name="ATL::CStringT<wchar_t,*>">  
+```xml
+<Type Name="ATL::CStringT&lt;wchar_t,*&gt;">
   <DisplayString>{m_pszData,su}</DisplayString>  
   <StringView>m_pszData,su</StringView>  
 </Type>  
-  
 ```  
 
  Notice the magnifying glass icon shown next to the value below. Choosing the icon will launch the text visualizer which will display the string that `m_pszData` points to.  
@@ -362,7 +358,7 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ####  <a name="BKMK_Item_expansion"></a> Item expansion  
  The `Item` element is the most basic and the most common element to be used in an `Expand` node. `Item` defines a single child element. For example, suppose that you have a `CRect` class with `top`, `left`, `right`, and `bottom` as its fields and the following visualization entry:  
 
-```xml  
+```xml
 <Type Name="CRect">  
   <DisplayString>{{top={top} bottom={bottom} left={left} right={right}}}</DisplayString>  
   <Expand>  
@@ -385,8 +381,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ####  <a name="BKMK_ArrayItems_expansion"></a> ArrayItems expansion  
  Use the `ArrayItems` node to have the Visual Studio debugger interpret the type as an array and display its individual elements. The visualization for `std::vector` is a good example:  
 
-```xml  
-<Type Name="std::vector<*>">  
+```xml
+<Type Name="std::vector&lt;*&gt;">  
   <DisplayString>{{size = {_Mylast - _Myfirst}}}</DisplayString>  
   <Expand>  
     <Item Name="[size]">_Mylast - _Myfirst</Item>  
@@ -397,7 +393,6 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
     </ArrayItems>  
   </Expand>  
 </Type>  
-  
 ```  
 
  A `std::vector` shows its individual elements when expanded in the variable window:  
@@ -416,8 +411,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  Multi-dimensional arrays can also be specified. The debugger needs just a little bit more information to properly display child elements in that case:  
 
-```xml  
-<Type Name="Concurrency::array<*,*>">  
+```xml
+<Type Name="Concurrency::array&lt;*,*&gt;">  
   <DisplayString>extent = {_M_extent}</DisplayString>  
   <Expand>  
     <Item Name="extent">_M_extent</Item>  
@@ -429,7 +424,6 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
     </ArrayItems>  
   </Expand>  
 </Type>  
-  
 ```  
 
  `Direction` specifies whether the array is row-major or column-major order. `Rank` specifies the rank of the array. The `Size` element accepts the implicit `$i` parameter which it substitutes with the dimension index to find the length of the array in that dimension. For example, in the previous example, above the expression `_M_extent.M_base[0]` should give the length of the 0th dimension, `_M_extent._M_base[1]` the 1st and so on.  
@@ -441,8 +435,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ####  <a name="BKMK_IndexListItems_expansion"></a> IndexListItems expansion  
  You can use the `ArrayItems` expansion, only if the array elements are laid out contiguously in memory. The debugger gets to the next element by simply incrementing its pointer to the current element. To support cases where you need to manipulate the index to the value node, `IndexListItems` nodes can be used. Here’s a visualization using `IndexListItems` node:  
 
-```xml  
-<Type Name="Concurrency::multi_link_registry<*>">  
+```xml
+<Type Name="Concurrency::multi_link_registry&lt;*&gt;">  
   <DisplayString>{{size = {_M_vector._M_index}}}</DisplayString>  
   <Expand>  
     <Item Name="[size]">_M_vector._M_index</Item>  
@@ -452,7 +446,6 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
     </IndexListItems>  
   </Expand>  
 </Type>  
-  
 ```  
 
  You can now use the `[]` operator with an `IndexListItems` expansion, for example `vector[i]`. The `[]` operator can be used with any visualization of a single-dimensional array that uses `ArrayItems` or `IndexListItems`, even if the type itself does not allow this operator (for example `CATLArray`).  
@@ -462,8 +455,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ####  <a name="BKMK_LinkedListItems_expansion"></a> LinkedListItems expansion  
  If the visualized type represents a linked list, the debugger can display its children by using a `LinkedListItems` node. Here’s the visualization for the `CAtlList` type using this feature:  
 
-```xml  
-<Type Name="ATL::CAtlList<*,*>">  
+```xml
+<Type Name="ATL::CAtlList&lt;*,*&gt;">  
   <DisplayString>{{Count = {m_nElements}}}</DisplayString>  
   <Expand>  
     <Item Name="Count">m_nElements</Item>  
@@ -475,7 +468,6 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
     </LinkedListItems>  
   </Expand>  
 </Type>  
-  
 ```  
 
  The `Size` element refers to the length of the list. `HeadPointer` points to the first element, `NextPointer` refers to the next element, and `ValueNode` refers to the value of the item.  
@@ -489,10 +481,10 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  The visualizer for CAtlMap is an excellent example of where `CustomListItems` is appropriate.  
 
-```xml  
-<Type Name="ATL::CAtlMap<*,*,*,*>">  
-    <AlternativeType Name="ATL::CMapToInterface<*,*,*>"/>  
-    <AlternativeType Name="ATL::CMapToAutoPtr<*,*,*>"/>  
+```xml
+<Type Name="ATL::CAtlMap&lt;*,*,*,*&gt;">  
+    <AlternativeType Name="ATL::CMapToInterface&lt;*,*,*&gt;"/>  
+    <AlternativeType Name="ATL::CMapToAutoPtr&lt;*,*,*&gt;"/>  
     <DisplayString>{{Count = {m_nElements}}}</DisplayString>  
     <Expand>  
       <CustomListItems MaxItemsPerView="5000" ExcludeView="Test">  
@@ -521,8 +513,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 ####  <a name="BKMK_TreeItems_expansion"></a> TreeItems expansion  
  If the visualized type represents a tree, the debugger can walk the tree and display its children by using a `TreeItems` node. Here’s the visualization for the `std::map` type using this feature:  
 
-```xml  
-<Type Name="std::map<*>">  
+```xml
+<Type Name="std::map&lt;*&gt;">  
   <DisplayString>{{size = {_Mysize}}}</DisplayString>  
   <Expand>  
     <Item Name="[size]">_Mysize</Item>  
@@ -536,7 +528,6 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
     </TreeItems>  
   </Expand>  
 </Type>  
-  
 ```  
 
  The syntax is very similar to the `LinkedListItems` node. `LeftPointer`, `RightPointer`, and `ValueNode` are evaluated under the context of the tree node class, and `ValueNode` can be left empty or have `this` to refer to the tree node itself.  
@@ -548,36 +539,34 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  To see the values of the vector, you have to drill down two levels in the variable window passing through _Myptr member. By adding an `ExpandedItem` element, you can eliminate the `_Myptr` variable from the hierarchy and directly view the vector elements::  
 
-```xml  
-<Type Name="std::auto_ptr<*>">  
+```xml
+<Type Name="std::auto_ptr&lt;*&gt;">  
   <DisplayString>auto_ptr {*_Myptr}</DisplayString>  
   <Expand>  
     <ExpandedItem>_Myptr</ExpandedItem>  
   </Expand>  
 </Type>  
-  
 ```  
 
  ![auto&#95;ptr&#60;vector&#60;int&#62;&#62; ExpandedItem expansion](../debugger/media/dbg_natvis_expand_expandeditem_visualized.png "DBG_NATVIS_Expand_ExpandedItem_Visualized")  
 
  The example below shows how to aggregate properties from the base class in a derived class. Suppose the `CPanel` class derives from `CFrameworkElement`. Instead of repeating the properties that come from the base `CFrameworkElement` class, the `ExpandedItem` node allows those properties to be appended to the child list of the `CPanel` class. The **nd** format specifier which turns off visualization matching for the derived class is necessary here. Otherwise, the expression `*(CFrameworkElement*)this` will cause the `CPanel` visualization to be applied again because the default visualization type matching rules consider it the most appropriate one. Using the **nd** format specifier instructs the debugger to use the base class visualization or the base class default expansion if the base class doesn’t have a visualization.  
 
-```xml  
+```xml
 <Type Name="CPanel">  
   <DisplayString>{{Name = {*(m_pstrName)}}}</DisplayString>  
   <Expand>  
     <Item Name="IsItemsHost">(bool)m_bItemsHost</Item>  
     <ExpandedItem>*(CFrameworkElement*)this,nd</ExpandedItem>  
   </Expand>  
 </Type>  
-  
 ```  
 
 ####  <a name="BKMK_Synthetic_Item_expansion"></a> Synthetic Item expansion  
  Where the `ExpandedItem` element provides a flatter view of data by eliminating hierarchies, the `Synthetic` node does the opposite. It allows you to create an artificial child element (that is, a child element that is not a result of an expression). This child element can contain children elements of its own. In the following example, the visualization for the `Concurrency::array` type uses a `Synthetic` node to show a diagnostic message to the user:  
 
-```xml  
-<Type Name="Concurrency::array<*,*>">  
+```xml
+<Type Name="Concurrency::array&lt;*,*&gt;">  
   <DisplayString>extent = {_M_extent}</DisplayString>  
   <Expand>  
     <Item Name="extent" Condition="_M_buffer_descriptor._M_data_ptr == 0">_M_extent</Item>  
@@ -612,8 +601,7 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  Here's an example of a UIVisualizer element:  
 
-```xml  
-  
+```xml
 <?xml version="1.0" encoding="utf-8"?>  
 <AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">  
     <UIVisualizer ServiceId="{5452AFEA-3DF6-46BB-9177-C0B08F318025}"   
@@ -633,9 +621,8 @@ The Visual Studio Natvis framework lets you customize the way Visual Studio disp
 
  Each type defined in the .natvis file must explicitly list the UI visualizers that can display them. The debugger matches the visualizer references in the type entries to match types with the registered visualizers. For example, the following type entry for `std::vector` references the UIVisualizer in our example above.  
 
-```  
-  
-<Type Name="std::vector<int,*>">  
+```xml
+<Type Name="std::vector&lt;int,*&gt;">  
   <UIVisualizer ServiceId="{5452AFEA-3DF6-46BB-9177-C0B08F318025}" Id="1" />  
 </Type>  
 ```