Teamprise TFS Ant Tasks: User Manual

The Teamprise TFS Ant Tasks are created and supported by Teamprise. For more information, go to the index page or visit teamprise.com.

Contents

• Introduction
• The Tasks
• Known Issues
• Change History

Introduction

These tasks provide an interface to Microsoft Team Foundation Server. By using these tasks you can access the capabilities of a TFS server from an Ant script. The TFS Ant tasks require Ant version 1.6 or higher. Version 1.7.0 is recommended.

These tasks are implemented as wrappers around the tf command line tool for accessing TFS. These tasks will work with either the tf.exe tool from Microsoft or the Teamprise command line client. Usage of these tasks requires that the command line tool is already installed on the machine running Ant.

Important: These tasks need "tf" to be on the path. Alternatively, you can set the property tfs.vc.executable to the location of the tf program to execute. If the tasks aren't working, check that one of these conditions is met.

The Tasks

General TFS Task Properties

Connection Details

Each of the tasks below requires information specifying the TFS server to connect to and the credentials to use when logging in. These values can be individually specified for each task as attributes or globally specified as properties. Note: the per-task attributes take precedence over the global properties. If both a global property and the corresponding per-task attribute is set, the value of the per-task attribute will be used.

Important: When specifying a username using the DOMAIN\USERNAME syntax, be sure to use only a single backslash. Escaping the backslash is not neccessary inside an Ant script.

In certain cases, these connection details are optional and do not need to be specified. However, it's usually best to always specify them explicitly rather than rely on the inferring behavior of the command-line tool that works under some conditions but not others.

Execution Options

Additionally, the TFS tasks support the following configuration options. Again, these can be set either as global properties or as per-task attributes.

Input / Output Options

Each of the TFS tasks supports a number of optional per-task attributes that allow you to redirect the input and output of the underlying command-line tool. For example, you can use these properties to capture the output of a TFS task and write it to a file or Ant property instead of writing it to the Ant log.

Examples

Using global properties to specify TFS connection details:-

<property name="tfs.server" value="http://tfs.mycompany.com:8080"/>
<property name="tfs.user" value="MYDOMAIN\autobuild"/>
<property name="tfs.password" value="access"/>

Using task attributes to specify TFS connection details:-

<tfsWhatever
	server="http://tfs.mycompany.com:8080"
	user="MYDOMAIN\autobuild"
	password="access"
	.
	.
	.
/>

Using global properties to specify the location of the command-line executable:

<property name="tfs.vc.executable" value="c:\program files\microsoft visual studio 8\common7\ide\tf.exe" />

Capturing the output of a TFS task in a property instead of having the output go to the Ant log:

<tfsWhatever outputproperty="myprop" />
<echo message="${myprop}" />

Parameters specified as nested elements

All of the TFS tasks can pass custom arguments and options to the wrapped command-line tool by using nested elements. The main use of this feature is as a stop-gap measure to provide functionality not available through the built-in attributes of a task, or to allow workarounds for bugs in the Ant/TFS integration. The generic tfs task will usually need to use these nested elements in order to be useful.

arg

Custom command line arguments should be specified as nested <arg> elements. See Command line arguments. When possible, nested <option> elements should be used instead, as the wrapped command-line tool's switch syntax does not have to be manually specified.

option

Custom command line options should be specified as nested <option> elements. Used nested option elements is preferred to using nested argument elements (when the value is really an option and not a free-form argument) because the Ant script does not need to hard-code the switch syntax. The switch syntax is the leading prefix character ('/' or '-') and the separator character between the option name and option value (':'). The switch syntax may be platform-specific.

env

It is possible to specify environment variables to pass to the command-line tool via nested <env> elements.

redirector

A nested I/O Redirector can be specified.

Example

<tfsWhatever x="y">
	<arg value="some value" />
	<option name="myoption" value="myvalue" />
	<env key="MY_ENV_VAR" value="myvalue" />
</tfsWhatever>

The versionspec format

Several of the task descriptions below reference the versionspec format. A versionspec is a string that describes a particular version of a TFS item. The following table lists the five possible versionspec types and gives examples of each.

For more information about the versionspec format, see the online documentation.

A word about exit codes and build failures

