In DevOps we find ourselves writing lots of small scripts over and over. The need for building a library of tasks in your choice of tooling is important. This repository contains custom VSTS tasks using PowerShell and C#.
The 1st reusable approach in VSTS for sharing your tasks is to leverage Task Groups. This is essentially a way to combine tasks into a unique group.
Task Groups can be used for build or release definitions. These are easily created by selecting one or more tasks, right click, and select Create task group.
- Lack of history NOTE: seems Microsoft has now added this
- Versioning support
- Parameters are required
Custom tasks allows us to encapsulate logic. They are packaged into a command written in PowerShell or Node.js and defined by a JSON manifest.
- Install CLI -
npm install -g tfx-cli - Login -
tfx login- Enter the collection url:
https://{companyName}.visualstudio.com/DefaultCollection - Enter PAT: https://www.visualstudio.com/en-us/docs/setup-admin/team-services/use-personal-access-tokens-to-authenticate
- Enter the collection url:
- Download Task SDK -
Save-Module -Name VstsTaskSdk -Path .\
One can write VSTS tasks as a simple PowerShell or Node.js script without many dependencies. Microsoft has an SDK that allows for a better integration with VSTS. THe SDK provides a consistent approach for testing custom tasks. One main advantage is being able to access VSTS service endpoint programmatically.
The task SDK is statically linked to your custom task. One references the SDK in their command script. Add the SDK under the folder ps_modules\VstsTaskSdk in the task directory.
$ScriptPath = $(Split-Path -Parent $MyInvocation.MyCommand.Definition)
Import-Module $(Join-Path $ScriptPath "ps_modules\VstsTaskSdk\VstsTaskSdk.psd1")Create a new task using the command tfx build tasks create. This will provide you with a manifest, icon, & empty PowerShell script.
Inputs map to the parameters for the custom task. These can provide a default value and some level of intelligence using groups, conditional visibility, and validation.
- string
- boolean
- picList
- filePath
- multiline
- radio
- connectedService:ServiceType
- connectedService:AzureRM
- connectedService:Azure
- connectedService:Azure:Certificate,UsernamePassword
- connectedService:Chef
- connectedService:ssh
- connectedService:Generic
- connectedService:Jenkins
- connectedService:servicefabric
Inputs can be grouped into logical visual containers. These are rendered as a collapsible fieldset.
"groups": [
{
"name": "advanced",
"displayName": "Advanced",
"isExpanded": false
}
],
"inputs": [
{
"name": "manageMode",
"type": "pickList",
"label": "Management Mode",
"defaultValue": "Verify",
"required": true,
"groupName": "advanced",
"helpMarkDown": "Verify or Deploy routes.",
"properties": {
"EditableOptions": "True"
},
"options": {
"Verify": "Verify",
"Deploy": "Deploy"
}
},
{
"name": "enabled",
"type": "pickList",
"label": "Enabled",
"defaultValue": "false",
"required": true,
"groupName": "advanced",
"helpMarkDown": "Specifies if the step will run. Requires 'Control Options | Enabled' to be set as well.",
"properties": {
"EditableOptions": "True"
},
"options": {
"false": false,
"true": true
}
}
],
When the task is ready to be run from VSTS, use the tfx-cli to upload the task. Every file under the task folder will be included so keep this in mind.
tfx build tasks upload --task.path ./CustomTask --overwrite
Using the SDK, one can mock the parameters to the custom task. This includes being able to mock VSTS service endpoints.
$env:ENDPOINT_URL_EP1 = 'http://test.com'
$env:ENDPOINT_AUTH_EP1 = '{ "Parameters": { "ServicePrincipalId": " "ServicePrincipalKey": " "TenantId": "" }, "Scheme": "ServicePrincipal" }'
$env:ENDPOINT_DATA_EP1 = '{ "SubscriptionId": " "SubscriptionName": "" }'Versioning follows SemVer and is critical when making changes that may affect existing builds or releases using this task. VSTS will download the latest Minor and Patch changes when a new build or release is queued that uses that task. One is forced to manually upgrade to the latest Major change.
"version": {
"Major": "2",
"Minor": "0",
"Patch": "0"
},Write-Host and Write-Verbose are your friend.
An error has occurred running task...
Setting the build or release variable system.debug to true will output verbose logs.
It takes a while to upload the task, queue a build, queue a release, view the logs. Test as much of the script locally as you can.
Changing the major number will force users to manually upgrade. This can be a really good thing!
Use this to categorize your task in the catalog.
"visibility": [
"Build",
"Release"
],
Else developers will bother you...
Do not store the .NET cmdlet source in the same directory.
Consider having a process to check-in the custom task just as any source code. Build the task which may run some cleanup of the directory, restore NPM or Nuget packages and run tests and increment the version. Consider GitVersion to apply this.
Build the custom .NET PowerShell cmdlet and package it using NuGet. Publish it to a feed and restore it in your task.
- tfx-cli - https://github.com/Microsoft/tfs-cli
- Microsoft Tasks - https://github.com/Microsoft/vsts-tasks
- Microsoft VSTS Task Lib - https://github.com/Microsoft/vsts-task-lib
- Task Manifest Schema - https://www.visualstudio.com/en-us/docs/integrate/extensions/develop/build-task-schema