Custom Build Tasks in VSTS

[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:

  1. Go to the tfx-cli website.
  2. 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*.

  1. In a command window, run tfx login.
  2. Provide your collection URL (i.e. the URL to your VSTS account). NOTE: Be sure your collection URL ends with “/DefaultCollection”).
  3. 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.

  1. In the command window, create a new directory for the task – e.g. mkdir HelloTask
  2. Run the command: tfx build tasks create
  3. 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.

  1. From the same directory that we ran the “create” command in above, run the following command:tfx build tasks upload –task.path ./HelloTask
  2. 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 – <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.


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:

Happing building!

22 thoughts on “Custom Build Tasks in VSTS

  • […] [Update 2015-08-12] Microsoft has just made a new command-line utility called “tfx-cli” available which allows you to create, upload, delete and list build tasks. You can use that, instead of the “TaskUploader” described in this post. I’ll leave this post up here, since the part about building the tasks is still useful. “tfx-cli” is distributed through npm and can be found here.A nice walkthrough by Jeff Bramwell can be found on his blog here. […]

  • Liviu M

    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

    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?

    • Jeff B.

      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.

  • Richard Rubie-Todd

    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.

      • Richard Rubie-Todd

        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!

          • Richard Rubie-Todd

            Thanks. I’m really glad it isn’t just me not being able to follow instructions!

          • Jens Bruggeman

            I have the same issue. @jeffbramwell:disqus : do you know the cause or can you put the solution here?

            Thank you

          • Hamid Shahid

            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.


          • Vikram

            I am also getting the same error:

            File not found: ‘C:…._d54f4c50-8449-40db-aa23-afebce62c6f01.0.0ps_modulesVstsTaskSdkVstsTaskSdk.psd1’

      • Alex

        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

  • Matt

    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.

    • Alex

      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

  • MCodeMedia

    Thanks this answered many of my question, I only had to have a lead developer point me to your blog

Comments are closed.