Porting VSS Web Extension SDK to Azure DevOps Web Extension SDK

To develop an Azure DevOps Web Extension, you can either use the VSS SDK or Azure DevOps SDK.

The Azure DevOps SDK (AzDO SDK) is newer and has many advantages over the old VSS SDK such as: better performance, more consistent UI and theming support.

If your extension has been developed using the old SDK and now you want to migrate over the new one, you may find this porting guideline helpful.

Loading Bundle

1. Using the old way

<! --- index.html --->
<script type="text/javascript">
    VSS.init({
      applyTheme: true,
      explicitNotifyLoaded: true,
      setupModuleLoader: true
    });
    VSS.ready(function () {
      VSS.require(["../dist/my-bundle"], function (app) {
        VSS.notifyLoadSucceeded();
      });
    });
</script>

2. Using the new way

Make sure to remove libraryTarget: “amd” in your webpack config file. Otherwise, you’ll encounter define is not defined error since the AzDO SDK doesn’t support requireJS.

<! --- index.html --->
<script type="text/javascript" src="../dist/my-bundle.js" charset="utf-8"></script>
...
// index.tsx
import { init as sdkInit } from 'azure-devops-extension-sdk';
sdkInit()
  .then(() => {
    ReactDOM.render(...);
});

Fixing Data Types in the “import” statements

Most data types don’t change so you just need to find/replace to update the import paths.

Updating Services

There are some small changes when invoking services but the results are the same.

Updating REST Clients

Most REST Client classes and interfaces have been renamed to something else but their methods stay the same.

Other Porting Notes

1. Getting the current user’s info:

import { IUserContext, getUser } from 'azure-devops-extension-sdk';
const user: IUserContext = getUser();
const id: string = user.id;
const name: string = user.name;
const displayName: string = user.displayName;
const imageUrl: string = user.imageUrl;

2. Getting the app token used to authenticate with your back-end service:

import { getAppToken } from 'azure-devops-extension-sdk';
const token: string = await getAppToken();

3. Getting the host base URL (e.g. “https://dev.azure.com/your_organization”)

import { getService } from 'azure-devops-extension-sdk';
import { CommonServiceIds, ILocationService } from 'azure-devops-extension-api';
import { CoreRestClient } from 'azure-devops-extension-api/Core';
const locationService = await getService<ILocationService>(CommonServiceIds.LocationService);
const hostBaseUrl = await locationService.getResourceAreaLocation(
    CoreRestClient.RESOURCE_AREA_ID
  );

4. Getting the project info:

import { getService } from 'azure-devops-extension-sdk';
import { CommonServiceIds, IProjectPageService } from 'azure-devops-extension-api';
const projectPageService = await getService<IProjectPageService>(CommonServiceIds.ProjectPageService);
const projectInfo = projectPageService.getProject();
const projectId = projectInfo.id;
const projectName = projectInfo.name;

5. WorkItem field ‘System.AssignedTo’ returns JSON instead of string:

When using the new REST clients to query for work items, the returned field System.AssignedTo is a JSON object so to get the assignee’s display name, you must use: workItem.fields[‘System.AssignedTo’].displayName.

Helpful Resources:

• Unit Testing Azure DevOps Extensions
• Downloading Extension Certificates from Azure DevOps Marketplace programmatically