Customize your build process template

If you need your build process to do more than what the default template can do, you can customize the build process template to follow your own Windows Workflow Foundation (WWF) instructions. Your instructions can run .NET Framework code that is implemented in CodeActivity objects. You can run activities that are built into Team Foundation Build (TFBuild), offered by third parties, or if necessary, built by you.

Tip

If your custom build process functionality can be coded in a Windows batch file or a PowerShell script, you can upload your script and run it as part of your build process. This approach might be quicker and simpler than creating a custom build process. See Run a script in your build process.

• Start a custom build process solution and create a template

• Use a custom template in your build definition

• Get answers to common questions

Start a custom build process solution and create a template

Before you implement your instructions, extract a copy of the default template from your Team Foundation server and add it to a Visual Basic code project.

Important

Are you working in a Git team project? Do you plan to upload build process activity binaries? If so, storing binaries (especially many revisions to large files) can balloon the size of your Git repository. We recommend that you store your custom build process binaries in a repository that is separate from the code from which you build your app. You can either create a separate team project for your build processes, or you can create an additional repository in your existing team project.

1. Connect (Keyboard: Ctrl + 0, C) to the team project (and if appropriate, the Git repository) where you plan to store your build process source.

2. Create a new code project (Keyboard: Keyboard: Ctrl + Shift + N).

   Specifically, create a new solution (for example, BuildProcessSource) that contains a new Visual Basic workflow activity library code project (for example, Templates). Add the solution to a new directory under version control in an understandable location.

   TFVC example: C:\Users\YourName\Source\Workspaces\FabrikamTFVC\BuildProcessTemplates\

   Git example: C:\Users\YourName\Source\Repos\BuildProcesses\

   

   Why do I need a code project to edit my template?

3. On the builds page (Keyboard: Ctrl + 0, B), create or edit a build definition.

   

4. Download a copy of the default template. Save your new template in the same folder that contains the code project you created earlier in this procedure

   TFVC example: C:\Users\YourName\Source\Workspaces\FabrikamTFVC\BuildProcessTemplates\BuildProcessSource\Templates

   Git example: C:\Users\YourName\Source\Repos\BuildProcesses\BuildProcessSource\Templates

   

   

5. In solution explorer (Keyboard: Ctrl + Alt + L), add the template to your Templates project.

   

   

   You don’t need the Activity1.xaml file, so you can delete it if you want.

6. Set the Build Action property of your template to Content.

   

7. Add the following references to your Templates code project:

   • Microsoft.TeamFoundation.Build.Activities.dll

   • Microsoft.TeamFoundation.Build.Client.dll

   • Microsoft.TeamFoundation.Build.Workflow.dll

   • Microsoft.TeamFoundation.VersionControl.Client.dll

   How do I add these references to the code project?

   Save the code project.

8. Implement a “Hello World!” message so that after you check in and run the template you can be confident you’ve got it working. To do this, drag a WriteBuildMessage activity into your workflow and set its BuildMessageImportance property to Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.High.

   

9. Save the template and upload your new solution. Either check in pending changes if you are in TFVC (Keyboard: Ctrl + 0, P), or commit (Keyboard Ctrl + 0, G) and push them if you are in Git.

   

Use a custom template in your build definition

After you have uploaded a custom build process template to your team project as explained above, you can use the template from your build definitions.

1. On the builds page (Keyboard: Ctrl + 0, B), create or edit a build definition.

2. On the build definition Process tab, choose Show details, and then choose New.

   

3. After you choose New:

   • TFVC: Type or browse to the path to the template on your Team Foundation Server.

   • Git: Type or browse to the path to the template on your dev machine.

4. After you specify the path to the template, you can select it from the list.

   

5. If you are creating a new build definition, select the solution you are building and specify the staging location and any other options you need. See Create or edit a build definition. When you are finished, save the build definition.

6. On the builds page (Keyboard Ctrl + 0, B), queue the build.

   

7. After the build has completed, view the results to verify that your customized workflow ran as you expected.

   

Q & A

Q: I was blocked by the system because I don’t have permission. How do I get it?

A: Permission reference for Team Foundation Server

Q: Why do I need a code project to edit my template?

A: You should edit templates from within a code project because

• Problems can occur when you try to edit a template outside the context of a code project.

• Problems can occur unless you develop your build process activity in the same solution as your build process templates. By working this way, when you need to use one of your activities in your process template, the activity is available in the workflow designer toolbox. However, you must keep the source code for your activities in a separate code project from the one that contains your build process templates. See Use and develop custom build process activities.

Q: How do I add the references I need to work with TFBuild workflow?

A: Use the reference manager to add references to

View the code project references and open reference manager.

Browse to C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\ReferenceAssemblies\v2.0 and then select and add:

• Microsoft.TeamFoundation.Build.Activities.dll

• Microsoft.TeamFoundation.Build.Client.dll

• Microsoft.TeamFoundation.Build.Workflow.dll

• Microsoft.TeamFoundation.VersionControl.Client.dll

Q: Can I share a template across team projects?

A: Yes. You can register a template with more than one team project. This capability means that you can share a build process across any team project in the team project collection that contains your template.

Q: If I modify my template, what happens to the build definitions that use it?

A: If you need to modify a template, you should plan to review all build definitions that are based on the template and correct them after you have completed your changes to the template. If you do not do this, your build definitions might fail or function in an unexpected way.

Q: What happens if I delete my build process template?

A: If you decide to delete a build process template, first make sure that you locate and delete all build definitions that are based on the template. When you delete the template, any remaining build definitions based on the template will no longer function.

Q: What is causing errors in my custom build process?

A: A few common causes of some errors:

• TF215097: Can appear if your custom activity is missing a required attribute or if you try to edit your template in the same code project that contains your custom activities.

• MSBuild error XC1014: Can appear if you don’t set the Build Action of your template to Content.

If you get one of the above errors, make sure you have not missed one of the steps in the above procedures.

You might also find this topic helpful: Diagnose problems in your build.

Q: What is Windows Workflow Foundation? How do I use it?

A:Windows Workflow Foundation.

Q: How do I get environment variable data?

A:Use environment data from a custom build process

Q: Where can I learn about the built-in activities?

A:Team Foundation Build activities

What do I do if the built-in activities don’t meet my needs?

A:Develop your own custom build process activity.

Q: Where can I get templates, workflow activities, and scripts?

A:Community TFS Build Extensions

Q: Where can I learn more about how to develop custom build processes?

A:Curated answer: Customize your Team Foundation Build process