TFS 2008: A basic guide to Team Build 2008


Patrick Carnahan, a developer on Team Build, put together the following guide to the basic, as well as a few advanced, features of Team Build in TFS 2008.  It’s a great way to get started with continuous integration and other features in TFS 2008.


Team Build – Continuous Integration


One of the new and most compelling features of Team Foundation Build is the out-of-the-box support for continuous integration and scheduling. A few in-house approaches have been built around the TFS Soap Event mechanism, most likely set to listen for check-in events and evaluating whether or not a build should be performed. The disadvantages to this approach are the speed and accuracy at which build decisions may be made.

For all of the following steps, it is assumed that the ‘Edit Build Definition’ dialog is currently active. To activate this dialog, expand the ‘Builds’ node of the team project to which your V1 build type belongs (or to which you want to add a new V2 build definition) and click on ‘Edit Build Definition’ as shown below.



Setting up the workspace


Setting up a workspace is pretty important to the continuous integration build, since this is how the server determines when to automatically start builds on your behalf. Although the default workspace mapping is $/<Team Project Name> -> $(SourceDir), something more specific should be used in practice. For instance, in the Orcas PU branch you should use (at a minimum) the mapping $/Orcas/PU/TSADT -> $(SourceDir).

What is this $(SourceDir) variable? Well, in V1 the build directory was specified per build type, meaning that the build type was built on the same directory no matter what machine the build was performed on. In V2 we have separated out the idea of a build machine into a first-class citizen called a Build Agent; this is where the build directory is stored. The variable $(SourceDir) is actually a well-understood environment variable by Team Build, and is expanded to: <BuildAgent.BuildDirectory>\Sources (more on the Build Directory and environment variables later). Typically you will want to make use of $(SourceDir) and keep everything relative to it, but there is no restriction that forces this upon you.

Just so we’re on the same page with the workspace dialog, a picture has been included below. Those of you familiar with version control workspaces should feel right at home!


Already have a workspace ready to go? Simply select the ‘Copy Existing Workspace’ button to search for existing workspaces to use as a template. The local paths will be made relative to $(SourceDir) automatically!

Defining a Trigger


The trigger defines how the server should automatically start builds for a given build definition.

http://blogs.msdn.com/photos/buckh/images/1623211/original.aspx

The first option should be self-explanatory, and keeps the build system behaving just like V1 (no automatic builds). The other options are as follows.


  • The ‘Build each check-in’ option queues a new build for each changeset that includes one or more items which are mapped in a build definition’s workspace.

  • ‘Accumulate check-ins’, otherwise known as ‘Rolling Build’, will keep track of any checkins which need to be built but will not start another build inside of the defined quiet period. This option is a good way to control the number of builds if continuous integration is desired but you want a maximum number of builds per day (e.g. 12 builds per day, which would require a quiet period of 120 minutes) or your builds take much longer than the typical time between checkins.

  • Standard scheduled builds will only occur if checkins were made since the previous build. Don’t worry about this rule affecting the first build, however, because the system will ensure that the first build is started right on time.

  • Scheduled builds can optionally be scheduled even if nothing changes. This is useful when builds are dependent on more than what is in version control.

Drop Management


One of the side effects of a continuous integration system is that a greater number of builds will be created. In order to manage the builds and drops created through CI we have introduced a feature in Team Build called drop management.


Drop management is enabled through a concept we call Retention Policy in Team Build, which allows you to define how many builds to retain for a particular build outcome. For instance, you may only want to keep the last 5 successful builds and only one of any other kind. Through retention policy you can define this by setting the appropriate values in the dialog shown above and the server will manage the automatic deletion of builds for you.

What if you don’t want a build to be susceptible to automatic deletion? We have an option available on individual builds if you would like to retain a build indefinitely (it just so turns out that this is what the menu option is called). To do this go to the ‘Build Explorer’ in Visual Studio 2008 (available by double clicking a node under the Builds node in the Team Explorer window), right click on the build, then select ‘Retain Indefinitely’. Once this option has been toggled on you will see a padlock icon next to the build.


If you decide that the build is no longer useful, simply toggle the option off for the build and let drop management take care of the build automatically.

