Create views of OpenCASCADE objects in the Debugger
eryar@163.com
Abstract. The Visual Studio Natvis framework lets you customize the way Visual Studio displays native types in debugger variable windows such as the Watch, Locals and Data Tips windows. It supersedes the autoexp.dat file that has been used in earlier versions of Visual Studio and offers XML syntax, better diagnostics, versioning, and multiple file support. The container in OpenCASCADE is difficult for debugging, such as TColStd_Array1OfInteger in the TColStd package, .etc. Use the natvis framework to create views of these objects will make it easy for developers to inspect them during debugging and so accelerate the debug process.
Key Words. Visual Studio Natvis, OpenCASCADE
1. Introduction
因為OpenCASCADE早期使用C開發，所以自定義了一些容器類，如包TColStd中的類，TColGeom包及包TopTools中的類等，這些類在C++中都可以使用STL來替代了。這些類在Debug過程中，很難查看其中的值，如TColStd_Array1OfInteger，這個類相當于std::vector<int>，但是Debug時只能看到數據的指針，不容易查看容器中每個元素的值，如下圖1.1所示：
Figure 1.1 View of TColStd_Array1OfInteger in Locals Window
由上圖1.1可知，對于這個類的對象，Debug時只能看到數據的起始指針。為了方便自定義類型調試，Visual Studio在2012版本以后，引入了Natvis框架，用來替代原來的autoexp.dat來為自定義類型定義調試時的數據顯示。Natvis使用了XML文件，可讀性更好，易于實現。
本文使用Visual Studio的Natvis框架，來對OpenCASCADE中的一些容器類數據進行可視化，方便開發者對OpenCASCADE的調試。
2.For Array Container
對于OpenCASCADE的包TColStd中的數組類，定義其natvis如下所示：
<Type Name="TColStd_Array1OfInteger">
<DisplayString Condition="isAllocated != 1">empty</DisplayString>
<DisplayString>{{size = {myUpperBound - myLowerBound + 1}}}</DisplayString>
<Expand>
<Item Condition="isAllocated == 1" Name="[size]">myUpperBound - myLowerBound + 1</Item>
<ArrayItems Condition="isAllocated == 1">
<Size>myUpperBound - myLowerBound + 1</Size>
<ValuePointer>(Standard_Integer*)(myStart) + myLowerBound</ValuePointer>
</ArrayItems>
</Expand>
</Type>
調試時數據顯示如下圖2.1所示：
Figure 2.1 OpenCASCADE array in Locals Windows
同理，可對此包中其他一維數組使用同樣的規則，即可對其中的數據可視化，與std::vector顯示的效果一樣，方便調試。
3.For List Container
對于OpenCASCADE的包TColStd中的鏈表類，定義其natvis如下所示：
<Type Name="TColStd_ListNodeOfListOfInteger">
<DisplayString>{{current = {myValue}}}</DisplayString>
<Expand>
<LinkedListItems>
<HeadPointer>this</HeadPointer>
<NextPointer>(TColStd_ListNodeOfListOfInteger*)myNext</NextPointer>
<ValueNode>this->myValue</ValueNode>
</LinkedListItems>
</Expand>
</Type>
<Type Name="TColStd_ListOfInteger">
<DisplayString Condition="myFirst == 0">empty</DisplayString>
<Expand>
<Item Name="first">(TColStd_ListNodeOfListOfInteger*)myFirst</Item>
</Expand>
</Type>
調試時對于類TColStd_ListOfInteger，natvis診斷說找不到類TColStd_ListNodeOfListOfInteger定義，當跟蹤到此類一個具體函數時，就可以看到具體的值了：
Figure 3.1 Natvis gives a Error info
跟蹤到TColStd_ListOfInteger內部后，就可以看到類TColStd_ListNodeOfListOfInteger中的數據了，但是從TColStd_ListOfInteger的函數中出來后，就看不到了。
如果這個問題解決了，對于類TopoDS_ListOfShape中的數據也可以用同樣的方式來顯示，極大地方便了開發者對其調試。如果你對此有解決辦法，歡迎不吝賜教。
Figure 3.2 Data view for TColStd_ListNodeOfListOfInteger
先從簡單的容器類著手，解決后可將TopoDS_ListOfShape中的數據顯示出來，為OpenCASCADE程序的調試提供方便。
4.Conclusion
Visual Studio 2012版本以后引入了Natvis框架來對自定義的類進行可視化，方便調試。OpenCASCADE中有很多容器類直接使用了指針，調試程序時數據很不直觀。應用Natvis來對一些類在調試時的視圖進行配置，可以方便查看其中數據，使OpenCASCADE的調試更輕松。
對于一維數組的natvis定義還是很簡單的，但是對于List出現了問題。如果這個問題解決了，對TopoDS_ListOfShape的可視化也可做同樣的處理，方便造型算法調試。若您有解決方案，望不吝賜教。
5. References
1. Create custom views of native objects in the debugger.
https://msdn.microsoft.com/en-us/library/vstudio/jj620914.aspx
2. Writing debugger type visualizers for C++ using .natvis files
https://code.msdn.microsoft.com/Writing-type-visualizers-2eae77a2#content
3. vczh. C++實用技巧之配置Visual C++的調試器顯示數據結構的格式.
http://www.shnenglu.com/vczh/archive/2013/03/21/198665.html
4. stl.natvis in %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers
5. qt5.natvis in %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers