Authoring VS Team Services extension with Build/Release Tasks

Background

Build and Release services are available with Visual Studio Team Services and Team Foundation Server 2015.
Both these services rely on a set of tasks that are used to define build steps or deployment tasks.
A set of out of the box tasks are provided from the system. There is a provision for you to author your own tasks and make them available for your team.
In addition to that, with extensions and VSTS marketplace, you can now make your tasks publically available for everyone to use.

As a part of this blog, we’re going to look at a step by step guide to author an extension through which you can share a new task.
Release Management utility tasks is an example extension of this type. The associated code used to package this extension is available here.

Steps involved

We’ll look at the development procedure for the extension through four important steps. Each of the steps play an equally critical role in the development and life cycle management of the extension.

Author & test task that needs to be added

The first and arguably the most critical step of this development is to identify a task that you would like to contribute to the catalog.
The task is the heart of the extension with the rest forming the packaging layers that help with distribution of the task itself.

We would not focus on authoring the task itself here. Detailed guidance around authoring the task is available here.
As a recommendation, we suggest you to modify one of the existing tasks than starting from scratch.
Code for out of the box tasks is available here. You can take any of the tasks as a starting point (Grunt is a good one).

As an illustration, we’ll look to make changes to the currently available Azure PowerShell task.
The task currently supports taking an input of a script file only. We’ll try and add a capability for the task to support inline script inputs too.

A change to the task essentially involves making modifications to three/four files namely task.json, icon.png and the task’s powershell/ts file. In our example there is no ts file for the task. The task only has RunAzurePowerShell.ps1.

The following changes shall be required for the purpose.

  1. RunAzurePowershell.ps1 → This powershell script is the core execution logic of the task. The parameter inputs taken into the script map 1:1 with the parameter inputs from the task. We’ll add two additional parameters here namely “ScriptType” and “InlineScript”. We’ll also make changes to the script so as to conditionally execute the script from the file mentioned in the ScriptPath parameter or the InlineScript.
  2. Task.json → This json file is the metadata for the task. It plays a critical role in the rendered UI for the task. We’ll make changes to Id, name, friendlyname, description and author in this file as per the need. We’ll also add two additional inputs here with names matching the parameters we added to the powershell script namely “ScriptType” and “InlineScript”. ScriptType shall be a picklist while InlineScript would be of multiline type. Some additional changes to make relevant inputs show conditionally based on value of ScriptType.
  3. Icon.png  → This is the icon for the task. We’ll update this to the new icon.

Once the changes are made, we’ll upload this task into our private account using tfs-cli and validate its functionality using some test build and release definitions.

Add Extension Manifest and Icon

The extension follows a similar definition scheme as the task. There are two key files that contribute to the extension called extension-icon.png – the extension icon and vss-extension.json – the extension manifest.

 

You’ll need to add the task created above as a folder and mention it in the vss-extension.json file.

  • Add the folder name in the files section as a path
  • Add a contribution of the type ms.vss-distributed-task.task  for each of the tasks

Refer to this for more details on referring to the tasks in the extension files.

Package, Publish and Test

Once the extension is ready, you would need to package the extension into a .vsix file and then publish it. You can publish an extension as a private extension or a public one. You need to be a verified publisher before you could publish it as a public extension, though.

Even with private extension, you can share the extension with multiple accounts. Publishing it privately and sharing it with few accounts is a good way to test your extension or release your extension as a beta extension to a few test accounts. Once you are satisfied with the utility and quality of your extension, you should go ahead and publish the extension as a public one.

Refer to detailed documentation on publishing extension, here.

Making changes to extension or task

At any point in time, if you need to make a change to your extension for making any improvements or fixing a bug, you can easily do so and re-package it and update the extension.

Any changes made to the extension, once published, automatically gets available to everybody using the extension. So you should be really sure about the change before publishing it. You should also bump up the task version and the extension version in the latest extension, so that the change is available to all.