“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:

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:

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:

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:

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:

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

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:

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

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:

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:

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:

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:

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:

• The build agent should have a supporting version of Windows. The list of supported versions is listed at https://msdn.microsoft.com/en-us/Library/vs/alm/TFS/administer/requirements#Operatingsystems.
• The build agent should have Visual Studio 2013 or 2015.
• The build agent should have PowerShell 3 or a newer version.

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:

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:

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:

   

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:

   

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:

   

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

   

   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:

   

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

   

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:

   

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

   

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:

   

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

   

   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:

   

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

    

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

    

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

    

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:

    

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:

    

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

    

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:

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:

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:

   

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:

   

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.

   

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:

• Overview of Process Management in Microsoft Visio 2013 [article]
• Introduction to the Raspberry Pi’s Architecture and Setup [article]
• Implementing Microsoft Dynamics AX [article]

---