Build definition options

Last Update: 4/26/2017

Team Services | TFS 2017 | TFS 2015 | Previous versions: XAML Build, Release

Here we explain settings you can change on the build definition Options tab.

Description

Team Foundation Server (TFS) 2017 Update 1 and older

This section is available under General tab.

If you specify a description here, it is shown near the name of the build definition when you select it in the Build area of your team project.

Build number format

If you leave it blank, your completed build is given a unique integer as its name. But you can give completed builds much more useful names that are meaningful to your team. You can use a combination of tokens, variables, and underscore characters.

Example

At the time the build is queued:

  • Team project name: Fabrikam

  • Build definition name: CIBuild

  • Branch: master

  • Build ID: 752

  • Date: August 5, 2009.

  • Time: 9:07:03 PM.

  • The build ran once earlier today.

If you specify this build number format:

$(TeamProject)_$(BuildDefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd)$(Rev:.r)

Then the second completed build on this day would be named: Fabrikam_CIBuild_master_20090805.2

Tokens

The following table shows how each token is resolved based on the previous example.

Token

Example replacement value

$(BuildDefinitionName)

CIBuild

Note: The build definition name must not contain invalid characters, including whitespace.

$(BuildID)

752

$(BuildID) is an internal immutable ID.

$(DayOfMonth)

5

$(DayOfYear)

217

$(Hours)

21

$(Minutes)

7

$(Month)

8

$(Rev:.r)

2 (The third build on this day will be 3, and so on.)

Use $(Rev:.rr) to ensure that every completed build has a unique name. When a build is completed, if nothing else in the build number has changed, the Rev integer value is incremented by one.

If you want to show prefix zeros in the number, you can add additional r characters. For example, specify $(rev:.rr) if you want the Rev number to begin with 01, 02, and so on.

(Date:yyyyMMdd)

20090824

You can specify other date formats such as $(Date:MMddyy)

$(Seconds)

3

$(SourceBranchName)

master

$(TeamProject)

Fabrikam

$(Year:yy)

09

$(Year:yyyy)

2009

Variables

You can also use user-defined and predefined variables that have a scope of "All" in your build number format. For example, if you've defined My.Variable, you could specify the following build number format:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable)

The first four variables are predefined. My.Variable is defined by you on the variables tab.

Badge enabled

TFS 2017 Update 1 and older

This section is available under General tab.

Select if you want to show the latest outcome of this build on external web sites.

  1. Select the Badge enabled check box.

  2. Save the definition.

  3. When he Show url link appears, click it and copy the URL to your clipboard.

  4. Use the URL as the source of an image in the HTML of the page of the external web site. For example: <img src="{URL you copied from the link}/>

Create a work item on failure

If the build process fails, you can automatically create a work item to track getting the problem fixed. You can specify the work item type.

You can also select if you want to assign the work item to the requestor. For example, if this is a CI build, and a team member checks in some code that breaks the build, then the work item is assigned to that person.

Additional Fields: You can set the value of work item fields. For example:

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

Q: What other work item fields can I set? A: Work item field index

Allow scripts to access the OAuth token

Select this check box if you want to enable your script to use the build process OAuth token.

For an example, see Use a script to customize your build process.

Default agent queue

TFS 2017 Update 1 and older

This section is available under General tab.

Select the queue that's attached to the pool that contains the agents you want to run this definition.

Tip: If your code is in Visual Studio Team Services (Team Services) and you run your builds on Windows, in many cases the simplest option is use the Hosted pool.

Build job authorization scope

TFS 2017 Update 1 and older

This section is available under General tab.

Specify the authorization scope for a build job. Select:

  • Project Collection if the build needs access to multiple team projects.

  • Current Project if you want to restrict this build to have access only the resources in the current team project.

Build job timeout in minutes

TFS 2017 Update 1 and older

This section is available under General tab.

Specify the maximum time a build job is allowed to execute on an agent before being canceled by the server. Leave it empty or at zero if you want the job to never be canceled by the server.

Build job cancel timeout in minutes

Team Services only

Specify the maximum time a build job is allowed to respond after the a user cancels the build. You can specify a value from 1 to 60 minutes.

Set this value to allow sufficient time for tasks to complete in cases where you've specified to Run this task as Even if a previous task has failed, even if the build was cancelled or as Custom conditions that allow a task to always run after cancellation.

Whatever value you set here, the Build job timeout in minutes limit still applies. For example:

  • Build job timeout in minutes = 30

  • Build job cancel timeout in minutes = 15

  • A user clicks Cancel after the build has run for 25 minutes.

  • The build will be given 5 minutes to cancel instead of the 15 you specified.

NOTE

The system typically consumes about 10 seconds of this time allotment for messaging before your tasks run.

Demands

TFS 2017 Update 1 and older

This section is available under General tab.

Use demands to make sure that the capabilities your build needs are present on the build agents that run it. Demands are asserted automatically by build steps or manually by you.

Build step demands

Some build steps won't run unless one or more demands are met by the build agent. For example, the Visual Studio Build step demands that msbuild and visualstudio are installed on the build agent. If your build includes steps that have demands, they are listed first.

Manually entered demands

You might need to use on-premises build agents with special capabilities. For example, your build process requires SpecialSoftware.

Add the demand to your build definition.

Name Type
SpecialSoftware exists

Register each build agent that has the capability.

  1. Go to the Agent pools tab at the root of the control panel:

    • Team Services: https://{your_account}.visualstudio.com/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool

    The TFS URL doesn't work for me. How can I get the correct URL?

  2. Click the agent, and then click Capabilities

  3. Add something like the following entry.

First box Second box
SpecialSoftware C:\Program Files (x86)\SpecialSoftware

Tip: When you manually queue a build you can change the demands for that run.

Multi-configuration

Select this option to build multiple configurations. For example, you could build a C++ app for both debug and release configurations on both x86 and x64 platforms. For details about this example, see Visual Studio Build.

Q&A

In what time zone are the build number time values expressed?

If you are using Team Services, then the time zone is UTC.

If you are using an on-premises Team Foundation Server, then the time zone is the same as the time zone of the operating system of the machine where you are running your application tier server.

Do I need an agent?

You need at least one agent to run your build or release. Get an agent.

I can't select a default agent queue and I can't queue my build or release. How do I fix this?

See queues.

I use Team Foundation Server on-premises and I don't see some of these features. Why not?

Some of these features are available only on Visual Studio Team Services and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.