Automating Builds and Configurations in Visual Studio .NET
Visual Studio Team
Summary: This article provides information about how to use the Microsoft® Visual Studio® .NET Automation model to automate solution and project builds and build configurations. (9 printed pages)
The Solution and Project Automation Build Model Objects
Manipulating Build Configurations
Solution Build Configurations
Project Build Configurations
Initiating Solution and Project Builds
Project Build Dependencies
Defining the Startup Project
When you build a project or a solution in Visual Studio .NET, it is built according to the build configuration associated with it. Ordinarily, you build a solution or project manually by using the integrated development environment (IDE); however, the Visual Studio .NET Automation model contains objects that allow you to programmatically alter build configurations and perform build operations.
Using the Build model, you can choose the projects you want to build and exclude those that you do not want to build. In addition, by using build configurations, you can determine how the projects you select will be built. Two types of build configurations can be defined in Visual Studio: solution and project. Using the SolutionBuild object, you can programmatically run, debug, build, and deploy a solution or selected project.
The ability to programmatically control build configurations and project and solution builds can be useful for creating unattended builds, automated test suites, and batch jobs. Using the Build model, you can, among other things:
- Create, activate, and delete solution configurations.
- Build, run, or deploy any or all projects in a solution configuration.
- Obtain information about objects within a project or solution configuration.
- Add, remove, or obtain information about project build dependencies.
Most of the members of the solution and project build objects in the Visual Studio .NET Automation model mirror the commands in the Visual Studio .NET IDE. For example, the SolutionBuild object contains members that equate to commands on the Build menu such as Build Solution, Rebuild Solution, Build Project, and Rebuild Project.
For details about how solution and project build configurations work and are set in the IDE, see Builds During Application Development and Build Configurations in the Visual Studio product documentation.
The objects and collections in the Visual Studio .NET Automation Build model that allow you to modify solution and project build configurations and dependencies, as well as programmatically initiate builds, are:
|BuildDependency object||Represents a project that must be built before the owning project can be built.|
|BuildDependencies collection||Contains all of the projects that must be built before the owning project can be built.|
|Configuration object||Represents a project configuration, or set of build settings. For example, the Debug project configuration for the .NET Platform.|
|Configurations collection||Contains all of the project configuration objects.|
|ConfigurationManager object||Represents build configuration and platforms.|
|OutputGroup object||Contains the files that are built by the project.|
|OutputGroups collection||Contains all of the OutputGroup objects.|
|SolutionBuild object||Used to build, clean, and deploy the currently active Solution Configuration.|
|SolutionConfiguration object||Represents a list of projects and their configurations that are to be built.|
|SolutionConfigurations collection||Contains all of the defined SolutionConfiguration objects.|
|SolutionContext object||Represents the build context for each project in a SolutionConfiguration object.|
|SolutionContexts collection||Contains all of the SolutionContext objects in a SolutionConfiguration object, one for each project.|
In the Visual Studio .NET Automation model, the objects and collections relate hierarchically to each other in the following way:
For a detailed map of the entire Visual Studio .NET Automation model, see Automation Object Model Chart in the Visual Studio product documentation.
For information about the available configurations and project contexts, see Configuration, Configuration Properties, Solution Property Pages Dialog Box.
There are two different types of build configurations: solution and project. The following sections outline how to programmatically create and manipulate each one.
A solution build configuration specifies how certain projects in a solution are to be built and, if enabled, deployed. Solutions have two default build configurations: Debug and Release. Using the Configuration Manager dialog box, you can create new solution configurations, delete configurations, or edit existing ones. You can also use the SolutionConfiguration object to programmatically accomplish this. The following VSMacro example demonstrates how.
Sub SolutionConfigurationExample() ' Sets the Solution Configuration to "Release." Dim SolnCfg As SolutionConfiguration = DTE.Solution. _ SolutionBuild.SolutionConfigurations.Item("Release") ' Remove remark on the next line to delete the currently selected ' configuration. NOTE: You cannot delete the last soln. configuration. 'SolnCfg.Delete() ' Creates a new solution configuration based on the existing "Debug" ' build config. You must base it on an existing one. DTE.Solution.SolutionBuild.SolutionConfigurations.Add("NewSolnCfg", _ "Debug", False) ' Activates the specified solution configuration, in this case, ' "NewSolnCfg." SolnCfg = DTE.Solution.SolutionBuild.SolutionConfigurations. _ Item("NewSolnCfg") SolnCfg.Activate() End Sub
A solution context is the row of settings that displays in Configuration Manager dialog box for the solution; that is, Project, Project Configuration, Platform, and whether it builds. A SolutionContext object represents this row of property values, and the SolutionContexts collection contains all of the rows for that solution configuration.
The following example lists all of the solution context values for every project in the "Debug" solution configuration.
Sub SolnCtx() ' Choose the "Debug" solution configuration. Dim SolnCfg As SolutionConfiguration = DTE.Solution. _ SolutionBuild.SolutionConfigurations.Item("Debug") Dim SolnCtx As SolutionContext Dim SolnCtxs As SolutionContexts = SolnCfg.SolutionContexts Dim msg As String ' Lists the solution context values for every project in the solution. For Each SolnCtx In SolnCtxs msg = "Project Name: " & SolnCtx.ProjectName & vbCr msg = msg & "Configuration Name: " & SolnCtx.ConfigurationName & _ vbCr msg = msg & "Platform Name: " & SolnCtx.PlatformName & vbCr msg = msg & "ShouldBuild: " & SolnCtx.ShouldBuild & vbCr msg = msg & "ShouldDeploy: " & SolnCtx.ShouldDeploy & vbCr MsgBox(msg) Next End Sub
Project build configurations are groups of settings for debugging, building, deploying, and so forth. These configuration settings are listed in the Project Property Pages dialog box. You can view this by right-clicking a project in Solution Explorer and choosing Properties. The available Project configuration and platform names display in drop-down boxes at the top of the dialog box.
The Common Properties and Configuration Properties nodes in the dialog box list all of the available project build configuration properties that you can change. For example, to view or change the Build properties, click the Build node under Configuration Properties. When you make a setting change and then choose OK, the settings for that particular configuration name and platform name are saved. Using objects in the Visual Studio .NET Automation model, you can programmatically manipulate project build configuration settings.
For more information about how build configurations work and how to create them, see Default and Custom Builds.
The following VSMacro example demonstrates how to change the value of a setting in a project's build configuration.
Sub ProjConfig() ' This example shows how to change the boolean value of the Define ' Trace Constant setting in the specified Project's build ' configuration. This example requires that you have a project loaded. Dim Proj As Project = DTE.VBProjects.Item(1) MsgBox("Project name: " & Proj.Name) MsgBox("Project configuration property to change: " & Proj. _ ConfigurationManager.ActiveConfiguration.Properties.Item(3).Name) MsgBox("Current value: " & Proj.ConfigurationManager. _ ActiveConfiguration.Properties.Item("DefineTrace").Value) Proj.ConfigurationManager.ActiveConfiguration.Properties.Item _ ("DefineTrace").Value = True MsgBox("New value: " & Proj.ConfigurationManager. _ ActiveConfiguration.Properties.Item("DefineTrace").Value) End Sub
Another way to manipulate project configuration properties is by using the ConfigurationManager object. The following example shows how to do this.
Sub CfgMgrExample() ' This shows how to set a project configuration property using the ' ConfigurationManager object. Dim Proj As Project = DTE.VBProjects.Item(1) Dim msg As String msg = "Project name: " & Proj.Name & vbCr msg = msg & "Project property name: " & Proj.ConfigurationManager. _ Item(1).Properties.Item(1).Name & vbCr msg = msg & "Project property value: " & Proj.ConfigurationManager. _ Item(1).Properties.Item(1).Value & vbCr MsgBox(msg) msg = "" Proj.ConfigurationManager.Item(1).Properties.Item(1).Value = False msg = "Project name: " & Proj.Name & vbCr msg = msg & "Project property name: " & Proj.ConfigurationManager. _ Item(1).Properties.Item(1).Name & vbCr msg = msg & "Project property value: " & Proj.ConfigurationManager. _ Item(1).Properties.Item(1).Value & vbCr MsgBox(msg) End Sub
Using the Visual Studio .NET Automation model, you can programmatically execute solution and project builds. The primary object for doing this is the SolutionBuild object. Using this object, you can:
- Build a solution by calling the Build method of the SolutionBuild object.
- Build a particular project within a solution by calling the BuildProject method.
- Initiate a debug build of the solution by calling the Debug method.
- Deploy certain projects in a solution by calling the Deploy method.
- Execute the designated Start Project by calling the Run method.
Various properties of the SolutionBuild object also allow you to access:
- The active configuration (that is, the current solution configuration that will be used if a solution build operation occurs).
- Build dependencies (that is, which projects depend on which others to build properly).
- The build state (that is, whether a build has ever been started in the current environment session, whether a build is currently in progress, or whether a build has been completed).
The SolutionBuild object also contains a Clean method that, when called, removes compiler-generated support files from projects that are marked to build in the active solution configuration. Other SolutionBuild properties are available as well. For a complete list, see SolutionBuild Object Properties, Methods, and Events.
The following example demonstrates how to initiate a build of the current solution configuration. This example assumes that you have a build configuration called "MyBuildConfig."
Sub SolutionBuildExample() ' Build the active solution configuration. Dim sb As SolutionBuild = DTE.Solution.SolutionBuild sb.SolutionConfigurations.Item("MyBuildConfig").Activate sb.Build End Sub
The following example demonstrates how to initiate the building of a particular project and its dependencies within a solution. This example assumes that you have a build configuration called "MyBuildConfig" and that your current solution has a project called "ConsoleApplication1."
Sub ProjectBuildExample() ' Build the specified project in the solution. Dim sb As SolutionBuild = DTE.Solution.SolutionBuild sb.BuildProject("MyBuildConfig", "ConsoleApplication1", False) End Sub
Note The WaitForBuildToFinish flag determines whether Build retains control until the build operation is complete. The default value is False. If you set WaitForBuildToFinish to False — that is, control returns immediately after initiating a build — you can use the BuildDone event to determine when the build is complete.
The Visual Studio .NET build configuration model also allows you to define a build dependency between two projects by using the BuildDependencies property. The following is an example of how to make Project1 dependent on Project2 so that Project2 must build first when building the solution.
Sub BuildDependenciesExample() ' Make Project 1 dependent upon Project 2. Dim p1 As Project = DTE.Solution.Item(1) ' Project 1 Dim p2 As Project = DTE.Solution.Item(2) ' Project 2 Dim sb As SolutionBuild = DTE.Solution.SolutionBuild sb.BuildDependencies.Item(p1.UniqueName).AddProject(p2.UniqueName) End Sub
The Startup Project defines the project that will run when you start the Visual Studio debugger. Using the StartupProjects property of the SolutionBuild object, you can programmatically define this setting.
Note The StartupProjects collection in the current version of Visual Studio .NET allows you to set only a single startup project, but future versions will allow multiple startup projects.
The following example demonstrates how to view the current startup project and change it.
Sub StartUpProj() ' This example requires the presence of two projects in the solution. Dim sb As SolutionBuild = DTE.Solution.SolutionBuild Dim p1 As Project = DTE.Solution.Item(1) ' Project 1 Dim p2 As Project = DTE.Solution.Item(2) ' Project 2 MsgBox("Current startup project: " & sb.StartupProjects(0)) ' Change the startup project to a different project. sb.StartupProjects = p1.UniqueName MsgBox("New startup project: " & sb.StartupProjects(0)) End Sub
The Visual Studio .NET Automation Build model offers a number of options for programmatically controlling your solutions and projects and their build configurations. To become more familiar with how the Visual Studio .NET Automation Build model relates to the IDE, browse the objects listed in "The Solution and Project Automation Build Model Objects" with the Object Browser and compare their members to the various dialog boxes. Experiment with the model to become familiar with how it works. You can also check out the "PrePostBuildRules Add-In" sample on the Visual Studio .NET Automation samples Web site: http://msdn.microsoft.com/vstudio/downloads/samples/automation.aspx.