12 min read

“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.”

                                                               –Bill Gates

In this article, by Tarun Arora, the author of the book Microsoft Team Foundation Server 2015 Cookbook, provides you information about:

  • Configuring TFBuild Agent, Pool, and Queues
  • Setting up a TFBuild Agent using an unattended installation

(For more resources related to this topic, see here.)

As a developer, compiling code and running unit tests gives you an assurance that your code changes haven’t had an impact on the existing codebase. Integrating your code changes into the source control repository enables other users to validate their changes with yours. As a best practice, Teams integrate changes into the shared repository several times a day to reduce the risk of introducing breaking changes or worse, overwriting each other’s.

Continuous integration (CI) is a development practice that requires developers to integrate code into a shared repository several times a day. Each check-in is verified by an automated build, allowing Teams to detect problems early.

The automated build that runs as part of the CI process is often referred to as the CI build. There isn’t a clear definition of what the CI build should do, but at the very minimum, it is expected to compile code and run unit tests. Running the CI build on a non-developer remote workspace helps identify the dependencies that may otherwise go unnoticed into the release process. We can talk endlessly about the benefits of CI; the key here is that it enables you to have potentially deployable software at all times.

Deployable software is the most tangible asset to customers.

Moving from concept to application, in this article, you’ll learn how to leverage the build tooling in TFS to set up a quality-focused CI process. But first, let’s have a little introduction to the build system in TFS. The following image illustrates the three generations of build systems in TFS:

Microsoft Team Foundation Server 2015 Cookbook

TFS has gone through three generations of build systems. The very first was MSBuild using XML for configuration; the next one was XAML using Windows Workflow Foundation for configuration, and now, there’s TFBuild using JSON for configuration. The XAML-based build system will continue to be supported in TFS 2015. No automated migration path is available from XAML build to TFBuild. This is generally because of the difference in the architecture between the two build systems.

The new build system in TFS is called Team Foundation Build (TFBuild). It is an extensible task-based execution system with a rich web interface that allows authoring, queuing, and monitoring builds. TFBuild is fully cross platform with the underlying build agents that are capable of running natively on both Windows and non-Windows platforms. TFBuild provides out-of-the-box integration with Centralized Version Control such as TFVC and Distributed Version Controls such as Git and GitHub. TFBuild supports building .NET, Java, Android, and iOS applications. All the recipes in this article are based on TFBuild.

TFBuild is a task orchestrator that allows you to run any build engine, such as Ant, CMake, Gradle, Gulp, Grunt, Maven, MSBuild, Visual Studio, Xamarin, XCode, and so on. TFBuild supports work item integration, publishing drops, and publishing test execution results into the TFS that is independent of the build engine that you choose. The build agents are xCopyable and do not require any installation. The agents are auto-updating in nature; there’s no need to update every agent in your infrastructure:

Microsoft Team Foundation Server 2015 Cookbook

TFBuild offers a rich web-based interface. It does not require Visual Studio to author or modify a build definition. From simple to complex, all build definitions can easily be created in the web portal. The web interface is accessible from any device and any platform:

Microsoft Team Foundation Server 2015 Cookbook

The build definition can be authored from the web portal directly

A build definition is a collection of tasks. A task is simply a build step. Build definition can be composed by dragging and dropping tasks. Each task supports Enabled, Continue on error, and Always run flags making it easier to manage build definitions as the task list grows:

Microsoft Team Foundation Server 2015 Cookbook

The build system supports invoking PowerShell, batch, command line, and shell scripts. All out-of-the-box tasks are open source. If a task does not satisfy your requirements, you can download the task from GitHub at https://github.com/Microsoft/vso-agent-tasks and customize it. If you can’t find a task, you can easily create one. You’ll learn more about custom tasks in this article.

Changes to build definitions can be saved as drafts. Build definitions maintain a history of all changes in the History tab. A side-by-side comparison of the changes is also possible. Comments entered when changing the build definition show up in the change history:

Microsoft Team Foundation Server 2015 Cookbook

Build definitions can be saved as templates. This helps standardize the use of certain tasks across new build definitions:

Microsoft Team Foundation Server 2015 Cookbook

An existing build definition can be saved as a template

Multiple triggers can be set for the same build, including CI triggers and multiple scheduled triggers:

Microsoft Team Foundation Server 2015 Cookbook

Rule-based retention policies support the setting up of multiple rules. Retention can be specified by “days” or “number” of the builds:

Microsoft Team Foundation Server 2015 Cookbook

The build output logs are displayed in web portal in real time. The build log can be accessed from the console even after the build gets completed:

