// HelloTask.cs
using System;
using Microsoft.Build.Utilities; // reference assembly of same name
using Microsoft.Build.Framework; // ditto

namespace MyFirstTask {
  public class HelloTask : Task {
    string _who;

    [Required]
    public string Who {
      get { return _who; }
      set { _who = value; }
    }

    public override bool Execute() {
      Log.LogMessage(string.Format("hello, {0}!", _who));
      return true;
    }
  }
}

My task implements the msbuild ITask interface by deriving from the Task helper base class, which provides the Log object, among other things. The only thing I have to do is implement the Execute method, which needs to return true on success. To prove that my task is called, I use the Log object to log a message (I could also log an error or a warning). The public Who property is set from the use of the task in an msbuild file. By marking the property with the Required attribute, I ensure that msbuild itself makes sure that a Who is provided.

Once I’ve compiled my task, I can use it directly from a .proj (or .csproj or .vbproj) file:

<!-- fun.proj -->
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="HelloTarget">
    <HelloTask Who="Joe" />
  </Target>
  <UsingTask
    TaskName="MyFirstTask.HelloTask"
    AssemblyFile="C:\MyFirstTask\bin\Release\MyFirstTask.dll" />
</Project>

Notice the HelloTask element, which creates an instance of my HelloTask class and sets the Who property. The mapping between the HelloTask and the MyFirstTask.HelloTask class in the MyFirstTask.dll assembly is in the UsingTask element. Running msbuild against fun.proj yields the following output:

C:\taskfun>msbuild fun.proj
Microsoft (R) Build Engine Version 2.0.50215.44
[Microsoft .NET Framework, Version 2.0.50215.44]
Copyright (C) Microsoft Corporation 2005. All rights reserved.

Build started 7/16/2005 7:04:09 PM.
__________________________________________________
Project "C:\taskfun\fun.proj" (default targets):

Target HelloTarget:
hello, Joe!

Build succeeded.
0 Warning(s)
0 Error(s)

Time Elapsed 00:00:00.04

Notice the “hello, Joe!” output by the task as its Execute method is called. Notice also that while the task is in its folder, the .proj file can be anywhere, so long as it has a UsingTask that maps appropriately. By convention, the UsingTask elements are kept in .targets files and put into shared folders to be used between multiple project files, e.g. Microsoft.common.targets, etc. Refactoring the UsingTask out of the .proj file and into a .targets file looks like this:

Of course, a real task does far more than this one, but it was hella easy to get started.