Advanced Topics


1. Automated UI Tests


Automated UI tests cannot be run in the build agent running as a windows service since it is not interactive, meaning that it cannot interact with the desktop. So, we have provided the ability to run an interactive instance of the service out-of-the-box!

The first thing you will need to do is create a new build agent on the server. To do this you should right click on the ‘Builds’ node for your team project, then click ‘Manage Build Agents’. Once this dialog comes up, click the ‘Add’ button which will bring you to the dialog below.


The display name can be anything descriptive you want. For instance, if the machine name is ‘BuildMachine02’ you may choose to name the build agent ‘BuildMachine02 (Interactive)’ so you can easily differentiate between the interactive and non-interactive agents. The computer name should be the computer name of the machine on which the build service resides, and the port should be changed to 9192 since it is the default interactive port. When changing the port you may see a dialog with the message below, which may be safely disregarded in this case since you’ll be using the default interactive port.


TF226000: After you change the port that is used by Team Foundation Build, you must also update the build service on the build computer to use the new port. For more information, see http://go.microsoft.com/fwlink/?LinkId=83362 .


In order to run the build service in interactive mode just start a command-prompt on the build computer in the directory %PROGRAMFILES%\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies (if you do not want to run the build agent service as yourself then you need to be sure to spawn the command-prompt as the correct user using the ‘runas’ command). Now that you’re in the directory as the appropriate user all you need to do is type ‘TFSBuildService.exe’, which will output something similar to the following:




C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies>TFSBuildService.exe

Press the Escape key (Esc) to exit…


Once you see that prompt your interactive agent is ready to go. You’ll need to leave that command running. Be sure that any time you need to run automated UI tests that you target the correct agent!

2. Build Directory Customization

In TFS 2005, you were able to specify the root build directory which should be used in the build type definition file TfsBuild.proj. During the build, the root build directory would automatically get expanded to:


<Root Build Directory>\<Team Project Name>\<Build Type Name>


This was not configurable and was done this way to ensure uniqueness across build types being built on the same machine. The sources, binaries, and build type were then brought into sub folders named ‘Sources’, ‘Binaries’, and ‘BuildType’, respectively. Since the names could get quite long, there were quite a few issues with path name length errors which were unavoidable.

In TFS 2008 we have made it easier to customize the build directory on the agent through the use of 2 well-known environment variables.


$(BuildDefinitionPath), which expands to <TeamProjectName>\<DefinitionName>

$(BuildDefinitionId), which is the unique identifier by which the definition may be referenced (an Int32)


The build directory is no longer guaranteed to be unique by the system automatically unless one of these two variables is used. This approach has some great advantages, especially since $(BuildDefinitionId) is merely an Int32 and will definitely reduce the length of paths at the build location!

There is another method by which this path may be reduced even more if the source control enlistment requires it. If you take a look at the file %PROGRAMFILES%\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies\TfsBuildService.exe.config on the build computer, you will see some settings which may be of interest to you.


<add key=”SourcesSubdirectory” value=”Sources” />

<add key=”BinariesSubdirectory” value=”Binaries” />

<add key=”TestResultsSubdirectory” value=”TestResults” />


These control the name of the sub-directories which will house the Sources, Binaries, and TestResults. If you need an even shorter path, you could name the sources sub directory ‘s’!

NOTE: Be sure to restart the team build service ( the Windows service or the interactive service, as needed) after making changes to this file in order for the changes to take effect!

3. Port Configuration

