Working with Language-Specific Project Objects

The Visual Studio project object model was designed to provide functionality common to all project types. However, some projects can support additional, unique functionality. For example, a Visual C# project has a references node within its project, but a Setup project does not. If you could programmatically add and remove these references, you'd get a lot of flexibility in writing add-ins, macros, and wizards. To enable such project-specific programming, the Visual Studio project object model is extensible, allowing each project type to offer additional methods and properties beyond those defined by the Project object.

You can access the specific object type by using the Object property of the Project object. This property returns an object of type System.Object, which you can convert to the object model type supported by a specific language. The most commonly used project extension is the VSProject object, which is available for the Visual Basic, Visual J#, or Visual C# project types.

VSProject Project

VSLangProj.VSProject is the interface that defines extensions to the EnvDTE.Project object for Visual J#, Visual Basic, or Visual C# projects. Once you've retrieved the EnvDTE.Project interface for one of these project types, you can get to the VSLangProj.VSProject interface by calling the Project.Object property. The following macro code, which assumes that the first project in the Projects collection is a Visual Basic, Visual C#, or Visual J# project, retrieves the VSProject object for that project:

 Sub GetVSProject()     Dim project As EnvDTE.Project     Dim vsproject As VSLangProj.VSProject     project = DTE.Solution.Projects.Item(1)     vsproject = CType(project.Object, VSLangProj.VSProject) End Sub 

References

References are pointers to software components that a project can use to reduce the amount of code a programmer needs to write. A project uses the type of information contained within a reference to display information in the form of IntelliSense® statement completion. A reference also provides information to the compiler for resolving symbols used in programming code. A reference can be an assembly or another project loaded into the solution, and you can create references to COM components by wrapping the COM-object type information library with an interop assembly. You can add references through the user interface by right-clicking on the References node in a Visual Basic or Visual C# project, choosing Add Reference from the shortcut menu, and then selecting a component in the dialog box that appears.

Using the VSLangProj.References object, you can enumerate, add, or remove references. To get to the References object, use the VSProject.References property. For example, the following code retrieves the References object and then enumerates the references that have been added to a project:

 Sub EnumReferences()     Dim proj As EnvDTE.Project     Dim vsproj As VSLangProj.VSProject     Dim references As VSLangProj.References     Dim reference As VSLangProj.Reference     proj = DTE.Solution.Projects.Item(1)     vsproj = proj.Object     references = vsproj.References     For Each reference In references         MsgBox(reference.Name)     Next End Sub 