Microsoft Team Foundation Server 2015 Cookbook

The build reports have been revamped to offer more visibility into the build execution, and among other things, the test results can now directly be accessed from the web interface. The .trx file does not need to be downloaded into Visual Studio to view the test results:

Microsoft Team Foundation Server 2015 Cookbook

The old build system had restrictions on one Team Project Collection per build controller and one controller per build machine. TFBuild removes this restriction and supports the reuse of queues across multiple Team Project Collections. The following image illustrates the architecture of the new build system:

Microsoft Team Foundation Server 2015 Cookbook

In the preceding diagram, we observe the following:

  • Multiple agents can be configured on one machine
  • Agents from across different machines can be grouped into a pool
  • Each pool can have only one queue
  • One queue can be used across multiple Team Project Collections

To demonstrate the capabilities of TFBuild, we’ll use the FabrikamTFVC and FabrikamGit Team Projects.

Configuring TFBuild Agent, Pool, and Queues

In this recipe, you’ll learn how to configure agents and create pools and queues. You’ll also learn how a queue can be used across multiple Team Project Collections.

Getting ready

Scenario: At Fabrikam, the FabrikamTFVC and FabrikamGit Team Projects need their own build queues. The FabrikamTFVC Teams build process can be executed on a Windows Server. The FabrikamGit Team build process needs both Windows and OS X. The Teams want to set up three build agents on a Windows Server; one build agent on an OS X machine. The Teams want to group two Windows Agents into a Windows Pool for FabrikamTFVC Team and group one Windows and one Mac Agent into another pool for the FabrikamGit Team:

Microsoft Team Foundation Server 2015 Cookbook

Permission: To configure a build agent, you should be in the Build Administrators Group.

The prerequisites for setting up the build agent on a Windows-based machine are as follows:

A build agent is configured for your TFS as part of the server installation process if you leave the Configure the build service to start automatically option selected:

Microsoft Team Foundation Server 2015 Cookbook

For the purposes of this recipe, we’ll configure the agents from scratch. Delete the default pool or any other pool you have by navigating to the Agent pools option in the TFS Administration Console http://tfs2015:8080/tfs/_admin/_AgentPool:

Microsoft Team Foundation Server 2015 Cookbook

How to do it

  1. Log into the Windows machine that you desire to set the agents upon. Navigate to the Agent pools in the TFS Administration Console by browsing to http://tfs2015:8080/tfs/_admin/_AgentPool. Click on New Pool, enter the pool name as Pool 1, and uncheck Auto-Provision Queue in Project Collections:

    Microsoft Team Foundation Server 2015 Cookbook

  2. Click on the Download agent icon. Copy the downloaded folder into E: and unzip it into E:Win-A1. You can use any drive; however, it is recommended to use the non-operating system drive:

    Microsoft Team Foundation Server 2015 Cookbook

  3. Run the PowerShell console as an administrator and change the current path in PowerShell to the location of the agent in this case E:Win-A1. Call the ConfigureAgent.ps1 script in the PowerShell console and click on Enter. This will launch the Build Agent Configuration utility:

    Microsoft Team Foundation Server 2015 Cookbook

  4. Enter the configuration details as illustrated in the following screenshot:

    Microsoft Team Foundation Server 2015 Cookbook

    It is recommended to install the build agent as a service; however, you have an option to run the agent as an interactive process. This is great when you want to debug a build or want to temporarily use a machine as a build agent.

    The configuration process creates a JSON settings file; it creates the working and diagnostics folders:

    Microsoft Team Foundation Server 2015 Cookbook

  5. Refresh the Agent pools page in the TFS Administration Console. The newly configured agent shows up under Pool 1:

    Microsoft Team Foundation Server 2015 Cookbook

  6. Repeat steps 2 to 5 to configure Win-A2 in Pool 1. Repeat steps 1 to 5 to configure Win-A3 in Pool 2. It is worth highlighting that each agent runs from its individual folder:

    Microsoft Team Foundation Server 2015 Cookbook

  7. Now, log into the Mac machine and launch terminal:

    Microsoft Team Foundation Server 2015 Cookbook

  8. Install the agent installer globally by running the commands illustrated here. You will be required to enter the machine password to authorize the install:

    Microsoft Team Foundation Server 2015 Cookbook

    This will download the agent in the user profile, shown as follows:

    Microsoft Team Foundation Server 2015 Cookbook

    The summary of actions performed when the agent is downloaded

  9. Run the following command to install the agent installer globally for the user profile:

    Microsoft Team Foundation Server 2015 Cookbook

  10. Running the following command will create a new directory called osx-A1 for the agent; create the agent in the directory:

    Microsoft Team Foundation Server 2015 Cookbook

  11. The agent installer has been copied from the user profile into the agent directory, shown as follows:

    Microsoft Team Foundation Server 2015 Cookbook

  12. Pass the following illustrated parameters to configure the agent:

    Microsoft Team Foundation Server 2015 Cookbook

  13. This completes the configuration of the xPlatform agent on the Mac. Refresh the Agent pools page in the TFS Administration Console to see the agent appear in Pool 2:

    Microsoft Team Foundation Server 2015 Cookbook

  14. The build agent has been configured at the Team Foundation Server level. In order to use the build agent for a Team Project Collection, a mapping between the build agent and Team Project Collection needs to be established. This is done by creating queues. To configure queues, navigate to the Collection Administration Console by browsing to http://tfs2015:8080/tfs/DefaultCollection/_admin/_BuildQueue. From the Build tab, click on New queue; this dialog allows you to reference the pool as a queue:

    Microsoft Team Foundation Server 2015 Cookbook

  15. Map Pool 1 as Queue 1 and Pool 2 as Queue 2 as shown here:

    Microsoft Team Foundation Server 2015 Cookbook

  16. The TFBuild Agent, Pools, and Queues are now ready to use. The green bar before the agent name and queue in the administration console indicates that the agent and queues are online.

