Solution and Project Objects

Solution and Project Objects

The Solution object represents the currently loaded solution. The individual projects within the solution are available via Project objects returned within the Solution.Projects collection. Items within a project are accessed in a similar fashion through the Project.ProjectItems collection.

As you can see from Figure 10.1, this hierarchy exactly mirrors the solution/project hierarchy that we first discussed in Chapter 4, "Solutions and Projects."

Figure 10.1. Mapping the solution/project hierarchy.

There are some mismatches heresolution folders, for instance, are treated as projectsbut for the most part, the object model tree closely resembles the solution project tree that you are used to.

The Solution object and Solution2 object members allow you to interact with the current solution to perform common tasks such as

• Determining the number of projects in the solution (Count property)

• Adding a project to the solution based on a project file (AddFromFile method)

• Creating a new solution or closing the current one (Create and Close methods)

• Saving the solution (SaveAs method)

• Removing a project from the solution (Remove method)

You can also directly retrieve a reference to any of the projects within the currently loaded solution by iterating over the Solution.Projects collection. As an example of interacting with the Solution and Project objects, this Visual Basic code snippet removes the first project from the current solution:

Dim sol As Solution = DTE.Solution Dim proj As Project = sol.Projects.Item(1) If proj.Saved Then              sol.Remove(proj) Else       ... End If

Table 10.3 provides the combined list of the most commonly used properties and methods implemented by Solution2.

Table 10.3. Primary Solution/Solution2 Object Members

Property	Description
AddIns	Returns a collection of AddIn objects associated with the current solution.
Count	Returns a count of the projects within the solution.
DTE	Provides a reference back to the parent DTE object.
FullName	Provides the full path and name of the solution file.
IsOpen	Indicates whether a solution is open.
Projects	Returns a collection of Project objects representing all the projects within the solution.
Properties	Returns a collection of Property objects that expose all the solution's properties.
Saved	Indicates whether the solution has been saved since the last modification.
SolutionBuild	Returns a reference to a SolutionBuild object. This is the entry point to the build automation objects applicable for the current solution.

Method	Description
AddFromFile	Adds a project to the solution using an existing project file.
AddFromTemplate	Takes an existing project, clones it, and adds it to the solution.
AddSolutionFolder	Creates a new solution folder in the solution.
Close	Closes the solution.
Create	Creates an empty solution.
FindProjectItem	Initiates a search for a given item in one of the solution's projects.
Item	Returns a Project instance.
Open	Opens a solution (using a specific view).
Remove	Removes a project from the solution.
SaveAs	Saves the solution.

Controlling Projects in a Solution

One of the things that the Solution object is good for is retrieving references to the various projects that belong to the solution. Each Project object has its own set of useful members for interacting with the projects and their items. By using these members, you can interact with the projects in various, expected ways, such as renaming a project, deleting a project, and saving a project.

See Table 10.4 for a summary of the most common Project members.

Table 10.4. Primary Project Object Members

Property	Description
AddIns	Returns a collection of AddIn objects associated with the current solution.
Count	Returns a count of the project within the solution.
DTE	Provides a reference back to the parent DTE object.
FullName	Provides the full path and name of the solution file.
IsOpen	Indicates whether a solution is open.
Projects	Returns a collection of Project objects representing all the projects within the solution.
Properties	Returns a collection of Property objects that expose all the solution's properties.
Saved	Indicates whether the solution has been saved since the last modification.
SolutionBuild	Returns a reference to a SolutionBuild object. This is the entry point to the build automation objects applicable for the current solution.

Method	Description
AddFromFile	Adds a project to the solution using an existing project file.
AddFromTemplate	Takes an existing project, clones it, and adds it to the solution.
AddSolutionFolder	Creates a new solution folder in the solution.
Close	Closes the solution.
Create	Creates an empty solution.
FindProjectItem	Initiates a search for a given item in one of the solution's projects.
Item	Returns a Project instance.

Property	Description
Open	Opens a solution (using a specific view).
Remove	Removes a project from the solution.
SaveAs	Saves the solution.

