How to: Write a Simple MSBuild Project

Switch View

How to: Write a Simple MSBuild Proj...

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Visual Studio

How to: Write a Simple MSBuild Project

This topic explains how to write a simple MSBuild project file that uses a task to compile a project containing one file. This example covers two project files, one that compiles a Visual Basic source file, and one that compiles a Visual C# source file. The complete source code for each project file is available at the end of the topic.

Adding the Project Element

The Project element is the root element of an MSBuild project file and. It can specify the default set of targets for the project as well as the initial target to run first every time the project is built. For more information, see Project Element (MSBuild).

To add a Project element

Add XML similar to the following:

<Project DefaultTargets="Compile"
    xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    ...
</Project>

This Project element specifies that the Compile target is the default target.

Adding Properties

The PropertyGroup element is used to group Property elements that contain values that are referenced several times in the project file or to set the values for properties that are used in several configurations. For more information on properties, see MSBuild Properties and Property Element (MSBuild).

To add properties

Add a PropertyGroup element. Property elements must be children of a PropertyGroup element.
Add one or more properties as children of the PropertyGroup element.
Property elements do not use the word "Property" as their element name. Rather, the element name is based on the name of the property, and the value of the property is the text value of the element. For example, the following XML sets the value of the appname property to HelloWorldCS.
```
<PropertyGroup>
    <appname>HelloWorldCS</appname>
</PropertyGroup>
```

Adding Items

The ItemGroup element is used to group Item elements, which define inputs into the build system. For more information on items, see MSBuild Items and Item Element (MSBuild).

To add items

Add an ItemGroup element. Item elements must be children of an ItemGroup element.
Add one or more items as children of the ItemGroup element. Use the Include attribute to specify a file to include as an input to the build system.
Item elements do not use the word "Item" as their element name. Rather, the element name is based on the item collection that contains the individual item. For example, if a project contains several source files and several resource files, you may want to put all source files into an item collection named SourceFile and all resource files into a collection named ResourceFile. This makes it easier to pass groups of items into tasks.
For example, the following XML includes the file consolehwcs1.cs in the CSFile item collection.
```
<ItemGroup>
    <CSFile Include="consolehwcs1.cs"/>
</ItemGroup>
```
For a VB project, you may want to name the item collection something more descriptive, such as VBFile.
```
<ItemGroup>
    <VBFile Include="consolehwvb1.vb"/>
</ItemGroup>
```

Adding Targets

Targets group tasks together in a particular order and expose sections of the project file as entry points into the build process. The Target element is used to define targets, and contains a set of tasks that MSBuild executes sequentially. For more information on targets, see MSBuild Targets and Target Element (MSBuild).

To add a target

Add a Target element, with a name specified by the Name attribute. For example, the following target is named Compile.
```
<Target Name="Compile">...</Target>
```

Adding Tasks

Tasks are units of executable code used by MSBuild to perform build operations. The Task element specifies the task to run and the parameters to pass to the task. A library of common tasks is provided with MSBuild, and you can also write tasks yourself. For more information on tasks, see MSBuild Tasks and Task Element (MSBuild). For more information on the common tasks provided with MSBuild, see MSBuild Task Reference.

To compile a Visual C# project, use the Csc Task, and to compile a Visual Basic project, use the Vbc Task. Both of these tasks are part of the library of common tasks provided with MSBuild.

To add a task

Add a task as a child of a Target element.
Task elements do not use the word "Task" as their element name. Rather, the element name is the name of the task itself.
Add the necessary attributes for the task.
Some tasks accept parameters, which are passed to the task through attributes on the Task element.
The following example compiles a Visual C# project, passing the CSFile item collection to the Sources parameter of the task.
Note:
Use the @() notation to specify an entire item collection as a parameter.
```
<CSC Sources="@(CSFile)">...</CSC>
```
The following example compiles a Visual Basic project, passing the VBFile item collection to the Sources parameter of the task.
```
<VBC Sources="@(VBFile)">...</VBC>
```

Note:
Use the @() notation to specify an entire item collection as a parameter.

Adding Task Outputs

Some task attributes can be defined for the task outputs so that those outputs can be referenced later in the project file. The Output element is used to specify task outputs, and can assign the output to either an item collection or a property. For more information on task outputs, see MSBuild Tasks and Output Element (MSBuild).

To add task outputs

Add an Output element as a child of a Task element.
Set the TaskParameter attribute of the Output element equal to the attribute that you want to use as output, and the ItemName or PropertyName attribute that you want to store the value in.
The following example compiles a Visual C# project, passing the CSFile item collection to the Sources parameter of the task, and stores the value of the OutputAssembly parameter in the EXEFile item collection.
Note:
Use the $() notation to specify a property as a parameter.
```
<CSC
    Sources="@(CSFile)"
    WarningLevel="$(WarningLevel)">
    <Output
        TaskParameter="OutputAssembly"
        ItemName="EXEFile"/>
</CSC>
```
The following example compiles a Visual Basic project, passing the VBFile item collection to the Sources parameter of the task, and stores the value of the OutputAssembly parameter in the EXEFile item collection.
```
<VBC
    Sources="@(VBFile)"
    WarningLevel="$(WarningLevel)">
    <Output
        TaskParameter="OutputAssembly"
        ItemName="EXEFile"/>
</VBC>
```

Note:
Use the $() notation to specify a property as a parameter.

Adding Messages

Some status information, such as the current target and task, is automatically logged by MSBuild as a build progresses. In addition, you can use the Message task to provide additional information.

To add a message

Add a Message task as a child of a Target element.
Add the message text to the Text parameter of the Message task.
The following example creates a message that writes the name of the item collection created with the Output element in the previous example.
```
<Message Text="The output file is @(EXEFile)"/>
```

Adding Comments to a Project File

MSBuild project file comments are written in the standard format for comments in an XML file.

To add comments

Type <!-- to begin a comment.
Write the text of the comment.
Type --> to end a comment.
The following example adds a comment in an XML file.
```

```

Building a Project

MSBuild project files are built using MSBuild.exe. For more information on MSBuild.exe, see MSBuild Command Line Reference.

To build a project

Navigate to the directory that contains the project file and type the following:
```
msbuild <file name>.proj
```

Example

The following example shows a project file that compiles a Visual C# application and logs a message containing the output file name.

<Project DefaultTargets = "Compile"
    xmlns="http://schemas.microsoft.com/developer/msbuild/2003" >

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldCS</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <CSFile Include = "consolehwcs1.cs"/>
    </ItemGroup>

    <Target Name = "Compile">
        <!-- Run the Visual C# compilation using input files of type CSFile -->
        <CSC
            Sources = "@(CSFile)"
            OutputAssembly = "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the CSC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </CSC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

The following example shows a project file that compiles a Visual Basic application and logs a message containing the output file name.

<Project DefaultTargets = "Compile"
    xmlns="http://schemas.microsoft.com/developer/msbuild/2003" >

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldVB</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <VBFile Include = "consolehwvb1.vb"/>
    </ItemGroup>

    <Target Name = "Compile">    
        <!-- Run the Visual Basic compilation using input files of type VBFile -->
        <VBC
            Sources = "@(VBFile)"
            OutputAssembly= "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the VBC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </VBC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Concepts

MSBuild Overview

MSBuild Project File Schema Reference

MSBuild

Other Resources

MSBuild Concepts

MSBuild Reference