Normally, when the execution of the wrapped command-line tool fails, the Ant build will fail as well. There are a few kinds of failures that can happen, and a few ways that you can configure a TFS task's behavior when the command-line tool fails.

The tf tool defines several standard exit codes. The exit code of the sub-prcess is used by the TFS task to determine what kind of failure has happened. An exit code of 1 or 100 is the most common error exit code. When this exit code is returned, the build will fail unless the failonerror attribute is set to true (or the global tfs.failonerror property is set to true). Any other non-zero exit code indicates a bug in the TFS task itself and will always fail the build.

It is also possible that an error will occur when attempting to execute the command-line tool, and the tool cannot be executed. An example of this kind of error would be that the command-line tool executable could not be found. This kind of error will fail the build unless the failifexecutionfails attribute is set to true (or the global tfs.failifexecutionfails property is set to true).

Task Descriptions

tfs

Description:

Runs a generic TFS command. This task is intended as a stop-gap measure when some functionality is needed that one of the other TFS tasks does not provide. This task gives full control over the options and arguments that are passed to the TFS command line client. For a complete listing of the available commands and their syntax, consult the online documentation.

Parameters

Tip: When the global tfs server property is set (tfs.server), the server option will be automatically included when invoking the command line client. Certain TFS commands will error or show a warning if the server option is passed. Occasionally when using the <tfs> task when the global server property is set, you may wish to suppress this option for certain TFS commands to avoid errors or warnings. By using the per-task server attribute and setting the value to an empty string, you can suppress the server option. The per-task attributes always override the global properties. See above for more information on TFS task configuration. The examples section shows an example of supressing the global server property when using this task.

Examples

List workspaces and store the results in a property:

<tfs command="workspaces" outputproperty="myprop" />
<echo message="${myprop}" />

Run the status command to see pending changes against an item:

<tfs command="status" server="">
	<arg file="${basedir}/files/project" />
</tfs>

Run the properties command to display properties for a folder and all contained items:

<tfs command="properties">
	<option name="recursive" />
	<arg value="$/myproject/myfolder" />
</tfs>

tfsadd

Description:

Pends adds for new items to a workspace. To commit the new items, you must perform a check-in (tfscheckin). This task wraps the tf add command.

Parameters

Examples

Add an item to TFS version control:

<tfsadd 
	item="${basedir}/files/newfolder" />

Add an item to TFS version control, specifying a lock:

<tfsadd 
	lock="checkin"
	item="${basedir}/files/newfolder" />

tfscheckin

Description:

Checks in items that have been previously checked out in a workspace. This task wraps the tf checkin command.

Parameters

Check-in notes are specified in the following format:

NoteFieldName=NoteFieldValue

You can provide multiple, semicolon-separated "field=value" expressions.

Examples

Check an item in:

<tfscheckin 
	comment="checked in by build process" 
	item="${basedir}/files/build/version.txt" /> 

Check an item in, specifying some check-in notes:

<tfscheckin 
	comment="checked in by build process" 
	notes="Code Reviewer:${codereviewer};Security Reviewer:${securityreviewer}"
	item="${basedir}/files/build/version.txt" /> 

tfscheckout

Description:

Check items out. Before checking an item out, you must ensure that the item is mapped in a workspace (tfsworkfold) and that the item exists locally (tfsget). By checking an item out, the local file or folder is made writable. Changes to that item can later be checked in (tfscheckin). This task wraps the tf checkout command.

Parameters

Lock Attribute Values

For more information on the lock attribute, see Understanding Lock Types in the MSDN documentation.

Examples

Check an item out:

<tfscheckout item="${basedir}/files/build/version.txt" />

Check an item out, locking it so that other users cannot check it in until you do:

<tfscheckout 
	lock="checkin"
	item="${basedir}/files/mydirectory" />

tfsdelete

Description:

Pends deletes for items in a workspace. To commit the deletions, you must perform a check-in (tfscheckin). This task wraps the tf delete command.

Parameters

Examples

Delete an item from TFS version control:

<tfsdelete 
	item="${basedir}/files/newfolder" />

tfsget

Description:

Performs a get on a local path that has previously been mapped in the specified workspace. This task wraps the tf get command.

Parameters

Examples

Perform a simple recursive get on a path:

<tfsget localpath="${basedir}/files" />

Peform a get of items at a specific changeset version:

