New requirement when updating Team Services extensions on the Marketplace

If you develop extensions for Visual Studio Team Services or Team Foundation Server, there is a new requirement during publishing that you should be aware of: when updating an extension on the Marketplace, the updated extension’s version number must be greater than the published extension’s version number. To say it another way, you must increment the version of your extension every time you update it. As an example, if your extension is currently published to the Marketplace at version 0.9.0, attempting to upload version 0.8.0 will fail. In TFX this will be reflected with a message similar to this:

Version number must increase each time an extension is published. Extension: fabrikam.my-extension Current version: 0.9.0 Updated version: 0.8.0

This change only impacts Team Services extensions, not Visual Studio Code extensions.

Why the change

Up until now, the Marketplace did not enforce that an extension’s version number be incremented on update. Although this made life easier during development, it resulted in problems downstream. For example, different variations of an extension with the same version number make it difficult for developers to correlate problems back to the appropriate version of the source code. It also makes it difficult for Team Foundation Server 2015 users to definitively know what version of an extension they are actually running. This change is also necessary to support some upcoming features (stay tuned).

Tools to help

If you already increment your extension’s version number before you publish an update, good job – keep doing what you’re doing! If not or you don’t want to manage your extension’s version, there are a few tooling options to help.

TFX

The latest version of TFX (0.3.26 and later) introduces a new argument to increment the last segment of the extension’s version number:

tfx extension create --rev-version

This reads the current version from the manifest file, increments the value in the third segment of the version (the patch segment), writes the new version to the local file, and then creates the package.

As an example, assume the extension manifest file currently has a version of 0.4.10. After running TFX with the –rev-version argument, the version in the local manifest file and resulting .vsix file will be 0.4.11.

For more information, see TFX extension commands.

Build and Release Tasks for Extensions

A few months ago, we (with help from the ALM Rangers) released a set of build and release tasks that help extension developers package, publish, and manage their Team Services and Team Foundation Server extensions. Of course, these tasks were packaged as an extension and made available on the Visual Studio Marketplace.

One of the tasks, Query Extension Version, queries the Marketplace to get the current version of a specified extension. The task then increments the specified segment (MAJOR.MINOR.PATCH) of the extension’s version. This new version is stored as a variable that can be used in a later Package or Publish task to override the version from the manifest file.

As an example, Team Calendar is a public extension maintained by us (Microsoft) under our DevLabs publisher. We use the build and release extension tasks in a Team Services-hosted CI build process to package the Team Calendar extension when updates are pushed to its public GitHub repository.

A “query extension version” step gets the current version of the published extension, increments the minor version segment, and saves the new value in a build variable called Extension.NewVersion:

query-version-step

A later “package extension” step uses the value from the Extension.NewVersion build variable when creating the .vsix package (no change is made to the source manifest file):

Extension package step that overrides the variable with a variable set earlier in the build process.

The end result is a compiled .vsix file, with a version that is greater than the version currently published.

We know that any change to a day to day process can be tough, but this is an important and necessary change. We welcome your feedback on this.

Will Smythe, Program Manager at Microsoft