[Updated 16 Jun 2016 to reflect name change from VSO to VSTS]
[Updated 28 Dec 2015 to reflect latest changes in command line interface]
If you’ve been making use of the new Team Foundation Build technology in Visual Studio Team Services (VSTS) or Team Foundation Server (TFS) 2015 then you might have wished you had the ability to create and upload your own custom build tasks. Well, that day is now here! You can now create a custom build task and upload it to your VSTS account for use across your build definitions.
The ability to upload custom tasks is still considered to be in a “pre-release” mode so you might run into the occasional issue. However, if you do, Microsoft is committed to resolving any bugs/issues uncovered and will fully support the technology.
That said, let’s walk through the creation of a simple custom build task…
Step 1: tfx-cli
The new tool provided for managing build tasks is called the TFS Extensions Command Line Utility, or tfx-cli for short. This is a cross-platform utility for managing extensions in TFS/VSTS and is supported on Windows, OS X and Linux.
To install tfx-cli:
- Go to the tfx-cli website.
- Follow the instructions for installing tfx-cli via npm. For example, to install it on Windows, run the following command:npm install -g tfx-cli
Once installed, enter tfx on the command line and press enter to see the command usage instructions.
Step 2: Login to VSTS/TFS with tfx-cli
Before running any actions with tfx-cli let’s first login to our VSTS account (or TFS). Currently, you can login using basic auth or a personal access token (PAT). Support for NTLM (to login to TFS) will be coming soon.
For this example, we will login to VSTS using a personal access token (PAT). NOTE: You can create PAT’s by editing your profile in VSTS and selecting the Security tab*.
- In a command window, run tfx login.
- Provide your collection URL (i.e. the URL to your VSTS account). NOTE: Be sure your collection URL ends with “/DefaultCollection”).
- Paste in your personal access token. NOTE: when pasting your PAT into the command line the PAT will not be visible.
Once logged in, you can run multiple tfx-cli commands without having to login again.
[*Read more about PATs in Personal Access Tokens & VSTS]
To verify everything is working you can list out all build tasks (for the account you’ve logged into) by running the following command:
tfx build tasks list
NOTE: You can view the various build task commands here.
Step 3: “Hello, Task!”
Now that we can view our installed build tasks, let’s create a new, custom build task.
- In the command window, create a new directory for the task – e.g. mkdir HelloTask
- Run the command: tfx build tasks create
- After answering the questions you will be left with a set of files that make up a custom build task.
You should see a list of files similar to this once the command has completed:
- The icon.png file is a default icon and should be replaced with a custom, 32×32 png file with transparencies set appropriately.
- The sample.ps1 contains the PowerShell build task logic that is executed when running on a Windows agent.
- The task.json file contains the metadata that describes the build task along with any inputs and contains references to the script files that contain the task’s logic.
Let’s go ahead and upload this task to our VSTS account so we can make use of it in a build.
- From the same directory that we ran the “create” command in above, run the following command:tfx build tasks upload –task.path ./HelloTask
- Once uploaded, you will see a success message:
Step 4: Take it for a Test Drive
First, let’s create a new, empty build definition in VSTS:
Next, click on the Utility tab and click Add next to our custom build task (Hello, Task!) then click Close:
You should see something similar to this:
The callouts above show the element names within the task.json file that define the marked sections. Each of these can be fully configured in the task.json file.
Save the build definition and queue it up. Once the build has executed, you should see an output similar to the following:
Note the “Hello World” output in the log. This is the output provided by the custom build task. Cool, eh?!
Step ?: Deleting Your Build Task
The final command that can be ran is the delete command. If you need/want to delete a build task, simply run:
tfx build tasks delete –task.id <build task ID>
Where the build task ID is the ID associated with the build task you want to delete. If it is a custom build task, this ID is the “id” element at the top of the task.json file. If you do not have access to the task.json file, you can get the ID by running the list command as shown in Step 2 above.