Walkthrough: Adding Build Steps Using the BuildStep Task

A BuildStep task is an MSBuild task written specifically for Team Foundation Server. You add a BuildStep task to a build by adding one or more BuildStep elements to a Target element in the TFSBuild.proj file of the solution's build definition.

Prerequisites

Before you can add a BuildStep task to a build definition, you must have the following:

• Access to the TFSBuild.proj file for the build definition that you want to customize. For more information about how to create build definitions, see How to: Create a Build Definition.

  Important Note:
  When you customize the TFSBuild.proj file, you customize every build definition associated with it.

• A local workspace that contains your team project files and the build files. For more information, see How to: Create a Mapped Workspace and How to: Get the Source for Your Team Project.

Required Permissions

To perform the procedures in this topic, you must have the Check in and Check out permissions set to Allow. For more information, see Team Foundation Server Permissions.

To add build steps using the BuildStep task, perform the following procedures:

• Adding a Task to the Project File

• Adding an Informational Build Step to the Project File

Adding a Task to the Project File

You can use the BuildStep task to add and update build steps. This procedure describes how to modify the TFSBuild.proj file as follows:

1. Add a build step.

2. Perform a task.

3. Update the build step with the status Succeeded if the task is successful or with the status Failed if the task is not successful.

The build step task in the example copies source files to a new location.

To add and update a build step to the TFSBuild.proj file

1. Start Visual Studio.

2. Check out the TFSBuild.proj file that you want to modify from Team Foundation version control and open it in the Visual Studio XML editor.

3. Add the following XML to the <ItemGroup> element. You can add the XML to the existing <ItemGroup> element or you can decide to add a new <ItemGroup> element:

   Note

   The code in this step identifies the folders where the source files to be copied are located. Other MSBuild tasks may require other additions to the XML. For more information about requirements for MSBuild tasks, see MSBuild Task Reference.

   <ItemGroup>
       <SourceFileFolder Include="C:\WorkingFolder\TeamBuildTypes\**\*.cs" />
   </ItemGroup>
   

4. Add the following XML to the end of the TFSBuild.proj file just before the </Project> element:

   </ItemGroup>
       <Target Name="BeforeCompile">
           <BuildStep
               TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
               BuildUri="$(BuildUri)"
               Message="Working...">
               <Output TaskParameter="Id" PropertyName="StepId" />
           </BuildStep>
   
           <!-- Perform a task... -->
           <Copy SourceFiles="@(SourceFileFolder)"
               DestinationFolder="C:\NewSourceFileFolder"
           />
   
           <BuildStep
               TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
               BuildUri="$(BuildUri)"
               Id="$(StepId)"
               Status="Succeeded" />
           <OnError ExecuteTargets="MarkBuildStepAsFailed" />
       </Target>
   
       <Target Name="MarkBuildStepAsFailed">
           <BuildStep
               TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
               BuildUri="$(BuildUri)"
               Id="$(StepId)"
               Status="Failed" />
       </Target>
   </Project>
   

   Note

   For more information about Team Foundation Build targets and a list of customizable targets, see Customizable Team Foundation Build Targets.

5. Save your changes and then close TFSBuild.proj.

6. Check in the TFSBuild.proj file to version control.

7. Run the build definition.

   For more information, see How to: Queue or Start a Build Definition.

   You can view the build step message in the Build Explorer, and you can see the complete build step creation and update processes in the build log. You also see the copied files in the directory that you specified. For more information, see How to: Monitor Build Progress.

Adding an Informational Build Step to the Project File

If you do not have to perform a task but you want to add an informational build step, do not use the Id Output property and set the status immediately. This procedure adds only a message to the build process that you see when you open the build in the Build Explorer.

To add an informational build step to the TFSBuild.proj file

1. Start Visual Studio.

2. Check out the TFSBuild.proj file that you want to modify from Team Foundation version control and open it in the Visual Studio XML editor.

3. Add the following XML to the end of the TFSBuild.proj file just before the </Project> tag:

   </ItemGroup>
       <Target Name="AfterCompile">
           <BuildStep
               TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
               BuildUri="$(BuildUri)"
               Message="Compile step complete."
               Status="Succeeded" />
       </Target>
   </Project>
   

   Note

   For more information about Team Foundation Build targets and a list of customizable targets, see Customizable Team Foundation Build Targets.

4. Save your changes, and then close TFSBuild.proj.

5. Check in the TFSBuild.proj file to version control.

6. Run the build definition.

   For more information, see How to: Queue or Start a Build Definition.

   You can view the message in the Build Explorer and in the build log. For more information, see How to: Monitor Build Progress.

See Also

Reference

BuildStep Task

Other Resources

MSBuild Task Reference

MSBuild Project File Schema Reference