Category list

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