Team Build Object Model - Queueing a Build

  • Article

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!

Comments

  • Anonymous
    April 25, 2007
    I just read Aaron's post "Team Build Object Model - Queueing a Build" and I just had convert his code
  • Anonymous
    April 27, 2007
    Notion Solutions announces eTraining for Team System. Kannan on TFS Reporting Simplified. Brian Harry...
  • Anonymous
    February 13, 2008
    The documentation for the team build 2008 object model is now available as a CHM file. Later this year,
  • Anonymous
    February 18, 2008
    At code camp i mentioned build as one of the areas in TeamSystem with the most enhancements was Build-
  • Anonymous
    February 18, 2008
    At code camp i mentioned build as one of the areas in TeamSystem with the most enhancements was Build
  • Anonymous
    December 26, 2008
    I had only one problem with new TFS 2008 API. I couldn't get if build server process some build at the moment or not. Previous version had mechanism like:               string uri = string.Format("tcp://{0}:{1}/{2}", server, "9191", typeof(Microsoft.TeamFoundation.Build.Common.IBuildAgent).FullName);               Microsoft.TeamFoundation.Build.Common.IBuildAgent agent = (Microsoft.TeamFoundation.Build.Common.IBuildAgent)Activator.GetObject(                   typeof(Microsoft.TeamFoundation.Build.Common.IBuildAgent), uri);               if (agent.Status == AgentStatus.Initializing)               {                   return "InProgress";               }               else               {                   return "NotRunning";               }Don't you know it's new implementation?
  • Anonymous
    December 29, 2008
    The new version would involve querying for queued builds on the relevant agent.  As of SP1, you should be able to do something like:IQueuedBuildSpec spec = BuildServer.CreateBuildQueueSpec("TeamProject");spec.AgentSpec.Name = "DesiredAgentName";spec.Status = QueueStatus.InProgress;IQueuedBuildQueryResult queryResult = BuildServer.QueryQueuedBuilds(spec);This assumes that you've already retrieved an IBuildServer into the BuildServer variable, that your Team Project is called "TeamProject", and that the agent you are interested in is named "DesiredAgentName".  You can inspect the Builds property of the query result to determine whether there were any in progress builds on the agent.For RTM it is a bit more complicated, since we didn't expose the QueryQueuedBuilds method directly in the OM.  Instead, you would need to create an IQueuedBuildsView, set the appropriate filters on it, call Refresh, and then inspect the contents of the queue.