.CSPROJ File Format – Targets and tasks

How targets are ordered

The targets to build are those named on the command line (-t:A;B), or the project’s DefaultTargets, or the first target. Targets in InitialTargets (of the project and of every import) always run first. For each target MSBuild then:

1. checks its Condition; when it is false, the target is skipped and so are its DependsOnTargets;
2. runs the targets in DependsOnTargets, left to right, each at most once in the whole build;
3. runs the targets whose BeforeTargets names it;
4. runs its own tasks, in order;
5. runs the targets whose AfterTargets names it.

<Project DefaultTargets="A" InitialTargets="Init">
  <Target Name="Init"><Message Text="Init" /></Target>
  <Target Name="A" DependsOnTargets="B;C"><Message Text="A" /></Target>
  <Target Name="B"><Message Text="B" /></Target>
  <Target Name="C"><Message Text="C" /></Target>
  <Target Name="D" BeforeTargets="A"><Message Text="D (before A)" /></Target>
  <Target Name="E" AfterTargets="A"><Message Text="E (after A)" /></Target>
</Project>

A target runs once. A task that fails stops its target and the build, unless ContinueOnError turns the failure into a warning (true or WarnAndContinue) or an error that lets the build go on (ErrorAndContinue); ErrorAndStop or false is the default. After a failure the OnError elements of the target run their ExecuteTargets; OnError must come after every task.

Incremental builds

A target with Inputs and Outputs is skipped when every output is newer than every input. MSBuild then logs that the target was skipped because its outputs are up to date. When only some outputs are out of date, MSBuild can run the target for just those (partial builds) if the two lists are transformations of one another, which is why Inputs="@(Compile)" pairs with Outputs="@(Compile->'$(IntermediateOutputPath)%(Filename).obj')". A target without them always runs.

Returns says which items the target hands to a caller (an MSBuild task running this project); when it is missing, the Outputs are returned.

Inside a target

Well-known targets

The common targets, imported by every .NET project, define these. A project hooks one with BeforeTargets or AfterTargets, or replaces a …DependsOn property.

The …DependsOn properties (BuildDependsOn, CoreBuildDependsOn, CompileDependsOn, CleanDependsOn, RebuildDependsOn, PublishDependsOn, PrepareForBuildDependsOn, ResolveReferencesDependsOn) hold the lists of targets a target depends on; a project adds to one (<BuildDependsOn>MyStep;$(BuildDependsOn)</BuildDependsOn>).

Built-in tasks

These ship with MSBuild and are declared in Microsoft.Common.tasks and the files it names. The parameters of each are in Microsoft’s task reference.

The native (C++) build and the Windows application packaging targets add many more (CL, LIB, MIDL, RC, Mt, BSCMake, SetEnv, GenerateAppxPackageRecipe, MakeAppxPack and others). A task that is not in these lists is declared by a UsingTask in an SDK or a package.

UsingTask and inline tasks

UsingTask says where a task is implemented. Give TaskName and exactly one of AssemblyName (an assembly by name) or AssemblyFile (a path), or, for a task defined in the file, a TaskFactory. Architecture and Runtime choose the task host; Override makes the declaration replace another with the same name.

<UsingTask TaskName="Stamp" TaskFactory="RoslynCodeTaskFactory"
           AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll">
  <ParameterGroup>
    <Path ParameterType="System.String" Required="true" />
    <Text ParameterType="System.String" Output="true" />
  </ParameterGroup>
  <Task>
    <Code Type="Fragment" Language="cs">
      Text = System.IO.File.ReadAllText(Path).Trim();
    </Code>
  </Task>
</UsingTask>
<Target Name="ShowStamp">
  <Stamp Path="stamp.txt"><Output TaskParameter="Text" PropertyName="StampText" /></Stamp>
  <Message Text="$(StampText)" />
</Target>

The task factories are RoslynCodeTaskFactory (C# or Visual Basic compiled with Roslyn, the current one), CodeTaskFactory (the older .NET Framework one), XamlTaskFactory (a task described by XAML) and the default assembly factory, used when TaskFactory is left out.

In the explorer

A project’s Targets tab lists every target with when it runs (dependencies and hooks), the tasks it calls and its condition; below it, every task call with its parameters and outputs, and every UsingTask.

Not described

Known, not yet covered

• Reference: the parameters of each task (Microsoft’s task reference lists them), and the targets and tasks that individual SDKs add.

Sources

Microsoft Learn, MSBuild targets, tasks, task reference and inline tasks; the names of the tasks and targets from Microsoft.Build.CommonTypes.xsd and from the .NET SDK’s own Microsoft.Common.CurrentVersion.targets. The ordering and failure behaviour were checked by running dotnet msbuild.