Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Automating Builds and Configurations in Visual Studio .NET

Visual Studio .NET 2003
 

Kemp Brown
Visual Studio Team
Microsoft Corporation

February 2002

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)

Contents

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
Conclusion

Introduction

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 Solution and Project Automation Build Model Objects

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:

Object Name Description
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:

DTE

   SolutionBuild

      BuildDependencies

         BuildDependency

   SolutionConfigurations

      SolutionConfiguration

         SolutionContexts

            SolutionContext

   Project

      ConfigurationManager

         Configurations

            Configuration

               OutputGroups

                  OutputGroup

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.

Manipulating Build Configurations

There are two different types of build configurations: solution and project. The following sections outline how to programmatically create and manipulate each one.

Solution Build Configurations

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

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

Initiating Solution and Project Builds

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.

Project Build Dependencies

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

Defining the Startup Project

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

Conclusion

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.

Show:
© 2015 Microsoft