Use and develop custom build process activities

"Hello World" from a C Sharp activity

After you have created a custom build process template, you can implement your own business logic using Windows Workflow instructions and the built-in Team Foundation Build (TFBuild) activities. If these tools are not sufficient, you can use activities from third parties, or if necessary, implement your own .NET Framework code in a CodeActivity.

> [!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.

  • Create a custom build process activity

  • Edit your build process template

  • Upload your custom build process

    • TFVC iconUpload and enable your custom build process in a TFVC team project

    • Git iconUpload and enable your custom build process in a Git team project

  • Enable your custom build process

  • Run the build

  • Q & A

"Hello World" in the build summary

Create a custom build process activity

Important

Before you begin, get a copy of the template and put it in a code project. If you have not already done so, here’s how to do it.

You should 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.

  1. Add a new C# or Visual Basic code project to the solution that contains your build process template code project.

    New Project for BuildProcessSource solution

    New Project

  2. Add the following references to your new code project:

    How do I add these references to the code project?

    Save the code project.

  3. Add a new activity to the project.

    New Item for Source code project

    Add New Item

  4. Implement your CodeActivity For example, Hello.cs:

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Activities;
    using Microsoft.TeamFoundation.Build.Workflow.Activities;
    using Microsoft.TeamFoundation.Build.Client;
    using Microsoft.TeamFoundation.Build.Workflow.Tracking;
    
    namespace BuildProcessSource
    {
        // enable the build process template to load the activity
        [BuildActivity(HostEnvironmentOption.All)]
        // keep the internal activity operations from appearing in the log
        [ActivityTracking(ActivityTrackingOption.ActivityOnly)]
        public sealed class Hello : CodeActivity
        {
            // Define an activity input argument of type string
            public InArgument<string> SayHelloTo { get; set; }
    
            // If your activity returns a value, derive from CodeActivity<TResult>
            // and return the value from the Execute method.
            protected override void Execute(CodeActivityContext context)
            {
                // Obtain the runtime value of the Text input argument
                string text = context.GetValue(this.SayHelloTo);
    
                // Add our default value if we did not get one
                if (text == null || text == "")
                {
                    text = "World";
                }
    
                // Write the message to the log
                context.TrackBuildWarning("Hello " + text, BuildMessageImportance.High);
            }
        }
    }
    

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

  5. Build your solution in Visual Studio (Keyboard: Ctrl + Shift + B).

When you’re done, your solution should look something like this:

Example of a custom build process solution

Edit your build process template

From your solution, edit your build process template by dragging activities into it. Once the activity is added to the template, set its properties (Keyboard: F4).

Editing a build process template from a solution

When you are done, save the template.

Upload your custom build process

Before you can define a build that uses your custom build process template and activity, you must upload and enable them.

  • TFVC iconUpload and enable your custom build process in a TFVC team project

  • Git iconUpload and enable your custom build process in a Git team project

Upload your custom build process in a TFVC team project

In a TFVC icon TFVC team project:

  1. Make sure you have built your solution (Keyboard Ctrl + Shift + B).

  2. Connect (Keyboard: Ctrl + 0, C) to the team project where you plan to store your build process source.

  3. From Source Control Explorer, add items to the folder that contains your activity code project.

    Source Control Explorer

  4. Browse to the folder that contains the .dll file and select it. For example, C:\Users\YourName\Source\Workspaces\FabrikamTFVC\BuildProcessTemplates\BuildProcessSource\Source\bin\Debug.

    Add build process binary to TFVC version control

  5. Finish the process to add the file.

    Add build process binary to TFVC version control

  6. Check in your changes.

    Pending Changes

Upload your custom build process in a Git team project

In a Git icon Git team project:

  1. Important:

    • 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 this purpose, or you can create an additional repository in your existing team project.

    • You must store your binaries in a subfolder in your Git repository. If you try to use binaries in the root folder, you might be blocked by a git branch not found error message.

  2. Make sure you have built your solution (Keyboard Ctrl + Shift + B).

  3. Connect (Keyboard: Ctrl + 0, C) to the team project where you plan to store your build process source.

  4. Open the Git command prompt.

    Open Command Prompt from Changes page

    Q: I can’t open the command prompt. What do I do?A:Enable the Git command prompt.

  5. Use the Git command prompt to add the .dll file. For example:

    cd c:\users\YourName\source\repos\BuildProcesses\BuildProcessSource\Source\bin\Debug
    
    git add Source.dll -f
    
  6. Commit your changes.

    Commit button on the Changes page

  7. Sync or push your commit.

    Sync link on Changes page

    Sync button and Push link on Unsynced Commits page

Enable your custom build process

Before you can run your custom build process, you must point the build controller to the binaries you uploaded to TFS and select the build process template in your build definition.

  1. On the Builds page (Keyboard: Ctrl + 0, B), choose Actions, and then choose Manage Build Controllers.

  2. On the Manage Build Controllers dialog box, highlight the controller you will use to run this build process and then choose Properties.

    Mange Build Controllers dialog box

  3. Specify the version control path to custom assemblies.

    Build Controller Properties dialog box

    VisualStudioEllipsesButton screenshot Browse to a folder that is an ancestor of the folder where you uploaded your build process in the steps above.

    • TFVC icon TFVC example: $/FabrikamTFVC/BuildProcessTemplates/BuildProcessSource/Source/bin/Debug

    • Git icon Git example: BuildProcessSource/Source/Bin/Debug

      Browse dialog box showing Git values

      The system automatically converts the value you enter to a vstfs path. For example: vstfs:///Git/VersionedItem/FabrikamGit/BuildProcesses/master/BuildProcessSource/Source/Bin/Debug.

      Version control path to custom assemblies

  4. If you have not done so already, create or modify a build definition and select your custom build process template.

    Build definition with custom process template

Run the build

Queue the build. The result should look something like this:

"Hello World" in build summary

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: 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.

Reerences context menu

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: What is causing errors in my custom build process?

A:Some common causes of errors.

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

A:Windows Workflow Foundation.

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

A:Team Foundation Build activities

Q: Where can I get build process 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