Team Build Object Model - Queueing a Build

Two of the biggest Team Build changes in Orcas (Beta 1 is now available here) are (a) the addition of an Object Model, and (b) the addition of build queueing.  In Team Build v1, by contrast, the only API available for Team Build was the web service; and only a single build (per Team Project per Build Machine) could be executed at a time - subsequent build start requests just failed.

The basic process for queueing a build is illustrated in the following sample:

 using System;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.Build.Client;

namespace OrcasBlogProjects
{
    class Program
    {
        static void Main(string[] args)
        {
            IQueuedBuild queuedBuild = QueueBuild("https://tfs:8080", "Team Project", "Nightly Build");

            Console.WriteLine(String.Format("Build successfully queued. Position: {0}.", queuedBuild.QueuePosition));
        }

        public static IQueuedBuild QueueBuild(String tfs, String teamProject, String buildDefinition)
        {
            // Get the specified team foundation server.
            TeamFoundationServer tfs = TeamFoundationServerFactory.GetServer(tfs);

            // Get the IBuildServer - the main point of entry to the Team Build OM.
            IBuildServer buildServer = (IBuildServer)tfs.GetService(typeof(IBuildServer));

            // Get the build definition for which a build is to be queued.
            IBuildDefinition definition = buildServer.GetBuildDefinition(teamProject, buildDefinition);

            // Create a build request for the build definition.
            IBuildRequest request = definition.CreateBuildRequest();

            // Queue a build.
            return buildServer.QueueBuild(request, QueueOptions.None);
        }
    }
}

Note the major steps in this process - (1) get the build definition, (2) create a request, and (3) queue the build.  An overload of QueueBuild will be available in Beta 2 that takes a definition directly - when using all default options (see below for more on this), this overload can be used.

Step (1) is fairly straightforward, but even here there are various options available.  The example illustrates obtaining a build definition from the Team Project name and the Definition name.  Another overload of the GetBuildDefinition method takes a build definition URI:

 public IBuildDefinition GetBuildDefinition(
    Uri buildDefinitionUri
)

In addition to the two Get methods, several Query methods are also available for build definitions.  The most interesting for these purposes is the following:

 public IBuildDefinitionQueryResult QueryBuildDefinitions(
    IBuildDefinitionSpec buildDefinitionSpec
)

The returned IBuildDefinitionQueryResult contains an array of matched definitions, and an array of Failures, if any occurred.  The input IBuildDefinitionSpec allows wildcards in its Name property, which allows you to probe a particular team project for build definitions.

Step (2) offers many opportunities for customization.  In particular, the IBuildRequest interface allows you to update many of the defaults for the requested build prior to queueing it.  Settable properties include:

• The build agent for which the requested build is queued.  Build Agents are a new concept in Orcas, but can be thought of as v1 build machines.
• The version for which sources are retrieved for the build.
• The drop location to which binaries and log files are copied when the build is complete.
• The priority of the requested build.  Queue priorities are used in combination with queue times to determine which build should be started on an idle agent when multiple builds are in the queue.
• The user for whom the build is being requested.
• The maximum acceptable queue position - if this position cannot be satisfied, an exception will be thrown.
• Last, but certainly not least, any command-line arguments which should be passed into MSBuild for the requested build.

Contrast this with the properties settable when starting a build in v1 - just the build machine and the build directory. 

Beta 1 does not have a go-live license, but I hope that various folks out there will start downloading the VPCs and experimenting with the new Team Build Object Model - we'd love to get your feedback on it as soon as possible!