How To Create A Build Definition In TFS 2015, Adding Tasks And Setting Build Menu Options

Build Definition TFS -2015

 

In my previous articles, I explained about Build Agent: How to install, configure, and unconfigure a build agent in TFS 2015. To see the previous articles, click here.

In this article, I’ll explain,

• How to create a build definition
• Tasks/Steps used in the build definition.
• Build menu options
• Save build definition
• Queue build
• Options after a successful build

Let’s create a new build definition for a simple web application. And in my next article, I’ll explain about release definition.

Build Definition

A Build definition may be defined as a collection of steps/tasks which can be executed in a sequence as specified while creating a build definition. We can change the sequence of steps added in the build definition by dragging on the desired place of execution. There are various tasks provided for adding in the build definition.

For example, there are tasks available to build, test, deploy. These tasks can be added in the build definition. Below is a screenshot of adding tasks as per your build definition. We can select any number of tasks in the build definition.

 Creating a Build Definition

Step 1 - Select the project

To get started, select the project from projects collection in TFS server and click on the Builds link in Visual Studio Team Explorer. 

 

 

Step 2 - View Builds

 

To create a new build definition Click on New Build Definition option OR View Builds to see all builds created from Visual Studio and you will get the following screen as shown in the below figure.

 

 

It will automatically take you to Web access,

 

 

Step 3 - Create New Build definition

 

You can create a build for Windows or on Linux also as step(s).