Accessing Code Within a Project

Beyond the basic project attributes and items, one of the cooler things that can be accessed via a Project instance is the actual code within the project's source files. Through the CodeModel property, you can access an entire line of proxy objects representing the code constructs within a project. For instance, the CodeClass interface allows you to examine and edit the code for a given class in a given project.

Note

Support for the different CodeModel entities varies from language to language. The MSDN documentation for each CodeModel type clearly indicates the source language support for that element.

After grabbing a CodeModel reference from a Project instance, you can access its CodeElements collection (which is, not surprisingly, a collection of CodeElement objects). A CodeElement is nothing more than a generic representation of a certain code structure within a project. The CodeElement object is generic, but it provides a property, Kind. This property is used to determine the exact native type of the code object contained within the CodeElement.

The CodeElement.Kind property is an enumeration (of type vsCMElement) that identifies the specific type of code construct lurking within the CodeElement object. Using the Kind property, you can first determine the true nature of the code element and then cast the CodeElement object to its strong type. Here is a snippet of C# code that does just that:

if (element.Kind == vsCMElement.vsCMElementClass)             CodeClass myClass = (CodeClass)element;

For a better grasp of the code model hierarchy, consider the C# code presented in Listing 10.1; this is a "shell" solution that merely implements a namespace, a class within that namespace, and a function within the class.

Listing 10.1. A Simple Namespace and Class Implementation

using System; using System.Collections.Generic; using System.Text; namespace MyNamespace {    class MyClass    {        public string SumInt(int x, int y)        {            return x + y;        }    } }

If you map the code in Listing 10.1 to the code object model, you would end up with the structure you see in Figure 10.2.

Figure 10.2. Simple code model object hierarchy.

To get an idea of the complete depth of the code model tree that can be accessed through the CodeElements collection, consult Table 10.5; this table shows all the possible vsCMElement values, the type they are used to represent, and a brief description of the type.

Table 10.5. Mapping the vsCMElement Enumeration Values

Enumeration Value	Type	Description
vsCMElementAssignmentStmt		An assignment statement
vsCMElementAttribute		An attribute
vsCMElementClass	CodeClass	A class
vsCMElementDeclareDecl		A declaration
vsCMElementDefineStmt		A define statement
vsCMElementDelegate	CodeDelegate	A delegate
vsCMElementEnum	CodeEnum	An enumeration
vsCMElementEvent	CodeEvent	An event
vsCMElementEventsDeclaration		An event declaration
vsCMElementFunction	CodeFunction	A function
vsCMElementFunctionInvokeStmt		A statement invoking a function
vsCMElementIDLCoClass		An IDL co-class
vsCMElementIDLImport		An IDL import statement
vsCMElementIDLImportLib		An IDL import library
vsCMElementIDLLibrary		An IDL library
vsCMElementImplementsStmt		An implements statement
vsCMElementImportStmt	CodeImport	An import statement
vsCMElementIncludeStmt		An include statement
vsCMElementInheritsStmt		An inherits statement
vsCMElementInterface	CodeInterface	An interface
vsCMElementLocalDeclStmt		A local declaration statement
vsCMElementMacro		A macro
vsCMElementMap		A map
vsCMElementMapEntry		A map entry
vsCMElementModule		A module
vsCMElementNamespace	CodeNamespace	A namespace
vsCMElementOptionStmt		An option statement
vsCMElementOther	CodeElement	A code element not otherwise identified in this enum
vsCMElementParameter	CodeParameter	A parameter
vsCMElementProperty	CodeProperty	A property
vsCMElementPropertySetStmt		A property set statement
vsCMElementStruct	CodeStruct	A structure
vsCMElementTypeDef		A type definition
vsCMElementUDTDecl		A user-defined type
vsCMElementUnion		A union
vsCMElementUsingStmt	CodeImport	A using statement
vsCMElementVariable		A variable
vsCMElementVBAttributeGroup		A Visual Basic attribute group
vsCMElementVBAttributeStmt		A Visual Basic attribute statement
vsCMElementVCBase		A Visual C++ base