Project File

Items represent inputs into the build system and are grouped into item collections based on their user-defined collection names. These item collections can be used as parameters for tasks, which use the individual items contained in the collection to perform the steps of the build process.

Items are declared in the project file by creating an element with the name of the item collection as a child of an ItemGroupelement. For example, the following code creates an item collection named Compile, which includes two files.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

You reference item collections throughout the project file with the syntax @(ItemCollectionName). For example, you reference the item collection in the example above with @(Compile).

Items can be declared using wildcards and may contain additional metadata for more advanced build scenarios. For more information on items, see MSBuild Items.

Properties represent key/value pairs that can be used to configure builds. Items and properties differ in the following ways:

• Items are stored in collections, while properties contain a single scalar value.
• Items cannot be removed from item collections, while properties can have their values changed after they are defined.
• Items can contain metadata and can use the %(ItemMetadata) notation, while properties cannot.

Properties are declared by creating an element with the name of the property as a child of a PropertyGroup element. For example, the following code creates a property named BuildDir with a value of Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

You reference properties throughout the project file with the syntax $(PropertyName). For example, you reference the property in the example above with $(BuildDir). For more information on properties, see MSBuild Properties.

Tasks are reusable units of executable code used by MSBuild projects to perform build operations. For example, a task might compile input files or run an external tool. Once created, tasks can be shared and reused by different developers in different projects.

The execution logic of a task is written in managed code and mapped to MSBuild with the UsingTask element. You can write your own task by authoring a managed type that implements the ITask interface. For more information on writing tasks, see How to: Write a Task.

MSBuild ships with many common tasks such as Copy, which copies files, MakeDir, which creates directories, and Csc, which compiles Visual C# source code files. For a complete list of available tasks and usage information, see MSBuild Task Reference.

You execute a task in an MSBuild project file by creating an element with the name of the task as a child of a Targetelement. Tasks usually accept parameters, which are passed as attributes of the element. MSBuild item collections and properties can be used as parameters. For example, the following code calls the MakeDir task and passes it the value of the BuildDir property declared in the previous example.

<Target Name="MakeBuildDirectory">
    <MakeDir
        Directories="$(BuildDir)" />
</Target>

For more information on tasks, see MSBuild Tasks.

Targets group tasks together in a particular order and expose sections of the project file as entry points into the build process. Targets are often grouped into logical sections to allow for expansion and increase readability. Breaking the build steps into many targets allows you to call one piece of the build process from other targets without having to copy that section of code into each target. For example, if several entry points into the build process require references to be built, you can create a target that builds references and run that target from every necessary entry point.

Targets are declared in the project file with the Target element. For example, the following code creates a target named Compile, which then calls the Csc task with the item collection declared in the previous example.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

In more advanced scenarios targets can describe relationships between each other and perform dependency analysis, which allows whole sections of the build process to be skipped if that target is up-to-date. For more information on targets, see MSBuild Targets.

Building with MSBuild

Advanced concepts

Visual Studio Integration