Develop your Visual Studio Team Services extension live

In previous post I’ve guide you on developing and publishing your first VSTS extension. This time I will show you how to prepare the extension and the environment for debuging. To be frankly developing a VSTS extension is in my opinion impossible if you have no chance to debug your code.

Thanksfully, all of the magic regarding VSTS extension happens basically in the client’s web browser, since the extension itself is simply a piece of a java script, html and css. That means you should be able to debug it right in your web browser. And that is actually true and Microsoft even provide some guide on that, so you can easilly look up what is going on in your extension at runtime.

That’s debuging. But the things are different when you want to write some code, test it, correct it, test it again and so on. We cannot do it in our development environment directly, because we have no VSTS context. But fortunatelly we can attach to the browser running our VSTS extension online. See how to do it.

To have a big picture first I will split it in some steps

1. Host your VSTS extension on local IIS Express with SSL
2. Publish a mock extension that will “cheat” the VSTS platform
3. Attach you IDE to the browser running VSTS with mock extension

Basically all the magic is based on fact that VSTS accept an external source of the extension content files. That is possible by setting the baseUri attribute in extension manifest. The extension can have all its files packaged together within or can load them from an external location. Now the thing is this external location does not necessarily have to be, well external. If the extension runs in our web browser we can tell it to look for the content on our localhost web server. And when we are running something on localhost we can easilly debug it.

1. Host your VSTS extension on locall IIS

I’m using the Visual Studio Code (VSC) for development of the VSTS extension, so all examples will refer to this IDE, but the most important here is the idea, not the tool. So assuming we have our simple extension, created by calling the command yo team-services-extension (as descripbed in previous post) in D:\research\my-job we need open in in VSC. In order to run it on IIS Expres we need a special VSC extension. Go to market place and install IIS Express. Now press Ctrl + Shift + P and choose IIS Express: Start Website

You should get new browser window with your application hosted on local IIS with default settings. Since the VSTS extension is basically a html + css + typescript application, you should see some sontent on the page. However we need to modify the default hosting settings. The VSTS platform requires the external content to be provided via SSL. Go to you VSC and under .vscode folder you should find configuration file called iisexpress.json. Make sure the entry in it looks like this

{
  "port": 44300,
  "path": "d:\\research\\my-job",
  "clr": "v4.0",
  "protocol": "https"
}

Note the https protocol instead of http. That wll cause to run our extension with SSL encription (self signed certificate is used) on locall IIS Express web server. After saving the configuration file, you may need to restart you instance of VSC and then you can run the page again, but before that we need one more small thing to be done. Go to

D:\research\my-job\node_modules\vss-web-extension-sdk\lib

and copy whole lib folder up to the main extension folder

D:\research\my-job\lib\

so the main VSS SDK script file is accesible from the index.html

<script src="../lib/VSS.SDK.min.js"></script>

This is required, because since our debuging version of the extension is running locally it needs to know the definition types of the VSS API.

You should be able to see the page under https://localhost:44300/static/.

2. Publish a mock extension to VSTS

Next we need to add, mentioned before, baseUri parameter to our extension manifest, bild the extension and publish it to the marketplace.

Open the vss-extension.json file and make sure to add following line

"baseUri": "https://localhost:44300"

Remember to increase the version number (if you’ve already published this extension before) and upload it to the marketplace.

3. Attach Visual Studio Code to the browser process running your VSTS extension

Ok now the crucial step. Go to VSC extensions tab and install the Debugger for Firefox. If you are using Chrome then check out the Debugger for Chrome. Follow the instructions on the debugger extension page for the attach mode
In short, in case of using Firefox you will have to

1. Enable debug options in firefox settings (devtools.debugger.remote-enabled and devtools.chrome.enabled)
2. Run the Firefox instance with debug option. In Windows hit Win + R and type in
   "C:\Program Files\Mozilla Firefox\firefox.exe" -start-debugger-server

Now make sure you only have one Firefox window opened, becasue the debugger settings applies to all of the instances and that could cause problems during the debugging process. 
Next, go to VSC and ensure your extension is running on IIS Express again. Open it in the FF running debug mode, new tab.

In your extension folder under VSC go to .vscode folder and open launch.json file. This file contains a debuging configurations used in VSC. Make sure you add following configuration

"configurations": [
        {
            "name": "FF attach",
            "type": "firefox",
            "request": "attach",
            "reloadOnChange": {
                "watch": "${workspaceFolder}/dist/*.js",
                "ignore": "**/node_modules/**"
            },
            "pathMappings": [
                {
                    "url": "https://localhost:44300/",
                    "path": "${workspaceFolder}/"
                }
            ]
        }
    ]

That will basically tells the debugger to reload the page whenever the source file has changed. It also provides the mappings so the browser knows where to take the source files from.

Additionally we can instruct the Type Script compiler to automatically compile out our .ts files to .js file on save. Simply open tsconfig.json file and add a watch option

{
  "compilerOptions": {
    "module": "amd",
    "moduleResolution": "node",
    "target": "es5",
    "rootDir": "src/",
    "outDir": "dist/",
    "watch": true,
    "types": [
      "vss-web-extension-sdk"
    ]
  },
  "files": [
    "src/app.ts"
  ]
}

Having that we have a super convinient debuging environment.

Open another tab in your browser running in debug node and navigate to your visual studio online portal. Go to your extension page. You will probably need to hit F12 and reload the browser cache so the local files are loaded instead of the cached ones.

Now finally go to Visual Studio Code, navigate to debuging panel, in the debug configuration list select FF attach and start debuging. You should be able to put a breakpoint in the app.ts file and after reloading the page get the breakpoint hit

If you encounter any problems, for instance the breakpoint doesn’t get activated, or does not get hit, try one of the following tips:

1. Stop IIS Express (look for the server icon in the windows taskbar) and restart the page
2. Restart debuging process in Visual Studio Code
3. Refresh the browser ensuring the cache is relaoded
4. Restart the browser in debug mode again and do all above

What is extremly convinient with this solution is that you can make a changes to your code, html, or css and immediatelly test them within the real VSTS environment. That makes the development of VSTS extension almost as easy as developing regular web or desktop application right in your local dev environment.

Hope that will help with your VSTS extension development.