Using the NavigationService in your VSTS and TFS extension

Last week a user of our Team Project Health extension reported an issue when using the extension on Team Foundation Server 2018. TPH delivers a set of dashboard widgets that give you a quick overview of the status of your builds and releases.

Figure 1 – On the ALM Ranger VSTS account we have a dashboard showing the build status of all our tools and extensions


When you click on one of the build detail widgets, a new tab is opened with the details of that build. However, the user was reporting that when navigating to the details of a build he got the following error:


Figure 2 Navigating to the build details from an extension tile shows an unauthorized exception

Reproducing the issue

To reproduce the issue I used my local TFS 2018 install. First I quickly created an empty project with a simple build definition that runs a PowerShell script that displays ‘Hello World’. I’ve configured my machine as a private build agent to run the build.


Figure 3 A very simple successful build definition

Now that I have a build, the second step is to install the TPH extension into my local TFS 2018 instance and create a dashboard. Installing an extension to TFS when it’s connected to the internet is very easy. Go to your Team Project Collection Settings à Extensions and open the Marketplace by selecting Browse Marketplace.


Figure 4 TFS allows you to browse the Marketplace and install extensions

You are then redirected to the online Marketplace. Here you can search through the extensions and select Install to install the extension directly into your TFS instance. The following screenshot shows that the Marketplace knows you’re coming from TFS and helps you by redirecting back to TFS and completing the installation automatically.


Figure 5 The Marketplace helps you to install the extension automatically in TFS

The last step is to add the newly installed widgets to a dashboard.


Figure 6 A simple dashboard showing the build and release detail and overview widgets

And indeed, clicking on the Build detail tile opens a new tab that shows the error from the GitHub issue.

Fixing the issue

The HTML for the Build detail tile contains the following snippet:

All we did was get the URL from the build and set the href attribute on the <a> tag.

After discussing the issue with Microsoft they suggested to use the NavigationService to handle opening the new window like this:

To test the code change, you need to compile the extension, increase the version number in the manifest and build an extension package. You can then upload this extension package to TFS and install it without using the public Marketplace.

And that’s it! This small code change fixed the issue. Whenever you want to navigate to a page in a new tab, make sure to use the HostNavigationService so the authentication context is passed along correctly and everything works as expected.

The TPH extension is fully open source on GitHub and you can view the commit that fixed this issue yourself here:

After committing the changes, our delivery pipeline builds the extension and deploys it fully automated to a test environment. After testing the extension to make sure we didn’t miss anything, the extension is approved and automatically released to the public Marketplace.

Happy extension building!