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:

image

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 :)