TFS 2010 – Custom Process Parameters Part 2 - MetaData

This is a continuation of the Part 1 post.

In the last post, we created a Hello World process template that uses a custom process parameter to pass in the text “Hello World!” And we showed that it worked pretty easily. But I skipped over something that perhaps you noticed. When you look at this process parameter on the Process tab of the definition editor, it doesn’t look like the other parameters – no nice name, no category, no description. In this post, I want to show you how to fix up your custom process parameters with some Metadata.

Metadata about a process parameter can contain the following pieces of information:

ParameterName – this is the unique name of the parameter specified within the XAML. This must match how the parameter is defined in the list of Arguments for the Workflow.

DisplayName – this is the string that you want to display to the user as the name of this parameter. This defaults to the ParameterName if not specified.

Category – this is a string that specifies how the parameter should be grouped with other parameters. Our built-in parameters are in one of three categories – Required, Basic, Advanced. If not specified the default is “Misc”.

Description – this is a string that gives the user more information on what the parameter does and how to use it. This string is shown in the UI when the parameter is selected in the property grid.

Editor – this is a string that specifies a custom editor for this parameter. See the Editor Attribute help for more information on the syntax.

Required – this is a bool that specifies if this parameter must be given a value by the user on the build definition. Default values in the XAML don’t matter. The user could wait to fill in the value on the Queue Build dialog, but that dialog does not require the user to take an action. Only the definition editor forces the user to fill something in (even there they can save without it). If this parameter is not given a value, the build will fail immediately.

AutoCreateInstance – this is a weird one. Basically this is a boolean that tells the build UI if it can automatically create and instance of the type for this process parameter. This defaults to true, but you may have to set it to false if the type doesn’t have a parameterless constructor. Like I said, weird. This one does not show up in the Metadata editor.

BrowsableWhen – this is a BrowsableContext value that specifies where the user can see this parameter. By default you can only view a parameter on the Process tab of the build definition. If you want to view/edit a parameter on the Queue Build dialog you can set this value to Always show the parameter.

This information is contained in the Metadata process parameter. It’s one of those special parameters that I mentioned in Part 1. Here is the XAML from Part 1 but with some Metadata added for our new parameter:

 <Activity x:Class="TfsBuild.Process" 
  xmlns="https://schemas.microsoft.com/netfx/2009/xaml/activities" 
  xmlns:mtbc="clr-namespace:Microsoft.TeamFoundation.Build.Client;assembly=Microsoft.TeamFoundation.Build.Client" 
  xmlns:mtbw="clr-namespace:Microsoft.TeamFoundation.Build.Workflow;assembly=Microsoft.TeamFoundation.Build.Workflow" 
  xmlns:mtbwa="clr-namespace:Microsoft.TeamFoundation.Build.Workflow.Activities;assembly=Microsoft.TeamFoundation.Build.Workflow" 
  xmlns:s="clr-namespace:System;assembly=mscorlib" 
  xmlns:this="clr-namespace:TfsBuild;" 
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">
  <x:Members>
    <x:Property Name="MyProcessParameter" Type="InArgument(x:String)" />
    <x:Property Name="Verbosity" Type="InArgument(mtbw:BuildVerbosity)" />
    <x:Property Name="Metadata" Type="mtbw:ProcessParameterMetadataCollection" />
    <x:Property Name="SupportedReasons" Type="mtbc:BuildReason" />
  </x:Members>
  <this:Process.Verbosity>[Microsoft.TeamFoundation.Build.Workflow.BuildVerbosity.Normal]</this:Process.Verbosity>
  <this:Process.Metadata>
    <mtbw:ProcessParameterMetadataCollection>
      <mtbw:ProcessParameterMetadata 
            Category="Basic" 
            Description="Set this parameter to the string that you want to print in the build log view." 
            DisplayName="My First Process Parameter" 
            ParameterName="MyProcessParameter" />
    </mtbw:ProcessParameterMetadataCollection>
  </this:Process.Metadata>
  <this:Process.SupportedReasons>All</this:Process.SupportedReasons>
  <Sequence>
    <mtbwa:WriteBuildMessage DisplayName="Write message" Message="[MyProcessParameter]" Importance="High" />
  </Sequence>
</Activity>

And here is how the definition looks now:

We will cover more of the metadata in future posts. By the way, if you use the Workflow Designer in Visual Studio to edit your build process templates, you will see that we have a simple editor for adding Metadata. It’s not overly helpful, but it does keep you from having to remember the XAML syntax :)

Comments

• Anonymous
  December 23, 2009
  Howdy Jason, These are great posts!  Keep them coming! I have a question about specifying a custom editor for your parameter.   If you specify an editor that is contained in a custom assembly that you manage, where does it need to be installed on end user's machines so that Visual Studio can resolve the editor's type properly?  I would imagine installing into the GAC would work but hopefully there is a common location that Visual Studio is looking for these custom editors in the Workflow Designer. Interested in hearing where that might be! Thanks again, Ed B.

• Anonymous
  January 18, 2010
  Hi Ed, I think I answered your question in my latest posts, but just in case...

1. GAC works
2. PrivateAssemblies folder under VScommon7ide should work
3. or you can include a custom activity in your assembly and check in the assembly into your controller's custom assembly path. That will automatically distribute the assembly to all clients as they need it. (Note you may have to restart VS when the assembly is updated). Hope that helps, Jason

• Anonymous
  January 18, 2010
  Thanks!  I just read them this morning when they were posted.  I think I prefer the method of storing them in the version control folder where the rest of the custom Team Build assemblies are stored and configured with the build controller. I wasn't sure if the Team Explorer dialogs would actually know how to pick up custom editors from there as well but I'm glad that was well thought out in the feature design! Thanks again for your great posts.

• Anonymous
  February 11, 2011
  Great post. Is there any way to have an Array type parameter? For example, I want to have multiple deployment directories.

• Anonymous
  July 20, 2011
  The comment has been removed

• Anonymous
  July 20, 2011
  "By the way, if you use the Workflow Designer in Visual Studio to edit your build process templates, you will see that we have a simple editor for adding Metadata." Where is this editor? I can't seem to find it in Visual Studio.  Thanks for the great post.

• Anonymous
  July 20, 2011
  Bah, I was looking for another whole VS window.  Turns out you just have to find the Argument labeled "Metadata" and open it's Default Value collection.  This page shows how to do it: www.ewaldhofman.nl/.../Customize-Team-Build-2010-e28093-Part-2-Add-arguments-and-variables.aspx

• Anonymous
  June 08, 2012
  The comment has been removed

• Anonymous
  August 31, 2014
  Hi do you know if it possible to show the sub elements of a custom datatype in the build definition file? For example in the 'Agent setting' the menu expands to its sub elements in the same way I want to show the elements of my own datatype.Thanks!

• Anonymous
  September 01, 2014
  To have your properties be expandable in the WinForms property grid, you have to put the ExpandableObjectConverter on them as a typeconverter. Look for examples of this converter and you should find plenty of examples. Thanks, Jason

• Anonymous
  February 03, 2016
  Hi, For me it's not showing the category names. What might be the problem?