You add a reference to an assembly by calling the References.Add method and passing the path to the assembly. The Add method copies the assembly into the project output folder unless a copy of the assembly with the same version and public key information is stored in the global assembly cache (GAC). This is done so that, when the project output is run or loaded by another assembly, the correct referenced assembly can be loaded. The following macro code adds a reference to an assembly:

 Sub AddReferenceToAssembly()     Dim vsproj As VSLangProj.VSProject     Dim proj As EnvDTE.Project     proj = DTE.Solution.Projects.Item(1)     vsproj = CType(proj.Object, VSLangProj.VSProject)     vsproj.References.Add("C:\Program Files\Common Files\" & _ "Microsoft Shared\MSEnv\PublicAssemblies\extensibility.dll") End Sub 

This code finds the VSProject object for a project and then adds a reference to the Extensibility.dll metadata assembly—the same assembly that contains the definition of the IDTExtensibility2 interface, which is used for building add-ins. You can't add assemblies located within the GAC as references to a project because the Visual Basic and Visual C# project systems maintain a separation between the files that are referenced for building against and files that are used during a component's run time.

During development, a component that is compiled by one project in a solution might be needed by a component in another project. You can create a reference from one project to another project by using the References.AddProject method. This method accepts a Project object and adds a reference to that project, as shown here:

 Sub AddProjectReference()     Dim vsproj As VSLangProj.VSProject     Dim proj As EnvDTE.Project     'Find the project the reference will be added to:     proj = DTE.Solution.Projects.Item(1)     vsproj = CType(proj.Object, VSLangProj.VSProject)     'Find the referenced project:     proj = DTE.Solution.Projects.Item(2)     'Make the project to project reference:     vsproj.References.AddProject(proj) End Sub 

Adding a reference to a COM object requires values that are COM-centric and might not be very intuitive to the non-COM programmer: the type library GUID, or library identifier (LIBID), of the type library that defines the COM component, and the version major and minor values of that type library. Using these values, you can add a reference to the type library of a COM component. When a reference to a COM library is made, the project system will first check to see if a primary interop assembly (PIA) exists for that COM object. If a PIA is found, the PIA will be added to the list of references. If a PIA is not found, the project will automatically create an interop assembly (IA) for that type library and then add a reference to that IA. The only difference between an IA and a PIA is a value in the system registry, PrimaryInteropAssemblyName, which is located underneath the LIBID and version number for a COM object's type library and points to the .dll file containing metadata describing the types the type library defines. Creating a PIA allows for one assembly file to define all types for one COM object, whereas there can be multiple IAs that handle this interop. If you plan on passing COM interfaces from one .NET program to another through a mechanism such as remoting, you should define a PIA because even though you could generate multiple IAs by wrapping the same type library, the types in one IA are considered distinct from the types in another IA, and an error will be generated. The following macro code adds a reference to the type library for Microsoft Windows Media® Player:

 Sub AddCOMReference()     Dim vsproj As VSLangProj.VSProject     Dim proj As EnvDTE.Project     proj = DTE.Solution.Projects.Item(1)     vsproj = CType(proj.Object, VSLangProj.VSProject)     vsproj.References.AddActiveX( _         "{}", 1, 0) End Sub 

Web References

The .NET Framework not only makes traditional software development easier, but it also makes new software development methodologies possible. One of these new methodologies involves XML Web services. XML Web services enable software development across the Internet by placing software code on a server, which can then be accessed by software that is run on the user's computer. Visual Studio makes connecting desktop software to XML Web services as easy as adding a Web reference. When a reference to an XML Web service is made, a special file written using the Web Services Description Language (WSDL) XML schema is downloaded from the server computer and a proxy class (a class that contains the logic to translate a method or property call from the client computer across the Internet to the server computer) is generated from the WSDL file. This proxy class can then be used to call to the XML Web service.

The following macro adds a Web reference to a project. It retrieves the VSProject object for a project and then calls the AddWebReference method with the URL for the XML Web service. This example uses the TerraServer Web service provided by Microsoft, which offers detailed geographic information and satellite images for the United States. This Web service is located at http://terraserver.microsoft.com/TerraService2.asmx

 Sub AddTerraServerWebRef()     Dim vsProj As VSLangProj.VSProject     Dim serviceURL As String     'Set the URL to the TerraServer web service     serviceURL = "http://terraserver.microsoft.com/TerraService2.asmx"     'Find the VSProject for a project     vsProj = DTE.Solution.Projects.Item(1).Object     'Add the web reference     vsProj.AddWebReference(serviceURL) End Sub 

When this Web reference is made, the WSDL file describing the XML Web service is downloaded from the server computer, and the proxy class for the service is generated and automatically added to the project. This class is placed in a namespace defined by the Web protocol and server name, but in reverse order. So, for example, if the XML Web service were located at http://www.microsoft.com, the namespace for the service would be com.microsoft.www. In this example, TerraServer is located at the server URL terraserver.microsoft.com so the namespace used is com.microsoft.terraserver. Once a reference to an XML Web service has been added to a project, using that service is as easy as calling methods on the generated proxy class.

Imports

To make the programmer's life easier, Visual Basic and Visual C# source code can contain using and Imports statements to shorten the identifiers used to access the namespace defined by a library of code. For example, to display a message box, you could use the longer, more specific identifier to resolve to a class name:

 System.Windows.Forms.MessageBox.Show("Hello World") 

But if this code were repeated a number of times, you'd have to type the namespace identifier over and over, which could lead to programming errors. You can use an Imports statement in Visual Basic to shorten what you have to type:

 Imports System.Windows.Forms 

Later in the program, you can use this shorter form of the code:

 MessageBox.Show("Hello World") 

Visual Basic also allows you to enter Imports statements through a project's Properties window rather than by typing the Imports statement into the source code. By using the project properties dialog box instead of typing the statement into code, you can make the import available for all the files within the project, not just the file that uses the Imports statement. Using the VSProject.Imports collection, you can enumerate, remove, and add imports for the entire project. The following macro adds the System.XML namespace to a Visual Basic project:

 Sub AddSystemXMLImport()     Dim vsProj As VSLangProj.VSProject     vsProj = DTE.Solution.Projects.Item(1).Object     vsProj.Imports.Add("System.Xml") End Sub 

Note 

The Imports object is valid only for the Visual Basic project type. Any attempt to access this object for a Visual C# or Visual J# project will return a null or Nothing value.

ProjectProperties

Each project has a number of options associated with it that allow you to control how you interact with that project. You can set these options under the Common Properties node of a project's Property Pages dialog box. The options include the name of the component that the compiler should build, the kind of project to be generated (an .exe or a .dll), and layout options for the HTML designer. You can also set these options programmatically by using the Properties property of the Project object. This property returns the same Properties object that's used throughout Visual Studio to set options. The following macro walks the list of properties available to a project as well as the values and types of each property:

 Sub WalkVSProjectProperties()     Dim project As EnvDTE.Project     Dim properties As EnvDTE.Properties     Dim [property] As EnvDTE.Property     Dim owp As InsideVSNET.Utilities.OutputWindowPaneEx     owp = New InsideVSNET.Utilities.OutputWindowPaneEx(DTE, _         "Project properties")     project = DTE.Solution.Projects.Item(1)     properties = project.Properties     For Each [property] In properties         owp.WriteLine("Name: " + [property].Name)         owp.WriteLine("Value: " + [property].Value.ToString())         owp.WriteLine("Type: " + [property].Value.GetType().FullName)         owp.WriteLine()     Next End Sub 

You can use this Property object to read the values of properties and to set the properties for a project. The following macro demonstrates this. It sets the icon to use for a project when it is compiled. This code assumes that an icon named Icon.ico is located in the folder containing the project file.

 Sub SetProjectIcon()     Dim project As EnvDTE.Project     Dim [property] As EnvDTE.Property     Dim projectPath As String     project = DTE.Solution.Projects.Item(1)     'Get the Property object for the icon:     [property] = project.Properties.Item("ApplicationIcon")     'Construct the path to the icon based off of the     ' project path:     projectPath = project.FullName     projectPath = System.IO.Path.GetDirectoryName(projectPath)     projectPath = projectPath + "\Icon.ico"     'Set the icon for the project:     [property].Value = projectPath End Sub