[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.
Caveat
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
For example:
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.js file contains the JavaScript build task logic that is executed when running on a cross-platform agent (e.g. OS X or Linux).
- 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.
Summary
While this new feature is still in a “pre-release” mode it is none-the-less functional and very useful. If you’ve been creating lots of custom PowerShell and/or JavaScript files to be executed within your build definitions you now have the option to encapsulate those into a custom build task that can be reused by all projects within your VSTS account (or TFS project collection).
Further Reading:
- tfx-cli home page
- Build Tasks commands for tfx-cli
Happing building!
I am getting this type of error when I try to upload a task with tfx-cli:
Error: Failed Request: Forbidden(403) – http://myserver:8080/tfs/_api
s/distributedtask/tasks/89A3A82D-4B3E-4A09-8D40-A793849DC94F?overwrite=false
I am log in with basic auth and I am able to LIST all the tasks but when I try to upload one I get this error.
I have admin permissions on the server and the logs from TFS tell me that I need Manage permissions but I do have them.
Is there a bug in the tool?
When you set permissions, make sure you are setting permissions at the Account level (not the TPC level). For example, sign in to your VSO account and immediately click on the settings (gear) icon (i.e. do not select a project before doing this). Click the “Agent pools” tab (if it says “Agent queues” then you’re in the wrong place) and then click on “Roles”. Make sure “Agent Pool Administrators” is selected and then add the appropriate users on the right.
Hope this helps.
It appears as though there has been a change to tfx login. You now have to provide the Collection name.
EX:
https://xxx.visualstudio.com/DefaultCollection <- The collection name is required
Thanks! This post has been updated to reflect the latest changes.
Great article!
The post implies that you can run “tfx build tasks create” and upload the result straight to VSTS and it will work. Is this still the case?
I get the following build errors when i try this.
Error: Cannot find module ‘vso-task-lib’.
When i remove the Node value from execution (task.json) i get
System.Exception: VSTS task module not found at expected location: C:LRMMSServicesMmsTaskAgentProvisionerToolsagents1.101.2tasksHelloTask.1.1ps_modulesVstsTaskSdkVstsTaskSdk.psd1
Am i configuring something wrong in VSTS? This post doesn’t show any configuration so i have left everything as default.
Any help would be great.
@richardrubietodd:disqus I just ran through the above steps (except I called the task “TestTask” instead of “HelloTask”) and it uploaded just fine. I would recommend you run “npm -g install tfx-cli” (no quotes) from the command line to ensure you have the latest version of the tfx tools. Give that a try and see if that resolves your problem.
See below screen shot for the steps i took, they ran successfully.
I created an empty build, added the uploaded task and saved.
The build will now fail with the error mentioned in my previous post.
Did yours run ok?
Thanks for the clarification! I am able to reproduce this. I am going to do a bit of research and will respond back soon (and will update the blog post accordingly if necessary). Thanks!
Thanks. I’m really glad it isn’t just me not being able to follow instructions!
I have the same issue. @jeffbramwell:disqus : do you know the cause or can you put the solution here?
Thank you
Hello there,
I am getting the same issue. Getting the following error on the VSO Hosted agent
File not found: ‘C:…._d54f4c50-8449-40db-aa23-afebce62c6f01.0.0ps_modulesVstsTaskSdkVstsTaskSdk.psd1’
Any pointers / advise please.
Thanks
I am also getting the same error:
File not found: ‘C:…._d54f4c50-8449-40db-aa23-afebce62c6f01.0.0ps_modulesVstsTaskSdkVstsTaskSdk.psd1’
run “Save-Module -Name VstsTaskSdk -Path .” inside the root folder of your task
“mkdir ps_modulesVstsTaskSDK”
copy contents of vstsTaskSDK/{version}/
into ps_modules/VstsTaskSDK
The directory tree should look like the following
Root
|
|-ps_modules
…|
…|-VstsTaskSdk
……|
……|-Strings
……|-…
I was searching, where the tasks are uploaded in TFS server for on promises TFS.
So can you tell me what is the location for it?
I went through this and am hitting the same issue as several of the other comments on here with the missing VstsTaskSdk module. I would appreciate if there are anymore details to resolving that issue.
run install-Module -Name VstsTaskSdk inside the root folder of your task
create a ps_modules folder
move vstsTaskSDK/{version}/
into ps_modules
The directory tree should look like the following
Root
|
|-ps_modules
…|
…|-VstsTaskSdk
……|
……|-Strings
……|-…
Thanks this answered many of my question, I only had to have a lead developer point me to your blog