|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Introduction to Project Extensibility
The object model is available simply by adding references to the VSLangProj assemblies to your project: VSLangProj.dll, VSLangProj2.dll, VSLangProj80.dll, and VSLangProj90.dll assemblies. For more information, see How to: Add or Remove References in Visual Studio (Visual Basic). This means that the object model is available for macros, add-ins, and any type of project that must extend or automate the IDE. Macros are written in the Macros integrated development environment by using Visual Basic. The examples in the topics are written in the Visual Basic and Visual C# languages. For more information on how to run the examples, see How to: Compile and Run the Automation Object Model Code Examples. Add-ins may be written in any Visual Studio hosted language, such as Visual Basic, Visual C#, Visual C++ and Visual J#. The reference topics for the VSLangProj, VSLangProj2, VSLangProj80 and VslangProj90 members include the syntax for each of these languages. For a description of the automation project types and capabilities of automation, see Creating Add-ins and Wizards.
These namespaces contain all of the classes, interfaces, and enumerations for Visual Basic, Visual C# and Visual J# projects. For a complete list of the objects in the namespace, see Visual Basic and Visual C# Extensibility Object Model for Projects.
If you create a project that references one or more of the VSLangProj assemblies and the EnvDTE assembly, you can occasionally get the following error at runtime:
"Unhandled Exception: System.IO.FileNotFoundException: Error while loading file 'EnvDTE, Version=7.0.3300.0"
This error is due to a runtime type resolution conflict. That is, the version of EnvDTE that is included with Visual Studio 2005 is 8.0.xx, but the project's configuration reference is looking for an earlier version of this assembly, version 7.0.xx. To fix this problem, you must add a binding redirect for the newer version of EnvDTE to your project's configuration (.config) file. This will enable Visual Studio to load the newer version of EnvDTE and prevent the error from occurring.
To do this, add an "Application Configuration File" to your project and then replace its contents with the following:
<?xml version="1.0" encoding="utf-8" ?> <configuration> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft- com:asm.v1" appliesTo="v2.0.50318"> <dependentAssembly> <assemblyIdentity name="EnvDTE" publicKeyToken= "b03f5f7f11d50a3a"/> <bindingRedirect oldVersion="7.0.3300.0" newVersion="220.127.116.11"/> </dependentAssembly> </assemblyBinding> </runtime> </configuration>
This object provides access to other objects in the extensibility model. The DTE object is the top-level object in the Visual Studio automation model. In the general extensibility model, a project is represented by the generic Project object. The Project object has an Object property. The type of this property is determined at run time by the language of the project. In a Visual Basic, Visual C# or Visual J# project, the Object property returns an object of type VSProject2. Since the type of the Object property is Object, you must cast the reference to type VSProject2. In a macro, the cast would look like the following if the first project were a Visual Basic project:
using EnvDTE; using EnvDTE80; using EnvDTE90; using VSLangProj; using VSLangProj2; using VSLangProj80; EnvDTE.Project proj; VSLangProj80.VSproject2 vsproject; proj = DTE2.Solution.Projects.Item(1); vsproject = (VSLangProj80.VSProject2)proj.Object;
After you reference the VSProject2 item, you can manipulate the project's properties, configurations, files, folders, imports statements, and references.
For more information, see Introduction to the VSProject2 Object.
The References property, contained by the VSProject2 object, holds a collection of Reference3 objects. The Reference3 object represents a project reference and is primarily a read-only object that supports a Remove method. The References object has support for adding references (COM, .NET assemblies, ActiveX, other projects) and raising events (adding, removing, and changing references).
The Imports property contained by the VSProject2 object maintains a collection of Imports statements that apply to an entire Visual Basic project. If an imports statement is added to this collection, the corresponding Imports statement (for example, Imports VSLangProj) does not have to be added to the code file. This object supports adding and removing imports statements and raising events in response to adding and removing statements. There is no equivalent in a Visual C# project, and the VSProject2.Imports property returns Nothing or null when applied to a Visual C# project. For more information, see Imports.
The VSProjectItem object is the project item counterpart of the VSProject2 object. In the general extensibility model, the generic ProjectItem object represents a project item. The Object property is of type Object, and in a Visual Basic or Visual C# project, the type of this property is VSProjectItem. Casting the object to type VSProjectItem would look like this in a macro:
using EnvDTE; using EnvDTE80; using VSLangProj; using VSLangProj2; using VSLangProj80; using VSLangProj90; EnvDTE.Project proj; VSLangProj.VSProjectItem pi; Pi = (VSProject2)DTE2.Solution.Projects.Item(1).ProjectItems.Item(1). Object;
The VSProjectItem object contains properties that link to the parent project item and project, and a method that forces execution of a custom tool on that item. The BuildManager object handles custom tool output. For more information, see RunCustomTool method, Introduction to the BuildManager Object, VSProjectItem object, and BuildManager object.
The general extensibility model has a Properties property in three objects:
Project object The properties in this object are equivalent to the properties found in the Common Properties tab of the project's Property Pages dialog box in the IDE.
Configuration object The properties in this object are equivalent to the properties found in the Configuration Properties tab of the project's Property Pages dialog box in the IDE.
ProjectItem object The properties in this object are equivalent to the properties found in the Properties window when a project item is selected in Solution Explorer.
In each case the Properties property is a collection of objects of type Property. A Property object can be obtained from the collection by specifying either the property's 1-based index or its name. The contents of the collection depend on the language. In the case of project items, the contents also depend on whether the item is a file or a folder.