<tfsget localpath="${basedir}/files" version="C128" />

Perform a get, re-downloading any items already downloaded and overwriting local writable files:

<tfsget localpath="${basedir}/files" force="true" />

tfshistory

Description:

Obtains the history of an item on the TFS server. This task is often used inconjunction with the outputproperty attribute that all TFS tasks support (see above). Using outputproperty allows the history output to be saved in an Ant property and used later in the build. By calling the tfsparsehistory task with the output of this task, individual values can be pulled out of the history output (like changeset numbers and dates). This task wraps the tf history command.

Parameters

Examples

Get the history for an item and store it in a property:

<tfshistory
	outputproperty="myprop"
	logerror="true"
	format="briefquot;
	item="$/MyProject/myfolder" />

<echo message="${myprop}" />

Display detailed history for only the last changeset of an item:

<tfshistory
	format="detailedquot;
	stopafter="1"
	item="$/MyProject/myfolder" />

tfslabel

Description:

Attaches or removes labels from a version of an item on the TFS server. Adds or removes of labels happen immediately: no subsequent check-in is required. This task wraps the tf label command.

Parameters

Examples

Create a label on an item:

<tfslabel
	name="${buildLabel}"
	item="${basedir}/files" />

tfsparsehistory

Description:

Parses the output of the tfshistory task. Unlike most of the other TFS tasks, this task does not invoke any underlying command-line tool. The purpose of this task is to take TFS history data (usually stored in a property from a previous call to tfshistory) and pull out an individual value.

Important: currently, this task only works with history data in the "brief" format. Attempting to use this task with history in the "detailed" format will not work.

The history data is in tabular form. The purpose of this task is to parse the table and pull out the value of a single cell. You must specify the index of the row to pull data from, as well as either the column name or column index. Note that the indices are one-based, so the first row index is "1" and the first column index is "1"

Parameters

Examples

The most common use of this task is to pull out changeset information for an item. This example shows how to obtain the latest changeset number of an item:

<tfshistory
	outputproperty="historydata"
	stopafter="1"
	item="$/MyProject/myfolder" />

<tfsparsehistory 
	historyinputvalue="${historydata}" 
	historyoutputproperty="changeset" 
	rowindex="1" 
	columnname="changeset" />
	
<echo message="changeset is: ${changeset}" />

tfstasksdiagnostics

Description:

Prints out diagnostic information and runs tests to ensure that the Teamprise TFS Ant tasks are correctly installed. This task takes no parameters.

Examples

<target name="diagnostics">
    <tfstasksdiagnostics />
</target>

tfsworkfold

Description:

Creates and deletes working folder mappings in a workspace. This task wraps the tf workfold command.

Parameters

The map and unmap modes are used to create and remove working folder mappings from a workspace. The list mode is used to display all existing working folder mappings in a workspace, and is intended primarily for debugging Ant scripts. When at least one of serverpath or localpath is specified, mode defaults to map if it is not specified. When neither of serverpath and localpath is specified, mode defaults to list if it is not specified.

When mode is map, both serverpath and localpath are required. When mode is unmap, either serverpath or localpath is required, and if both are specified serverpath will be used. The list mode does not require either serverpath or localpath to be specified.

Examples

Create a new working folder mapping:

<tfsworkfold 
	workspace="autobuild_workspace" 
	mode="map" 
	localpath="${basedir}/files" 
	serverpath="$/MyProject/myfolder" />	

List the working folder mappings in a workspace:

<tfsworkfold workspace="autobuild_workspace" />	

Remove a working folder mapping:

<tfsworkfold 
	workspace="autobuild_workspace" 
	mode="unmap" 
	localpath="${basedir}/files" 

tfsworkspace

Description:

Creates or deletes a workspace on the TFS server. This task wraps the tf workspace command.

Parameters

Examples

Create a new workspace:

<tfsworkspace mode="create" workspace="autobuild_workspace" />

Delete a workspace:

<tfsworkspace mode="delete" workspace="autobuild_workspace" />

Delete a workspace if it exists, but do not fail the build if the workspace does not exist:

<tfsworkspace 
	mode="delete" 
	workspace="autobuild_workspace" 
	failonerror="false" />

Known Issues

• No known issues in this release.

Change History

Copyright © Teamprise, 2007-2008. All rights reserved.