TFS 2010 – Custom Process Parameters Part 1

What are process parameters? These are the objects that we pass into the build process that determines what will be built, what tests to run (and how), and all the other switches that decide what happens.

How are they passed in? The process parameters can be set and/or modified in 3 different places. The XAML files (our process templates that are checked into version control under the BuildProcessTemplates folder) determine the types and names for the process parameters (they can be different for every process template). This is the first place you can set the value for a process parameter by specifying a default value for the process parameter within the XAML. When you create a definition you pick the build process template that it will use and so pick the process parameters that go with it. On the Process tab of the definition is where you can change the values of most process parameters for the second time. When you queue a build manually through the Queue Build dialog, you get your last chance to change the process parameters before the build starts.

What types are allowed for Process Parameters? As long as the type can be serialized by the XAML serializer (think Windows Workflow or WF), then you can use it as the type for a process parameter.

So, what do I mean by a custom process parameter? I just said that the process parameters are determined by the XAML. However, you can change the XAML :). So, let’s create our own process template and add a simple string process parameter and print it out in the XAML.

Scenario:

Create a “Hello World” build process template using a custom process parameter.

Here’s the XAML that I put into a file called HelloWorld.XAML:

 <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 />
  </this:Process.Metadata>
  <this:Process.SupportedReasons>All</this:Process.SupportedReasons>
  <Sequence>
    <mtbwa:WriteBuildMessage DisplayName="Write message" Message="[MyProcessParameter]" Importance="High" />
  </Sequence>
</Activity>

Notice that I left in some other process parameters (Verbosity, Metadata, and SupportedReasons). That’s because these parameters are special (not required, but special). We will talk more about them in future posts.

And here are the steps to making that XAML into a build process template and creating a definition for it:

1. Check in the XAML file. You can check it in anywhere, but the normal location for a team project would be in the BuildProcessTemplates folder.
2. Create a new definition to build it. On the Process tab of the definition, click Show Details, then click New to create a new process template.
3. On the New Process Template dialog, choose “Select an existing XAML file”. Then just find and select the new XAML file you created. After that is should show up in the list of templates.
4. After selecting my new process template, the process parameters box changes to show MyProcessParameter!
5. I can set the value of MyProcessParameter to “Hello World!”
6. Lastly, I set any other required fields and save the definition.

When built the Log View shows what happened:

As you can see, adding a custom process parameter that is a simple type like String is fairly easy, but there is so much more you can do! Stay tuned for the next part!