For Orcas we have changed the communication method for the build agent (the build agent is the service installed and running on the build computer). In TFS 2005 the Team Build Server communicated with the build machines via .NET Remoting. In TFS 2008 we changed this to use SOAP+XML over HTTP, just like the other Team Foundation services. In order to do this, we have switched to using Windows Communication Foundation self-hosting functionality to expose the service end-point without requiring Internet Information Services (IIS) on the build computer. There is a new series of steps which must be followed in order to change the port for an existing TFS 2008 build agent.


  1. Disable the build agent on the server using the ‘Manage Build Agents’ option in Visual Studio 2008 described above. This will keep the server from starting new builds on the machine, but will let existing builds finish. This way you do not accidentally stop an in-progress build from finishing.

  2. Once there are no builds running, issue a ‘Stop’ command to the build Windows service, either using the Windows Services control panel or from the command line using the “net stop vstfbuild” command.

  3. Navigate a command prompt to the directory %PROGRAMFILES%\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies.

  4. Open the file TFSBuildService.exe.config, and look for a child element in the <appSettings> section with the key=”port” (case sensitive!). Change the value of that key to the desired port and remember the value for the next step.

  5. In the same directory there will be an executable named wcfhttpconfig.exe. This will ensure that the appropriate URL ACLs are in place to allow the service account to listen for incoming HTTP requests. The command you should issue is: ‘wcfhttpconfig reserve <domain>\<user name> <port number>’. You must run this command as a local administrator.

  6. Now issue a ‘Start’ command to the window service. 

  7. Change the status of the build agent back to ‘Enabled’ using the ‘Build Agent Properties’ dialog and click ok.

You can find the official docs on MSDN at How to: Configure an Interactive Port for Team Foundation Build.


NOTE: Changing the port of the Interactive Service is exactly the same as the instructions above with one exception: the appSettings key you will need to modify is ‘InteractivePort’.


[UPDATED 9/07/07]  I’ve added links to the official docs on changing the port.


