How to: Write a Task

Tasks provide the code that runs during the build process. Tasks are contained in targets. A library of typical tasks is included with MSBuild, and you can also create your own tasks. For more information about the library of tasks that are included with MSBuild, see MSBuild Task Reference.

Examples of tasks include Copy, which copies one or more files, MakeDir, which creates a directory, and Csc, which compiles Visual C# source code files. Each task is implemented as a .NET class that implements the ITask interface, which is defined in the Microsoft.Build.Framework.dll assembly.

Derive your class from the helper class, Task, which is defined in the Microsoft.Build.Utilities.dll assembly. Task implements ITask and provides default implementations of some ITask members. Additionally, logging is easier.

In both cases, you must add to your class a method named Execute, which is the method that is called when the task runs. This method takes no parameters and returns a Boolean value: true if the task succeeded or false if it failed. The following example shows a task that performs no action and returns true.

When tasks run, they can also receive inputs from the project file if you create .NET properties on the task class. MSBuild sets these properties immediately before calling the task's Execute method. To create a string property, use task code such as:

If a project is going to run a task, MSBuild must know how to locate the assembly that contains the task class. Tasks are registered using the UsingTask Element (MSBuild).

The MSBuild file Microsoft.Common.Tasks is a project file that contains a list of UsingTask elements that register all the tasks that are supplied with MSBuild. This file is automatically included when building every project. If a task that is registered in Microsoft.Common.Tasks is also registered in the current project file, the current project file takes precedence; that is, you can override a default task with your own task that has the same name.

Tip:

You can see a list of the tasks that are supplied with MSBuild by viewing the contents of Microsoft.Common.Tasks.

You can mark certain task properties as "required" so that any project file that runs the task must set values for these properties or the build fails. Apply the [Required] attribute to the .NET property in your task as follows:

Description

Code

using System;
using Microsoft.Build.Utilities;
namespace SimpleTask1
{
public class SimpleTask1: Task
{
public override bool Execute()
{
// This is where the task would presumably do its work.
return true;
}
}
}

Description

Code

using System;
using Microsoft.Build.Framework;
namespace SimpleTask2
{
public class SimpleTask2: ITask
{
//When implementing the ITask interface, it is necessary to
//implement a BuildEngine property of type
//Microsoft.Build.Framework.IBuildEngine. This is done for
//you if you derive from the Task class.
private IBuildEngine buildEngine;
public IBuildEngine BuildEngine
{
get
{
return buildEngine;
}
set
{
buildEngine = value;
}
}
// When implementing the ITask interface, it is necessary to
// implement a HostObject property of type Object.
// This is done for you if you derive from the Task class.
private Object hostObject;
public Object HostObject
{
get
{
return hostObject;
}
set
{
hostObject = value;
}
}
public bool Execute()
{
// This is where the task would presumably do its work.
return true;
}
}
}