How it works…

To test the setup, create a new build definition by navigating to the FabrikamTFVC Team Project Build hub by browsing to http://tfs2015:8080/tfs/DefaultCollection/FabrikamTFVC/_build. Click on the Add a new build definition icon. In the General tab, you’ll see that the queues show up under the Queue dropdown menu. This confirms that the queues have been correctly configured and are available for selection in the build definition:

Microsoft Team Foundation Server 2015 Cookbook

Pools can be used across multiple Team Project Collections. As illustrated in the following screenshot, in Team Project Collection 2, clicking on the New queue… shows that the existing pools are already mapped in the default collection:

Microsoft Team Foundation Server 2015 Cookbook

Setting up a TFBuild Agent using an unattended installation

The new build framework allows the unattended setup of build agents by injecting a set of parameter values via script. This technique can be used to spin up new agents to be attached into an existing agent pool. In this recipe, you’ll learn how to configure and unconfigure a build agent via script.

Getting ready

Scenario: The FabrikamTFVC Team wants the ability to install, configure, and unconfigure a build agent directly via script without having to perform this operation using the Team Portal.

Permission: To configure a build agent, you should be in the Build Administrators Group.

Download the build agent as discussed in the earlier recipe Configuring TFBuild Agent, Pool, and Queues. Copy the folder to E:Agent. The script refers to this Agent folder.

How to do it…

  1. Launch PowerShell in the elevated mode and execute the following command:
    .AgentVsoAgent.exe /Configure /RunningAsService /ServerUrl:"http://tfs2015:8080/tfs" /WindowsServiceLogonAccount:svc_build /WindowsServiceLogonPassword:xxxxx /Name:WinA-10 /PoolName:"Pool 1" /WorkFolder:"E:Agent_work" /StartMode:Automatic

    Replace the value of the username and password accordingly.

    Executing the script will result in the following output:

    Microsoft Team Foundation Server 2015 Cookbook

  2. The script installs an agent by the name WinA-10 as Windows Service running as svc_build. The agent is added to Pool 1:

    Microsoft Team Foundation Server 2015 Cookbook

  3. To unconfigure WinA-10, run the following command in an elevated PowerShell prompt:
    .AgentVsoAgent.exe /Unconfigure "vsoagent.tfs2015.WinA-10"

    To unconfigure, script needs to be executed from outside the scope of the Agent folder. Running the script from within the Agent folder scope will result in an error message.

    Microsoft Team Foundation Server 2015 Cookbook

How it works…

The new build agent natively allows configuration via script. A new capability called Personal Access Token (PAT) is due for release in the future updates of TFS 2015. PAT allows you to generate a personal OAuth token for a specific scope; it replaces the need to key in passwords into configuration files.

Summary

In this article, we have looked at configuring TFBuild Agent, Pool, and Queues and setting up a TFBuild Agent using an unattended installation.

Resources for Article:


Further resources on this subject:



Subscribe to the weekly Packt Hub newsletter. We'll send you the results of our AI Now Survey, featuring data and insights from across the tech landscape.

LEAVE A REPLY

Please enter your comment!
Please enter your name here