Visual Studio

Navigating to Team Explorer Pages and passing along Context & Parameters

When creating your own VSTS / TFS Visual Studio Extension you may want to navigate to Team Explorer pages, either to your own or to built-in ones like Code Reviews, TFVC Changeset or Git Commit Details.

The corresponding method to do so is the ITeamExplorer.NavigateToPage() one which takes the target page’s .Id as parameter and an context one. The former are usually quite easy to get ahold of – when creating and providing your own Team Explorer navigation and page items you must provide and therefore know their corresponding Ids but the VS built-in pages’ Ids are also available in a central location named TeamExplorerPageIds.

Providing the right context (type) however may be a bit more tricky. As long as you know the target page does not require any context (and can handle null properly), you can go ahead and navigate to it i.e. like this:

var teamExplorer = serviceProvider.GetService(typeof(ITeamExplorer)) as ITeamExplorer;

teamExplorer.NavigateToPage(new Guid(TeamExplorerPageIds.MyWork), null);

However, if the target page does require a context to be passed in, having an object as parameter type obfuscates what the target page is expecting and unfortunately Visual Studio’s own Team Explorer pages’ parameters aren’t documented.. or the documentation is well-hidden. I’ll list the ones I know below, but for your own Team Explorer pages you can obviously pass along whatever context parameter you deem necessary when navigating to it and you’ll get it handed over in the ITeamExplorerPage.Initialize() method you have to implement for your page, more particularly its PageInitializeEventArgs.Context parameter.

Users may obviously navigate away from your page (or change connections, projects etc) and whenever that happens, your ITeamExplorer.SaveContext() method is called which allows you to store the current context for your page. It’s up to you how broad or narrow you define the term context here – it may for example only be a work item .Id but you may also use context more broadly and save visual state of your page along with it.

As for the aforementioned core Visual Studio Team Explorer pages, I’ve come across the following contexts you can or have to provide when navigating to the corresponding pages & unless mentioned otherwise, the ITeamExplorer.NavigateToPage(pageId, context) parameter is always a Dictionary<string, object> – the keys and value(types) being:

  • Builds
    • Key: “QueuedBuildId
    • Value: <Build Id> (int)
  • Request Code Review
    • Key: “Workspace
    • Value: <Workspace instance> (Workspace)
      or
    • Key: “ChangesetId
    • Value: <Changeset Id> (int, see Changeset.ChangesetId)
      or
    • Key: “Shelveset
    • Value: <Shelveset Instance> (Shelveset)
      or
    • Key: “ShelvesetName
    • Value: <Shelveset Name> (string, see Shelveset.Name)Please Note: for both, “Shelveset” and “ShelvesetName” there’s a second Dictionary key-value pair that you should provide:
    • Key: “ExcludedCount
    • Value: “<Count of excluded Changes from Shelveset>” (int, why this parameter is required is unbeknownst to me however)
  • View Code Review
    • Key: “WorkItem
    • Value: <Work Item Instance> (WorkItem)
      or
    • Key: “WorkItemId
    • Value: <Work Item Id> (int OR string)
  • Changeset Details
    • Cannot be called (unless using Reflection, which I’d not recommend), the context is an instance of type ‘ChangesetDetailsContext‘.. which is an internal class
  • Shelveset Details
    • Same as with Changesets – the context object is actually an instance of the internal type ‘ShelvesetDetailsContext‘ and therefore cannot be instantiated without Reflection.
  • Find Shelveset
    • .. and again – same for finding Shelvesets – the internal class used here is of type ‘FindShelvesetsModelContext’

 

I haven’t covered Git (commits, branches etc) here, yet – this might come at a later point.

What’s also worth mentioning, is that I’ve created a couple convenience wrappers for all these and other Team Explorer page navigations in my ‘JB.Common.VisualStudio.TeamFoundation‘ NuGet package (you might want to get the pre-release one), particularly as ITeamExplorer extension methods.

Discussion

Comments disabled.