Using HierUtil7 Project Classes to Implement a Project Type (C++)
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
The HierUtil7 class framework is provided as a set of helper classes for managing a hierarchy of nodes and providing a default implementation of many of the Visual Studio SDK interfaces in a basic project hierarchy. The HierUtil7 framework is included with the Visual Studio SDK to make it easier for you to implement new project types by deriving classes for your project implementation as appropriate from the HierUtil7 classes.
However, because HierUtil7 is a framework, there are project-specific interfaces that you also must implement based on the requirements of your project type.
This discussion of the implementation of project interfaces is based on the Basic Project sample implementation of the interfaces using HierUtil7. For more information about interfaces used in the sample projects, see Elements of a Project Model and Project Model Core Components.
The following illustration shows the class inheritance of the Basic Project sample implementation.
Class hierarchy and corresponding file names in Basic Project
.gif "Class Structure graphic")
As shown in the illustration, CMyProjectHierarchy is declared in PrjHier.h and defined in PrjHier.cpp. The class inherits from CVsHierarchy (one of the HierUtil7 base classes) and implements the project interfaces. Additionally, it adds implementations for other important or optional project-related interfaces that are not contained in CVsHierarchy. The CMyProjectHierarchy object corresponds to the Project Objects module in the Project Model diagram in Elements of a Project Model and exposes the interfaces required for project integration into the environment.
CFileVwBaseNode is declared in PrjNBase.h and defined in PrjNBase.cpp. The class inherits from HierUtil7's ChierContainer, which inherits from ChierNode, and implements common functionality for both leaf nodes and parent nodes in the project hierarchy.
CFileVwProjNode is declared in PrjNRoot.h and defined in PrjNRoot.cpp. The class inherits from CFileVwBaseNode and represents the parent (project) node in the project hierarchy.
CFileVwFileNode is declared in PrjNFile.h and defined in PrjNFile.cpp. The class also inherits from CFileVwBaseNode and represents a leaf (or, in the case of the Basic Project sample, a file) node in the project hierarchy.
Note
CFileVwBaseNode, CFileVwProjNode, and CFileVwFileNode implement most of the node management operations. CMyProjectHierarchy uses them to provide the interfaces' implementation by routing calls on IVsHierarchy to specific implementations for node operations. For example, CMyProjectHierarchy exposes the AddItemWithSpecific method, which uses the AddItem method defined in CFileVwProjNode to perform the operation.
In the Basic Project sample, CMyProjectHierarchy implements the fundamental project interfaces using CFileVwBaseNode, CFileVwProjNode, and CFileVwFileNode to implement the operations with the hierarchy nodes.
The Basic Project sample does not manage folder nodes and the class CFileVwFolderNode does not exist in the sample. Because a folder node is a container of file nodes but is not the root (project) node, the graphic shows a suggested implementation of CFileVwFolderNode class, which represents a folder node in the project hierarchy and inherits from CFileVwBaseNode class.
The following illustration shows interfaces called from CVsHierarchy and implemented from CMyProjectHierarchy, and files that map to project items using the class CFileVwFileNode.
Project implementation classes
.gif "Visual Studio Project graphic")
The CMyProjectHierarchy object points to the CFileVwProjNode object and vice versa. Together they administer all the items in the project. The CMyProjectHierarchy interfaces handle the primary responsibilities of the project. These responsibilities include persisting files, providing configuration information, starting services, and providing clipboard features. Additionally, VxDTE::IVsGlobalsCallback provides support for reading and writing data for extensibility clients.
CFileVwProjNode does not expose interfaces. It provides implementation of some of the project item operations, but does not expose them directly to the environment as interfaces. CMyProjectHierarchy exposes the interfaces, which sometimes in the sample use the actual implementation of the methods provided by CFileVwProjNode.
Each CFileVwFileNode is an object that is identified by a unique VSITEMID. A VSITEMID is just a DWORD_PTR and can hold any information specific to your implementation. Typically, a VSITEMID is cast to the pointers of the object itself. However, your implementation might use the VSITEMID as an index to an array.
Typically, a different class implements each node type in the hierarchy. For example, the class CFileVwFileNode represents the leaf (file) node and the class CFileVwProjNode represents the project node.
The Basic Project sample is simple because it only manages a flat list of file nodes, or leaf nodes, under the root node. A more complex project has a deeper hierarchy of nodes and other node types, such as project reference nodes and database connection nodes.
In nested projects, a child node can act as a folder and, in turn, have other child nodes. The semantics of each node are controlled by the project implementation as you design it. For more information, see Nesting Projects.
See Also
Reference
Concepts
Checklist: Creating New Project Types
Creating Project Instances By Using Project Factories