VSS Web Extensions SDK Update (version 1.108.0) - Breaking Changes

Symptom

If you are building a VSTS (or TFS) web extension, be aware of the breaking changes that come from the new SDK version.

Cause

Last week a we pushed a new release of the SDK (vss-web-extension-sdk@1.108.0). This release comes with some important dependency updates:

• React: now react types are included
• The Rest API version bumped to 3.0
• Typescript compiler bumped to 2.0.3

Resolution

If your extension was built using typescript, you may experience build problems when you update to this new version. Let's see how to handle these problems:

• With the addition of react, now you need to include React in the typing of your code, or you will see a build error related to this dependency. Add the React typing as explained in the SDK page:
  

NOTE: The way that you will handle this will depend if you're using TypeScript Definition (tsd) or typing.

• If you are using the Rest APIs, you may get some build errors due to interface changes. For instance, I built an extension that uses the Build API, and I got a build error because, one of the methods was using `GetBuilds()`, has changed its interface (some parameters have changed).  Be aware of these changes because now the SDK is using version 3.0 of the Rest API. You can look here to see differences of the API versions.
• Finally, the most breaking change, the compiler. Now the SDK is using Typescript 2.0, and as we can see here, this new major version of TypeScript introduced some compilation incompatibilities with earlier versions. You now have to build your extension using a newer version of TSC (Typescript Compiler), that ships with the TypeScript package. This can be made in different ways depending on the way you are building your extension. For example:
  • If you are using an NPM package of TypeScript,  with a build tool (like Grunt, Gulp, etc.) or a simple script, you just should update the npm package.
  • If you are using the Visual Studio Typescript Extension, you will need to update the extension, because it uses the MSBuild package of TypeScript.
  • If you are building using a NuGet package, you will need to update it.

We suffered a little bit with this update. As you can see in our open source extensions, most of our extensions use the Visual Studio project template for VSTS extensions. It is a Visual Studio project template that comes with all common files needed to build VSTS extensions. It's a good jump start. But, as it is a Visual Studio project, it uses MSBuild and its targets to build the code. It depends on the TypeScript for Visual Studio package, that installs all MSBuild targets and TypeScript libraries. Even if you include a dependency for TypeScript in you code through a NPM package, MSBuild won't use it. It will look for the TypeScript binaries and libraries at the default TypeScript for Visual Studio installation path (C:\Program Files (x86) \Microsoft SDKs\TypeScript).

Ok, but what is the problem? Well, we use a VSTS hosted build agent to build our extensions, and the hosted build doesn't have the latest version of TypeScript for Visual Studio installed, yet (at the time this post are written). So, some of our builds started to fail after the update.

It took some time for us to discover this issue. We preferred not to wait and not to be dependent on a hosted build agent update. So we changed our build scripts to be more robust after this event.

• Some teams opted to use commonly used tools to build TypeScript (like grunt, gulp, …).
• Others remained with MSBuild, but using a NuGet Package version of MSBuild targets for TypeScript. It requires a specific configuration in the *.csproj file, but makes MSBuild look for the binaries and libraries of TypeScript in the NuGet package. This avoids the hosted build agent issue, because all code dependencies stay self-contained in the build process. You only need to add a "NuGet restore" command line in the build script. Look here for detailed instructions to this approach.

Applies to

Extensions for Visual Studio Team Services and Team Foundation Server