Working with the BuildStep Task

One of the new convenience tasks added to Team Foundation Build 2008 is the BuildStep task.  This task allows you to add custom messages to the build reports created when you run a team build.  For example, you may want to display the message "Publishing web site" while your build script is updating some files on a web site.  Having the ability to "see" what your build script is currently executing is not only useful but can also be a great debugging tool (the messages are also logged as well as being displayed).

The BuildStep task accepts the following parameters:

• TeamFoundationServerUrl - specifies the Team Foundation Server URL.  For example: $(TeamFoundationServerUrl).
• BuildUri - specifies the build URI - for example: $(BuildUri).
• Name - specifies the name of the build step added by this task.  NOTE: this parameter appears to be optional - i.e. it works just fine with or without a Name being specified.
• Message - specifies the text of the message to be displayed within the build report.
• Id - specifies the optional input/output parameter. If specified, this is the ID of the build step that is updated. If not specified, a new build step is created.
• Status - specifies the status for the build step.  For example, Succeeded, Failed, or Stopped.

There are several variations in how you can implement the BuildStep task.  I've listed two of the more common scenarios below:

Simplest Scenario - Add a Message
The simplest scenario involves just adding a build step message to the build report with a status of "Succeeded".  To do this, use the following pattern (note: the target "PackageBinaries" is used for illustration purposes only - the task can be utilized from within any target you wish):

<Target Name="PackageBinaries">
  <BuildStep TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
             BuildUri="$(BuildUri)"
             Message="Publishing web site"
             Status="Succeeded" />
</Target>

This will display the text "Publishing web site" in the build report:

You can leave off the Status parameter, however, the icon displayed next to the build step will not indicate a completed task.  If you leave the Status parameter in, then the status icon will indicate a completed task as soon as the build step is displayed, even if the task has not yet completed.  To present a more accurate indication of what's currently executing, use the next template.

Complete Scenario - Display Actual Status
Ideally, you would want to display the icon that indicates a build step is executing until the step has completed and then change the icon (and optionally the message) to a "completed" status.  To do this, use the following pattern:

<Target Name="PackageBinaries">
  <BuildStep TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
             BuildUri="$(BuildUri)"
             Message="Publishing web site...">
    <Output TaskParameter="Id" PropertyName="MyBuildStepId" />
  </BuildStep>

  <!-- Long running task goes here... -->
  <BuildStep TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
             BuildUri="$(BuildUri)"
             Id="$(MyBuildStepId)"
             Message="Web site published"
             Status="Succeeded" />
</Target>

In this example, we're tracking the ID of the newly created build step (in the property MyBuildStepId) so we can use it in a subsequent BuildStep task to set the status icon to "Succeeded" and update the build report text.

NOTE: You can leave the Message parameter off in the second BuildStep task in the above example if you want to leave the original message text unchanged.

Although this is a new addition to the TFS 2008 release, you can get similar functionality for TFS 2005 by using a custom build task.  One example of such a custom build task is available here.