Introduction to Project Extensibility in Visual Basic and Visual C#
Visual Studio .NET includes a programmable, project-neutral object model that provides access to the underlying components and events of the integrated development environment (IDE). This "general extensibility" model has components that represent solutions, projects, tool windows, code editors, debuggers, code objects, documents, and events. This general extensibility model is discussed in Functional Automation Groups.
Visual Studio .NET also includes a programmable object model that exposes the Visual Basic and Visual C# projects and the project items they contain. This model contains several objects that may be used automating tasks in the IDE and extending project types and project items. This model for Visual Basic and Visual C# projects is discussed in this section of the documentation.
The object model is available simply by adding a reference to the VSLangProj.dll assembly to any project. For more information, see Adding and Removing References. This means that the object model is available for macros, add-ins, and any type of project that needs to extend or automate the IDE. Macros are written in the Macros integrated development environment using Visual Basic .NET. The examples in the topics are written in the Visual Basic .NET language. Add-ins may be written in any of the .NET languages, including Visual Basic, Visual C#, C++, and JScript .NET. The reference topics for the VSLangProj 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.
This namespace contains all of the classes, interfaces, and enumerations for Visual Basic and Visual C#. For a complete list of the objects in the namespace, see Visual Basic and Visual C# Extensibility Object Model for Projects.
This object provides access to the 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 or Visual C# project, the Object property returns an object of type VSProject. Since the type of the Object property is Object, you must cast the reference to type VSProject. In a macro, the cast would look like the following if the first project were a Visual Basic project:
' Macro editor Dim proj As Project Dim vsproject As VSLangProj.VSProject proj = DTE.Solution.Projects.Item(1) vsproject = CType(proj.Object, VSLangProj.VSProject)
Once you have a reference to the VSProject item, you can manipulate the project's properties, configurations, files, folders, imports statements, and references.
For more information, see Introduction to the VSProject Object.
References and Reference Objects
The References object, contained by the VSProject object, holds a collection of Reference objects. The Reference 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 References object does not contain the Web references of a project. A project's Web references may be retrieved by accessing the ProjectItems property of the WebReferencesFolder property.
The Imports object contained by the VSProject 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 VSProject.Imports property will return Nothing when applied to a Visual C# project. For more information, see Imports Object.
VSProjectItem and BuildManager Objects
The VSProjectItem object is the project item counterpart of the VSProject object. In the general extensibility model, a project item is represented by the generic ProjectItem object. The ProjectItem.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:
' Macro editor Dim pi As VSProjectItem pi = CType(DTE.Solution.Projects.Item(1).ProjectItems.Item(1).Object, _ VSProjectItem)
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. For a complete list of the properties for each object see:
- Properties Property (Visual Basic and Visual C# Project Object)
- Properties Property (Visual Basic and Visual C# Configuration Object)
- Properties Property (Visual Basic and C# ProjectItem Object)