Team Foundation Build: Enhancing the experience with built-in custom editors

4 minute read

When designing or customizing a Team Foundation Build process template you may have parameters that are not as basic as an integer or a string. You may want to provide your user with a nice UI to edit the values either when designing the build process template (for defining custom values for example) or queuing the build (in cases where the parameter can be defined/overridden when the build is queued).

Even when the parameters are of primitive types defined by .Net, you may want to provide a nice editor that allows easier editing for a parameter that doesn’t have a simple syntax. One example is the Team Foundation Build built-in Build Number Format ****editor.

Image 1: BuildNumber format Editor

While writing such an editor is easy, (I will not go into such details since Jason Prickett has already done a great post about it.

While writing this kind of integration is pretty easy writing the UI for object may be a somewhat tedious and long task. For example you want to reference objects stored inside TFS like a file stored in source writing the navigation can take some time.

This was exactly the situation I faced recently; designing a complex process template in which I have (among many others) two parameters which reference a path and a file in source control.

While power users don’t mind entering $/MyTeamProject/MyProject/Trunk/ in a text box, it’s not something a regular user would want to do.

While writing the glue to Team Foundation Build is easy, writing a source control folder picker like Browser for Folder requires some work.

Image 2: Browser for Folder

I would rather spend my time providing business value than writing plumbing. Since Microsoft obviously already has some code in place it would likely just be a matter of leveraging that.

There were basically two possibilities:

The browser picker UI is publically available and we just have to write a few lines of gluing code to integrate it with the Team Foundation Build user experience
Microsoft provides a publically accessible designer so we can just use it without having to write a single line of code.

Alas, none of these options appears to be available.

While 1) is available with some reflection hacking (see this post from Mathias Olausson)

Option two is preferred (no code is always better than some code Smile )

Not all is lost however; there is no publically available designer but there is an internal one (which means it may change in the next version but highly unlikely)

Luckily, they are implemented in Microsoft.TeamFoundation.Build.Controls assembly, which is where the UI for the builds is also stored. So we can freely reference it the Editor Parameter in the Metadata argument to enhance our user experience. (see Jason Prickett’s post on how to do this)

So just enter Microsoft.TeamFoundation.Build.Controls.ServerFileBrowserEditor, Microsoft.TeamFoundation.Build.Controls in the editor parameter and everything is set.

Image 3: Editing the Editor parameter to specify the custom designer

When editing the build definition (or queuing if the parameter can be defined/overridden while queuing) the parameter will have an ellipsis button

Image 4: Ellipsis Available to use

Upon clicking on the button you will be presented with the dialog

Image 5: Browser Dialog

Not bad for something that takes 15 seconds to implement and greatly enhances the user experience.

Other designers included in the same assembly, that you can leverage to improve the user experience

<td valign="top">
  <strong>Description</strong>
</td>

<td valign="top">
  Select an agent, I doubt this is useful in a build template, but there is always one strange scenario I can’t anticipate
</td>

<td valign="top">
  Select a project (typically a .sln or .csproj) from source control. Great if you want to build a project but it isn’t .Net so there is no platform settings baggage to carry
</td>

<td valign="top">
  Select a file in source control
</td>

<td valign="top">
  Select a spec of tests to run
</td>

<td valign="top">
  Select a work item type
</td>

<td valign="top">
  Select a folder in source control
</td>

<td valign="top">
  Edition of a list of string. </p> 
  
  <p>
    Also allows reordering of the items
  </p>
  
  <p>
    The argument should be of type <strong>List<string></strong> or <strong>Microsoft.TeamFoundation.Build.Workflow.Activities.StringList</strong>.
  </p>
</td>

<td valign="top" width="141">
  Shows the list of possible values of an enumerated allows you to easily select one of them </p> 
  
  <p>
    In this screenshot we are editing a argument of type <strong>Microsoft.TeamFoundation.Build.Workflow.BuildVerbosity</strong></td> </tr> </tbody> </table> 
    
    <p>
      &#160;
    </p>
    
    <p>
      Note: Don’t forget to add the namespace (<strong>Microsoft.TeamFoundation.Build.Controls)</strong> and the assembly name also. So when you read <strong>ServerFolderBrowserEditor</strong> you should enter in the editor as <strong>Microsoft.TeamFoundation.Build.Controls.<strong>ServerFolderBrowserEditor</strong> , <strong>Microsoft.TeamFoundation.Build.Controls</strong> </strong>
    </p>
    
    <p>
      If you to learn more about customizing the build parameters you can read the (faster way) this post series from Jason Prickett
    </p>
    
    <ul>
      <li>
        <a href="http://blogs.msdn.com/b/jpricket/archive/2009/12/23/tfs-2010-custom-process-parameters-part-1.aspx">TFS 2010 – Custom Process Parameters Part 1</a>
      </li>
      <li>
        <a href="http://blogs.msdn.com/b/jpricket/archive/2009/12/23/tfs-2010-custom-process-parameters-part-2-metadata.aspx">TFS 2010 – Custom Process Parameters Part 2</a>
      </li>
      <li>
        <a href="http://blogs.msdn.com/b/jpricket/archive/2010/01/18/tfs-2010-custom-process-parameters-part-3-custom-editors.aspx">TFS 2010 – Custom Process Parameters Part 3</a>
      </li>
      <li>
        <a href="http://blogs.msdn.com/b/jpricket/archive/2010/01/18/tfs-2010-custom-process-parameters-part-4-custom-types.aspx">TFS 2010 – Custom Process Parameters Part 4</a>
      </li>
    </ul>
    
    <p>
      If you want to read everything about builds and its process customization you can read the (slower but more complete way) <a href="http://rabcg.codeplex.com/">Rangers Build Customization Guide</a>
    </p>
    
    <p>
      Kudos to <a href="http://mikefourie.wordpress.com/">Mike Fourie</a> who had the patience to proofread and even enhanced this post.
    </p>