Debugging your VSTS extension

Recently I’ve been working on developing some extensions for Visual Studio Team Services (VSTS). Being able to develop custom extensions is great, since it enables you to extend the service with features that fulfil your needs.

Creating an extension for VSTS consists of a few steps:

  1. Develop the code
  2. Package the extension
  3. Publish it to the marketplace
  4. Install it in your VSTS account
  5. Start using your extension!

In order to use your extension inside VSTS, you have to go through all these steps. When you’re still developing and debugging your code, this makes for a very painful process. There is a neat little trick that you can use to overcome this, which makes debugging a VSTS extension much easier. It is described somewhere in the documentation, but it’s very well hidden so I thought I’d write a blog post about it.

How extensions work

Extensions for the VSTS web interface are actually web pages which are loaded inside an iframe in the VSTS UI. VSTS supports many extension points, and you can use whichever one suits your purpose best. For example, an extra tab on the work item form, a dashboard widget, an additional hub group or even an entire hub. When VSTS loads the html page for your extension, it will become visible in the UI. Inside your html page you include the VSTS extension SDK (“VSS.SDK.js”). That will take care of properly loading your extension inside the VSTS UI and will make some services available to your extension for getting data from and to VSTS. To put it all in a picture:

image

In order for your extension to load in VSTS, VSTS has to know some things about it, like: where to load your extension (e.g. as a dashboard widget or hub group), which html page to load and which permissions are required. These things are configured in your extension manifest. This manifest is used when packaging and publishing your extension to the marketplace. From there, it can be installed in your VSTS account.

The manifest also specifies from where your extension html should be loaded. If you have a simple extension with just a few static html/javascript/css files you can package these with your extension and they will be hosted inside VSTS. If your extension is more complex (e.g. you have some ASP.NETpages) then you will need to provide your own hosting and specify that in your manifest.

Preparing the debugging

When I’m developing an extension, I’m using Visual Studio. Of course I want to be able to use all of Visual Studio’s debugging power and do quick iterations (write code, hit F5, check if it works). In order to make this work we’ll trick VSTS to load our extension html from our local machine. Of course this won’t work for production scenario’s, but for debugging it’s fantastic.

In order to do so we’ll create a special manifest for development (in my case: “vss-extension-debug.json”). Inside that manifest, there are a few properties that we’ll change especially for debugging purposes:

{
  ...,
  "id": "devdemoextension",
  "name": "Dev: Demo Extension",
  "baseUri": "https://localhost:44300",
  ...
}

  • id: the id has to be unique across all your extensions. I usually prepend “dev” for my development versions.
  • name: this will be displayed in the VSTS marketplace and when you’re installing the extension in your account. I usually prepend “Dev:” so that I can identify the development version
  • baseUri: this is where the magic happens. This tells VSTS to load the extension from your localhost, where you have your development version running in IISExpress from Visual Studio.

Note: you have to run IISExpress in SSL mode, because VSTS demands that your extension is served from a secure source. You can enable SSL mode in the properties of your project in Visual Studio:

image

Now package your extension using the manifest modified for debugging:

vset package -m vss-extension-debug.json

Upload the resulting .vsix file to the marketplace and share & install it in your account. For instructions on how to do this, you can refer to the Visual Studio site.

Doing the debugging

Now that we have all the Yak shaving done we can get to the actual debugging. The easiest way to do this is to change the properties of your project in Visual Studio and set the Start URL to the location where your extension will load:

image

This will make sure that the debugger is attached to the correct browser process.

Now hit F5 and you’ll be able to use the full power of the Visual Studio debugger!

Happy debugging!

Advertisements

One thought on “Debugging your VSTS extension

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s