Click on the button and select Visual Studio template (This template requires that Visual Studio be installed on the build agent. (To read more about build Agent read here).

With Visual Studio Online definition, templates are also available. You can create your own templates too.

 

• Select Repository
  Select the repository source, you can select the project from team projects, GitHub and SVN.
  
  
   
  
  Check the continuous integration trigger if you want to queue the build on every code check-in.
  
  A continuous integration trigger on a build definition shows that the system should automatically queue a new build whenever a code change is checked-in. We will discuss about this in Triggers tab of build Menu later in this article.
  
  See more on Build triggers.
  
  Then, select the agent queues. Here, I used the default one and click on "Create". A new build definition is created with default Build Steps.
  
  
   
  
  
• Add Build Steps
  
  
    
  
  You can add new tasks included in the build by using the “Add Build step” option just below the save button. A new “Add Tasks” window will open select the step you would like to add and click on "Close".
  
  
   
  
  
• Remove Build Steps
   Click on the symbol to remove the task from the build definition as shown below.
  
  
• Save Build Definition
  Click on save, to save the build definition Name and add comments (if any).
  
  
  
  I used below the Build steps for my build definition.
  
  
   

Step 4 - Tasks used in the build definition

Now let’s take a look on different steps used in build definition and the settings used for the steps. In this build definition, I used 3 basic steps, you can add any other task [For the unit test, deploy, MSbuild etc. There are so many options available under add tasks window. Choose the task as per your project requirement]

1. Visual Studio Build Task
2. Copy files Task
3. Publish Build Artifacts Task

Task 1 - Visual Studio Build Task

 

Using this task we are able to specify the solution, platform, configuration, Visual Studio version etc for the build definition.

 

Select the Task on the left side and the task properties available on the right side as shown

Select the task on the left side and set the properties on the right side as shown.

Solution : If you want to build multiple solutions, use search criteria. For example, in order to include all .sln files in all subdirectories use **\*.sln as search criteria

Platform: It provides these options to choose for build - Win32, x86, x64 or any cpu.

Configuration: Lets you set the configuration for your build such as debug or release.

For information on the particular step setting, click on blue info icon.

To read more about this step, click here.

Task 2 - Copy files

 

This task can be used in a build to copy files from a source folder to a target folder. We can use a custom variable to specify the source folder path.

 

 

In this step, the source folder is $(build.sourcedirectory) under Agent’s _work folder.

s = source directory and a= artifact staging directory.

 

$(Build.ArtifactStagingDirectory) Directory is purged before each build, so you need not to clean it up yourself and recreate it prior to every build in spite of any settings. Read more about Artifacts here

To know more about this task read here.

 

Task 3 - Publish Build Artifacts

This task can be used in a build to publish build Artifacts to TFS, or a file share, as specified in the information shown below.

 

Path to publish

 

Specify Path to the folder or file you want to publish.

Using this task, we can specify the folder on the network and after build it publishes the files in this folder and from here, we can use these publish build Artifacts as the source for the Release definition.

Artifact Type: this can be of two types,

1. Server
2. File share
   
   

I selected file share and for this, specify the path to the file share where you want to copy the files. The path must be a fully-qualified path or a valid path relative to the root directory of your repository. 

Note
Publishing artifacts from a Linux or macOS agent to a file share is not supported.
 

Build Menu Options

The Build definition contains various options, as we can see in the below screenshot.

1. Build tab
2. Options tab
3. Repository tab
4. Variables tab
5. Triggers tab
6. General tab
7. Retention tab
8. History tab

Now let’s discuss, one by one,

Build tab

 

This is the first tab in which we can add the build steps or add new tasks to the build definition. See the image,

 

 

 

Use the +Add build Step... button add the steps in your build definition.

 

 

 

Options tab

 

This menu contains three further options to set

1. Multi-Configuration
2. Create Work Item on Failure
3. Allow scripts to Access OAuth Token

 

 

Multi-Configuration

This option can be used to build multiple configurations such as configuration on both x86 and x64 platforms.

This option from Options tab helps in building selected solutions multiple times. For that, we can add comma separated list of configuration variables here. These variables are listed in the variables tab which we will discuss later in this section. You can find a list of predefined variables here. The Parallel check box, provides all the combinations in parallel.

 

Note
The pre-condition is that there should be multiple agents available to run. 

 

Create Work Item on Failure

This option can be used to automatically create a work item when the build fails due to any reason. The work item can be of Bug, Task, Test case, User story and Issue type. Assign to Requestor option can be used to assign the work item to the requestor.

 

 

And using +Add field we can add an additional field when creating the work item, as shown in the comment.

 

Field	Value
System.Title	Build $(Build.BuildNumber) failed
System.Reason	Build failure

 

To know more about options tab click  here

Repository tab

We can specify Repository type, source path and local path mappings, and add new mappings using this tab.

At the beginning of the build process, the agent downloads files from your remote repository into a local sources directory on an agent.

For example, in the below build, the server path is mapped to the local path under mappings section. 

The Server paths can be mapped with a local path. 

	Server Path mapped to	Local Path on the agent
Application files	Source Code	BBSourceCode
PowerShell scripts	BuildProcessTemplates/PowerShellScripts	BuildProcessTemplates\PowerShellScipts

 

So it will create ‘BBSourceCode’ and “PowerShellScripts” folders on my agent machine’s “s” directory locally, as shown below,

 

We can add mappings using Add Mapping  link as shown above.

 

Variable tab

 

Using this tab, we can add variables which can be used in the build definition. Variables can store and share key bits of data in your build definition. Some build templates automatically define some variables for you.

 

Ex - when you create a new .NET application build, BuildConfiguration and BuildPlatform are automatically defined for you.

This tab contains some predefined system variables which are created automatically at the time of build definition creation. for example,

• system.collectionId,
• system.teamProject,
• system.definitionId

We can't edit these variables,

 

 

You can also add your own variables which can be used in the build definition.

SYNTAX : $(myVariablename)

So, if you want to use your variable in the build definition, we have to specify it as per the above syntax.

 

For example, in the Build definition Task, we used these variables as $(buildConfiguration), as shown below.

 

 

In the same way, you can use your own variables.

 

Allow at Queue Time

 

Also, there is a checkbox “Allow at Queue Time” specified in front of your each defined variable which means you can edit the value of these variables at the time of queuing new Build. When you click on the Queue build option then at this time you are able to edit the value of these specified variables as shown below,

 

 

To know more about variables, click here.

Triggers tab

 

Using this tab we can schedule the build, build with each check-in or with gated check-ins.

Triggers available are - Continuous Integration, Scheduled and gated check-in.

CI (Continuous Integration) - Select this trigger if you want the build to run whenever someone checks in code.

Checked Continuous Integration and provide the path of the solution for which Continuous Integration is build.

We can add filters as well to include and exclude any file/path.

 

We can also schedule the build using Scheduled Trigger, specify the time at which you want the build to run.

 

 

To know more detail about triggers please click here.

 

General tab

 

Using the General tab, we can specify -

• Default agent queue for build
• Build Job authorization scope, i.e., Project Collection or current project
• Build number format – what name you want for your build or the name of the folder under which queued build will be placed.
• Build job timeout in minutes – by default 60
• Demands - capabilities on the agent machine 

Make sure that the capabilities your build needs are present on the build agents that run it. Demands are added automatically by build steps or we can also add Demands manually using Add demand button.

 

Some build steps won't run unless one or more demands are met by the build agent.

For example, the Visual Studio Build step required that "msbuild” and “visualstudio” are installed on the build agent. If your build includes steps that have demands, they are listed first.

We can specify additional demands like choosing a specific agent by adding a demand as “Agent.Name” as shown above.

NOTE
if the "msbuild" and "visualstudio" are not present on the build agent, and in our build definition we added "Visual Studio Build" Task, It will show a message that capabilities are not present on the agent.

Retention tab

Retention tab as the name says, allows to see the duration to keep the build and a minimum number of build to keep. It also allows us to set or edit maximum build retention policy.

 

 

History tab

History tab allows to see any changes in the build definition.

It also shows the information like changed By, Changed date, Change Type and comment.

 

Save Build

 

Save the build definition by clicking on the Save button.

 

 

Specify the comment, if any, and click on OK. Build definition is saved and now Queue build option is enabled which means we can build the task steps.

 

 

Queue Build

 

After saving, Queue build is enabled. Click on Queue build,

 

Specify variable/Demands and click ok,

Build has started and the build tasks are executing as specified in the build definition.

The agent downloads all the resources to the local path mapped to the server path and then executes the steps as mentioned in the build definition. 

 

Build with defined Build Number Format is created as an example we can see below as Build 20181219.1 

 

 

Build has succeeded with all the steps.

We can see the console for the build tasks and explore logs using Logs as shown below.

 

 

On the agent Machine, we can see the folders specified in the Repository tab are created and we can see the _work/2/s path in the logs of the build.

 

 

 

 

And the Build Artifacts are published on the specified location as we set in the Publish Build Artifacts step.

 

The TestDrop folder created as specified on the File Share path.

 

 

After Build Has Succeeded

There are different options we can see when the build has succeeded

1. Summary tab
2. Timeline tab
3. Artifacts tab
4. Tests tab

Summary tab

 We can see build details such as build definition name, source branch, any test resuls source version etc. as shown below in this tab.

 

 

Timeline tab

This tab can be used to display build steps, agent name and the duration takes place when executing each step as shown.

 

Artifacts tab

We can use this tab to explore the build Artifacts as we setup in the Publish Build Artifacts step.

 

On exploring we can see these artifacts on the File Share path specified as shown:

Tests tab

 

This tab shows any test tasks, I didn’t use any test task so it’s showing none here,

 

 

Summary

 

In this article, we saw,

• How to create a build Definition
• How to configure the different tasks/steps included in the build
• How to configure various build menu options
• Save the build
• Queue build option
• After the build has succeeded, various options to see the information about the build

Note
We can use the build Artifacts produced by the Build definition in the release definition. I’ll explain in my next article about the Release definition for different environments and the steps included in the Release definition.

Below is a flow of the work of build, release definition, and agent.

 Happy Reading!!! :)