Master Complex Builds with MSBuild : Page 2

As your projects grow more complicated, you'll need a build system to keep track of build results—and MSBuild is up to the task.

by Tapas Pal

Oct 7, 2008

Page 2 of 4

Using Wildcards to Build All Files in a Directory
You can declare multiple files within a single item as shown below:

   <CSFile Include="testclass1.cs; testclass2.cs"/>
   <VBFile Include="testform1.vb; testform2.vb"/>

You can also use wildcards to recursively include all files or only specific files from subdirectories as build inputs. The double asterisk matches all files and folders. For the following example, assume you have a project that contains graphics files in the following directories and subdirectories:

   Project\Images\BestJpgs 
   Project\Images\ImgJpgs 
   Project\Images\ImgJpgs\Img1

Assume that the project file itself is stored in the Project directory shown above. Given that structure, you could then write:

   Include="Images\\**\*.jpg" 
   Include="Images\**\img*.jpg"
   Include="Images\**\*jpgs\*.*"
   Include="Images\**\*jpgs\*"

Using MSBuild to Build Projects
You can run MSBuild from the command line by passing a project file to MSBuild.exe with the appropriate command line options for setting properties, executing specific targets, and specifying loggers. For example, the following command line builds the file TestProj.proj with the Configuration property set to Debug:

   MSBuild.exe TestProj.proj /property:Configuration=Debug

Author's Note: The default path of MSBuild.exe is C:\WINNT\Microsoft .NET\Framework\Framework Version\ (see Figure 5).


Figure 5. MSBuild Default Path: The figure shows the default path for MSBuild.exe.

From the command line, you can view help and reference information for MSBuild commands using:

   MSBuild.exe /help

The following steps show how to create an MSBuild Project file and create a build from it.

Step 1
Add a Project element at the top of your XML configuration file. The Project element is the root element of an MSBuild project file. It specifies the default set of targets for the project as well as the initial target to run every time the project is built:

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

Step 2
Add a PropertyGroup element. You use this element to group Property elements, which may contain values that are referenced several times in the project file, or that set values for properties used in several configurations:

   <PropertyGroup>
       <appname>TestAppName</appname>
   </PropertyGroup>

Step 3
Add the ItemGroup element used to group Item elements, which define inputs into the build system:

   <ItemGroup>
       <CSFile Include="testclass.cs"/>
   </ItemGroup>

For a VB project, you may want to name the item collection something more descriptive, such as VBFile, for example:

   <ItemGroup>
       <VBFile Include="testclass.vb"/>
   </ItemGroup>

Step 4
Add Target elements, which list tasks in a particular order, and expose sections of the project file as entry points into the build process. The Target element defines each target, and contains a set of tasks that MSBuild executes sequentially:

   <Target Name="Compile">...</Target>

Next add tasks, which are units of executable code used by MSBuild to perform build operations. The Task element specifies a particular task to run and the parameters to pass to the task:

   <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>

You could define some task attributes for the task outputs, so that those outputs can be referenced later in the project file. You use the Output element to specify task outputs. You can assign the output to either an item collection or a property:

   <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>

MSBuild automatically logs status information such as the current target and task as a build progresses. Beyond that, you can use the Message task to provide additional information:

   <Message Text="The output file is @(EXEFile)"/>

You should comment your build files. In MSBuild you write project file comments in the standard XML comment format; in other words, type  to end the comment, as shown below:

   <!-- Your comment -->

To build a project file, you use MSBuild.exe. Navigate to the directory that contains the project file and type the command:

   msbuild <file name>.proj

If this command doesn't work (because MSBuild.exe isn't in your path), navigate to the default MSBuild.exe directory (C:\WINNT\Microsoft .NET\Framework\Framework Version\) and run MSBuild.exe from that path. Listing 1 shows a sample MSBuild Project file.

Figure 6 shows the output when you build the file in Listing 1.


Figure 6. MsBuild Output (with Error): Sample output showing a build error.


Figure 7. Checking MSBuild Version: Here's the type of output you'll see when you check your MSbuild version from the command line.

If you're not sure which version of MSBuild you're running, type "msbuild /version" at the command prompt, and you'll see output similar to Figure 7.

Now that you know the basic steps involved in using MSBuild, you can explore some more advanced features, such as logging, task batching, and transforms, and you'll see how MSBuild integrates with Visual Studio.

« Previous Page 123 4 Next Page »