Comments (33)

  1. Check out Buck’s post written by Patrick Carnahan summarizing the key features available in Team Build

  2. Check out Buck&#39;s post written by Patrick Carnahan summarizing the key features available in Team

  3. Stuart Preston on VSTS: "No Commands Available" in Source Control Explorer a.k.a. "everything is greyed…

  4. Bonjour à toutes et à tous Les ateliers de Microsoft sur VSTS 2005 sont très bien fait, mais ne sont

  5. I picked up the blog post written by Buck Hodges today about some of the new features related to Build

  6. Johan's Blog says:

    I picked up the blog post written by Buck Hodges today about some of the new features related to Build

  7. StevenIBSI says:

    Is there a way to set up a build Trigger so that a build will not occur until there is not check-in activity for at least x minutes.

    This way if multiple users are doing checkins the build will not happen until everyone is done checking in.

    Thanks

    – Steven

  8. StevenIBSI says:

    So it appears if I set the "Accumlate check-ins ntil the prior build finishes and then Check Build no more often than every 15 minutes it almost does what I wanted.  

    But the problem is that the very first check-in started a build, then all the subsequent checkins were included in a build 15 minutes later. So I wanted all the check-ins in 1 build and they got split between two build.

    I would like another checkbox labeled;

    "Wait for X minutes after the last check-in before starting the build."

    so then my "group" of check-ins would all be in the same build.

    Thanks

    – Steven

  9. buckh says:

    Steven, I see what you mean.  When we designed the feature, we looked at it from the perspective that you might be the only person checking in and would therefore like the build to be kicked off immediately rather than having 15 minutes of dead time.

    How often do you have multiple people checking in during a short window where you want them all built together vs. individuals checking in periodically but not so close together?

    Thanks for the feedback.

    Buck

  10. Buck Hodges says:

    Dave McKinstry has written a couple of posts on his experiences with Team Build in TFS 2008. In Introduction

  11. Steve says:

    CruiseControl has a notion of a delay after a checkin before the build kicks off; I think that would address StevenIBSI’s concern (which I share).  Let me say that builds will not kick off for x seconds (default 0) after a checkin, and keep everything else you have as-is.  I think a common scenario would be to set this to 60 seconds or so, which would let one developer do a few checkins or several developers check in related work.

  12. buckh says:

    Steve, since we’ve heard this several times from former CC.NET users, we’ll consider this for the next release after TFS 2008 (Rosario).

    Buck

  13. Arturo Rojas Rodriguez says:

    I would like if you can send me technical information for learning TFS 2008: A basic guide to Team Build 2008. Please, send information to:

    Arturo Rojas Rodriguez

    Systems Engineer

    C#, .Net and Sqlserver developer

    Calle 25C No. 33-07, Piso 3.

    Bogota D.C., Colombia

  14. [update 15/11/7 to add JScript syntax checking, JSON-Enabled WCF, MFC Vista Common Controls links] Here’s

  15. If you are creating multiple build types, i.e. daily, weekly, continuous and others for a Team Project

  16. In the previous build post TFS Build &quot;Workspace already mapped&quot; Issue we covered a common build

  17. Kevin Plotner says:

    I’ll be setting this up in a virtual environment ASAP. Just finished VSTS/TFS.

  18. rakesh says:

    Hi.

    I have set up the Build server – app. server and Data tier.

    But when i process the build it fails, although the files related to build are put in the build server shared file path.and the status of build  is failed. i don’t know the exact reason.

    and one more thing is that..can u any one tell me what is build server and build agent. how to install build agent.?

  19. buckh says:

    Rakesh, you’ll need to run the setup for it under the Build folder on the DVD, if I remember correctly (there should be instruction in the TFS Installation Guide).

    For debugging issues with build, I’d recommend the build MSDN forum.

    http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=481&SiteID=1

    Buck

  20. MrEd says:

    Been reading for an hour and I haven’t found this one from anybody else.  My build was set to run nightly on weekdays at 10pm, by the previous SCM.  I unclicked Friday as I do not intend to come in on the weekend to check these builds.  (I know, "noobies have no dedication to the craft") I set it to run on Sundays, so I would have a build on Monday mornings.  The first week I had some run, some not.  A little research and I see the "run even if no checkins" is OFF.  I reset it to ON and schedule a build in 10 minutes.  It does not run.  That night -Thursday- no build but -Friday – Saturday – Sunday  the build runs at 10pm.  I am looking at a list of days built and days skipped and it is skipping every Wednesday and Thursday and building on Friday and Saturday.  My local calendar is accurate.  What do I need to clear and reset?

  21. buckh says:

    MrEd, the first day always depends on what you are doing.  If the scheduled build has already run (or the server has already determined there was nothing to do) based on prior settings, changing the time will not queue another one.  To do that, change the trigger to none, click OK to close the dialog and save the change to the server, then bring the dialog back up and change it to scheduled with a time 10 minutes into the future.  By changing the trigger to something different and then back again, you clear out all state with respect to the schedule.  This is done so that you can go change the time for a scheduled build without triggering one every time you change the time.

    Regarding Friday vs. Saturday, you may be hitting the issue described in the following thread: http://social.msdn.microsoft.com/Forums/en-US/tfsbuild/thread/b57f639c-3304-4129-9d0f-8b5edf25a1a2.

    Buck

  22. MrEdxoxo says:

    I see what you are saying about new builds scheduled on the same day, but my builds are scheduled for 10pm.  The new test build was scheduled for 10:15am the next day.  "Build despite no changes" was checked.  This being the first failure, I suspect I am dealing with the refusal to build on Thursday after failing on Wednesday.  

    That brings us back to the calendar slip.  The known bug is similar, but different enough that I do not even suspect the same root cause.  My problem is not an extra Friday poping up, but the whole week slipping 2 days back (or 5 days forward).  The build is supposed to be OFF of Fri and Sat, but it is skipping Wed and Thr instead.  The refusal to build on Thursdays would explain the failure to build the test build at 10:15am.  The day following the first failure, would have been Thursday.

    I have gone into my 2 build definitions and changed them.  The first I reset to Monday only and then clicked Save All and closed.  I then reopened it and reset the correct days.  The second build I opened, reset to Monday, closed, reopened and reset the correct days.  I will leave them and see how they run this week.

  23. MrEdxoxo says:

    UPDATE:

    Clearing the schedule and resetting it and saving the changes made no difference in either method.  Both of my nightly builds refused to run on Wednesday and Thursday.  I will wager any sum that they run Friday and Saturday even though those days are turned OFF in the checklists.  I am considering renaming the build server HAL.  Sometimes it is easier to conform to the reality.  Monday I will turn all days on and see what it HAL wants to do.

  24. Jason says:

    Hi Mr Ed (or should I call you Dave ;)

    Could we continue digging into this by opening a forum post. I want to help, but communicating thru Buck’s blog is a little cumbersome. Here is a link to the Team Build forum: http://social.msdn.microsoft.com/forums/en-US/tfsbuild/threads/

    Thanks,

    Jason

  25. Jerry Mcquire says:

    It is possible to have a build definition in different team projects. You can queue these build definitions. When that happens two builds can run both (in parallel). When both builds start unit testing (with code coverage), the both use VSPerfMon. It seems that there might be only one VSPerfMon process alive. How does the build handle this scenario?

  26. buckh says:

    Jerry, I think it may be a limitation of VSPerfMon that it cannot handle this scenario.

    Buck

  27. jcorker says:

    Hi, are there any known problems with setting the build no more often than every # minutes?  I have tried setting this to 120, I get around two builds out of it in a day and then realise a week later it has not been doing integration builds since.

    The downside to not having this is our builds get queued up and they are not quick so you can be waiting hours for them all to run through.

    Thanks,

    John

  28. buckh says:

    John, there’s a bug in the RTM version of 2008 that was fixed in TFS SP1 where accumulation intervals greater than 59 minutes do not work.  Installing TFS SP1 for 2008 on your server should fix the problem.

    TFS SP1 download: http://www.microsoft.com/downloads/details.aspx?FamilyId=9E40A5B6-DA41-43A2-A06D-3CEE196BFE3D&displaylang=en

    Buck

  29. vishrut says:

    Hi,

    I need a small help from you regarding a new requirement in our project for TFS Build.

    When we are deploying the builds from Build server to Dev server, we want to take back up of existing files on Dev server.Currently we take bakcup by manually copying the files before deploying the build.These files will be replaced with new files when builds will be deployed.

    We want something like this in TFSBuild.proj file. Step1 we should take backup of files (deployed by earlier build)at some other location in dev node.

    Step 2 We should make the builds and have the builds ready in Build server.

    Step 3 We should push/deploy build/files to Dev Server. (At present we do Step 2 and Step 3 only)

    The major problem we are facing is that the place where we deploy our files in Dev server is a folder where many other files and folders are also present. This folder is common folder for many other builds/apps.

    Now if we want to achieve the thing I have discussed above,I have one approach here.

    since we maintain a list of files and folders with there paths to be backed up in a text file, we can use this file with ReadLinesFromFile Task and can take the backup of files and folders specified in the text file to our backup location.

    Please suggest me if you have any other idea.

    to me,I want the collection of files and folders being copied to dev/QA server from Build server as a part of build process. It would be great if you could help me here. I am in dire need of solution.

    you can mail me at vishrut.104@gmail.com or vishrut.singh@ef.com

  30. buckh says:

    Vishrut,

    To get the file list before the build drops, you’d have to write a file logger for msbuild and hook the appropriate events, which is probably not worth the effort to get it right.

    Also, the current build may have different files in it than the previous build.

    What if as part of the current build you save a list that you create as part of AfterDropBuild, and that list, such the CSV file you describe, would describe the build accurately?  Prior to deploying the new build, you could grab that list from a known location, which would be the list for the previous build, do the backup that you need, then deploy and update the file list in the known location.  If I understand what you’re after, I think that or something along those lines may give you a reasonably simple solution.

    Buck

  31. TabbyCool says:

    We are using Team Build 2008 to run a continuous integration build, but I was wondering, is it possible to run a build on my local machine before checking in?  If my changes are going to break the server build, I’d rather detect this and avoid breaking anything on the server – is there a way of running or emulating a Team Build project on my local machine, or can this only be done on the TFS server?

    Thanks

  32. buckh says:

    TabbyCool, what are describing is a feature we call gated checkin that we have built into 2010.  You can either go with full gated checkin where are checkins are queued to be built and only checked in if the build is successful, or you can submit a "buddy build" which is a build with a shelveset specified.

    2010 beta 2 will be available very soon.  It will have a go-live license (meaning that you can use it in production).

    If you need a solution for 2008, I’d recommend that you check out the BuddyBuild project on CodePlex: http://buddybuild.codeplex.com/.

    Buck