Pipeline extension scoped to a specific TFS or Agent version

In The Netherlands more and more cities are creating an artificial wall around the city centers for older cars, certain fuel types or lorries. This is happening elsewhere in Europe as well. A similar things needs to happen in the Azure DevOps marketplace now that the number of supported target server versions is increasing.

As an extension developer it is becoming harder and harder to retain compatibility with all the different TFS versions out there as well as with Azure Devops with its high release frequency.

While Microsoft officially only supports the RTM and the latest Update pack of each major TFS version (2015, 2015.4.1, 2017, 2017.3, 2018.0.1 and 2018.3), many clients are lingering on some version in between 2015 and 2018.3 and wish for your extensions to work with their version.

Up until now I've simply had my extensions target Azure DevOps and TFS. No version limitations. Yet with the introduction of YAML and Output Parameters and more modern versions of the underlying Node runtime, I'm considering adding these features which may break 2015 and 2017 versions of my build tasks.

There are multiple places where a task developer can scope their extensions or tasks. Let's have a quick look at our options:

Ways to target your extension to Azure DevOps and/or TFS

The simplest option you have is to scope the vss-extension.json manifest file to Azure DevOps or TFS using the Installation targets:

You can either list support for Azure DevOps and Team Foundation Server explicitly or use the older Visual Studio Services option that still stems from the time Azure DevOps was called Visual Studio Online.

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
        }
    ]
}

Is the explicit equivalent of:

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Ways to target specific versions of Team Foundation Server

In my case I want to support TFS 2018 and Azure DevOps, since TFS 2018 has support for the new Output Variables. In order to exclude older versions of TFS you'll need to add a version to your target. The exact syntax is clearly defined in the docs.

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[16.0,)"
        }
    ]
}

It's better to target API versions instead of Servers

If you're dependent on the availability of a specific API version, then you can add demands to your extension manifest instead of a version range. These demands ensure that the server you're installing into has the required server side APIs available:

{
    "demands": [
        "api-version/3.0"
    ]
}

You can demand the availability of an extension point as well:

{
    "demands": [
        "contribution/ms.vss-dashboards-web.widget-catalog"
    ]
}

The marketplace will compare the demands against the known APIs in Team Foundation Server and will show the correct list of supported servers, even if a demand is added to a later update pack without your knowledge. Nifty eh? The same should go for Preview features.

Unfortunately there is no way to demand specific Build and Release features. You can't demand "Release Gates available" as an option, though you may be able to work around this by looking up some of the UI extension points for these features.

Similarly, you can't demand a minimum agent version for your extension. You can for tasks, but that won't prevent people from installing the extension to a TFS server version that will never be able to run your tasks.

So what about build and release tasks?

Your build task contribution comes with its task.json manifest and you can tweak a few settings there to show support for different versions.

minimumAgentVersion

If you're dependent on a feature in the VSTS Task API that depends on a specific version of the agent, you can set the minimumAgentVersion property in the Task Manifest. A comprehensive list of agent versions and API features can be found int he vsts-task-lib docs.

The same page also lists which versions of the Agent have sipped with which versions of TFS. This will allow you to set the supported target version in the vss-extension.json accordingly.

{
  "minimumAgentVersion": "1.83.0"
}

demands

Another way to handle compatibility checks is through Demands. Demands are matched against the capabilities of the available Agents and against the capabilities provided by other tasks (like Tool Installers).

As a task author you can also specific custom demands that Agent Administrators need to configure on each Agent. This will signal the agent is compatible and will at least force an DevOps Pipelines administrator to look into the compatibility requirements of your task.

A long list of demands is available by default, but unfortunately, you can't perform any logic on them. You can only detect the presence of a demand from your task manifest.

And you'd almost expect to be able to read these agent capabilities from your task, but that's also not the case. Some of these are System level and user level Environment Variables, you can get to their values through there, others are supplied by the agent itself and aren't easy to resolve.

Querying the agent version

The Agent will set a Variable you can read from your tasks and a function in the Task Library to ensure you're running on the right agent:

/**
 * Asserts the agent version is at least the specified minimum.
 *
 * @param    minimum    minimum version version - must be 2.104.1 or higher
 */
export function assertAgent(minimum: string): void {
    if (semver.lt(minimum, '2.104.1')) {
        throw new Error('assertAgent() requires the parameter to be 2.104.1 or higher');
    }

    let agent = getVariable('Agent.Version');
    if (agent && semver.lt(agent, minimum)) {
        throw new Error(`Agent version ${minimum} or higher is required`);
    }
}

As you can see in the snippet above, this variable was introduced with agent 2.104.1, detecting it's presence will tell you you're on an older agent, but no on which.

If you'd ask me, this isn't ideal yet.

As task author there is no way to package multiple tasks in the same extension with different supported target platforms. There's no way to ship a version which presents a different UI in 2015 than in 2018 and slowly the number of features available between all the versions of TFS in the field is growing larger.

I hope the Azure DevOps or the Visual Studio Marketplace team will be able to provide us with ways to target specific extension versions to specific TFS versions. That may be the only backwards compatible way that will allow us to keep using the same Extension ID and Task ID in our extension; Which is the only way to not break your users on upgrades.