Specify general build definition settings

Last Update: 9/26/2016

Team Services | TFS 2015 | Previous versions (XAML builds)

Definition edit panel header
Build      Options      Repository      Variables      Triggers      General      Retention      History

Default agent queue

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

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.

Description

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.

Build job timeout in minutes

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.

Badge enabled

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}/>

Demands

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:

    • Visual Studio Team Services: https://{your_account}.visualstudio.com/_admin/_AgentPool

    • On-premises: http://{your_server}:8080/tfs/_admin/_AgentPool

  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.

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 a build agent?

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

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

See Administer 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.

Where is the Visual Studio 2013 XAML build documentation?

Visual Studio 2013 XAML build documentation