Partager via

Customize your build process template

  • Article

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 iconGit 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 icon 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 icon TFVC example: C:\Users\YourName\Source\Workspaces\FabrikamTFVC\BuildProcessTemplates\

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

    Create a code project to contain the new template

    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.

    New Build Definition or Edit 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 icon TFVC example: C:\Users\YourName\Source\Workspaces\FabrikamTFVC\BuildProcessTemplates\BuildProcessSource\Templates

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

    Download link on build definition Process tab

    Save As dialog box

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

    Add the build process template file to the project

    Add Existing Item dialog box

    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.

    Set the Build Action to Content

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

    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.

    Added WriteBuildMessage activity to template

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

    Uploading the changes using TFVC or 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 detailsShow details, and then choose New.

    Build definition, Process tab, New button

  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.

    CustomTemplate selected in build definition

  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.

    Queuing a build from the builds page

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

    "Hello World!" message appears in build log

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.

Custom template code project references

Reference Manager dialog box

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

Select the files to reference dialog box

Reference Manager dialog box

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