MSBuild
MSBuild does not require Visual Studio. This is ideal for lab environments in which Visual Studio is not installed. Individual builds are organized in project files. Build project files are XML files and have a .proj extension. As an XML file, the build project is platform-independent and extensible. For a complete explanation of MSBuild, consult the MSBuild Reference at the Microsoft Developer Network (MSDN) at http://winfx.msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_fxgenref/html/.asp.
Build projects consist of items, properties, and tasks, as described in the following sections.
Items
Items are the input of the build process. Items are created as child elements of the ItemGroup element. Items sharing the same name are considered a collection. Item collections are addressable in the build project as @(ItemCollectionName). Item collections are primarily used as parameters in build tasks.
For example, the Compile element is a standard item. It defines the source files that are included or excluded from the build. The Include attribute specifies a file to be included in the build. The Exclude attribute, naturally, excludes files. The following code defines a Compile collection, which includes two items:
<ItemGroup> <Compile Include="source1.cs"/> <Compile Include="source3.cs" Exclude="source2.cs"/> </ItemGroup>
Properties
Properties are configuration data used during the build process. Properties represent individual values and cannot be grouped into collections. Properties are defined as child elements of the PropertyGroup element. Refer to properties in the project using the $(property) syntax:
<PropertyGroup> <ApplicationVersion>1.2.3.4</ApplicationVersion> </PropertyGroup>
There are several reserved properties in the MSBuild environment. Table 4-6 lists the reserved properties.
| Property | Description |
|---|---|
| MSBuildProjectDirectory | This property is the absolute path to the MSBuild project file. |
| MSBuildProjectFile | This property is the name and extension of the MSBuild project file. |
| MSBuildProjectExtension | This is the file extension of the MSBuild project file. It should include the . prefix. |
| MSBuildProjectFullPath | This property is the fully qualified name of the MSBuild project file. |
| MSBuildProjectName | This property is the name of the MSBuild project file without the extension. |
| MSBuildBinPath | This property is the path to the MSBuild binaries. |
| MSBuildProjectDefaultTargets | This property is the list of targets specified in the project element of the MSBuild project file. |
| MSBuildExtensionsPath | This property is the supplemental directory for custom target files, which is found under the Program Files directory. |
Tasks
Tasks are the build operations of the MSBuild project and child elements of the Target element. Tasks can accept parameters, which are the attributes of the Task element. Item collections and properties are valid parameters to tasks. Create multiple targets to batch groups of build operations. The MSBuild tool can invoke different targets. For example, you can create targets for release versus debug builds.
Tasks are written in a managed language and are available to any MSBuild project. Developers can author specialty tasks in managed code. Build tasks are classes that implement the ITask interface.
Table 4-7 list the defaults tasks available in the MSBuild environment.
| Task | Description |
|---|---|
| AL | This task invokes the Assembly Linker (AL) tool. |
| AspNetCompiler | This task invokes aspnet_compiler.exe, which precompiles ASP.NET applications. |
| AssignCulture | This task creates an item for a culture. |
| Copy | This task copies files to a specified directory. |
| CreateItem | This task copies items between collections. |
| CreateProperty | This task copies properties. |
| Csc | This task invokes csc.exe, which is the C# compiler. |
| Delete | This task deletes files. |
| Exec | This task executes an application or command. |
| FindUnderPath | This task determines which items are found within a specified directory and its subdirectories. |
| GenerateApplicationManifest | This task creates an application manifest or native manifest for a ClickOnce application. |
| GenerateBootstrapper | This task locates, downloads, and installs an application. |
| GenerateDeploymentManifest | This task creates a deployment manifest for a ClickOnce application. |
| GenerateResource | This task creates .resources files from .txt and .resx files. |
| GetAssemblyIdentity | This task returns assembly metadata and stores the results in an item collection. |
| GetFrameworkPath | This task obtains the path of the .NET Framework assemblies. |
| GetFrameworkSDKPath | This task obtains the path of the .NET Framework SDK. |
| LC | This task converts a .licx to a .license file. |
| Makedir | This task makes a directory. |
| MSBuild | This task builds an MSBuild project from another build project. |
| ReadLinesFromFile | This task reads MSBuild items from a file. |
| RegisterAssembly | This task reads the metadata of an assembly and registers the assembly as a COM server, which allows COM clients to access the assembly. |
| RemoveDir | This task deletes a directory. |
| ResolveAssemblyReference | This task determines which assemblies depend on another assembly. |
| ResolveComReference | This task resolves the location of type library (TLB) files. |
| ResolveKeySource | This task determines the strong name of a key source. |
| Sgen | This task is a wrapper for the XML Serialization Generator Tool (sgen.exe). |
| SignFile | This task signs a file with a certificate. |
| Touch | This task sets the access and modification time of a file. |
| UnregisterAssembly | This task unregisters an assembly from the registry. Afterward, the assembly is no longer available to COM clients. |
| Vbc | This task invokes vbc.exe, which is the Visual Basic .NET compiler. |
| VcBuild | This task wraps vcbuild.exe, which builds a Visual C++ project. |
| WriteLinesToFiles | This task writes the paths of the specified items to a file. |
Project File
A project file is a generalized skeleton of an MSBuild project. An MSBuild project can have any number of tasks, item collections, and properties. This is entirely dependent on the requirements of the actual project.
<?xml version="1.0" encoding="utf-8"?> <!-- MSBuild Schema --> <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <ItemGroup> <!-- Item Collection --> </ItemGroup> <Target Name="Task1"> <!-- Task(s) --> </Target> <PropertyGroup> <!-- Properties --> </PropertyGroup> <ItemGroup> <!-- Item Collection --> </ItemGroup> <Target Name="Task2"> <!-- Task(s) --> </Target> </Project>
This is the syntax of the MSBuild command line:
Msbuild switches projectfile
MSBuild command-line switches are listed in Table 4-8.
| Task | Description |
|---|---|
| /help | This switch displays help information on the MSBuild command. /? and /h are also help switches. |
| /noconsolelogger | This switch disabled the default console logger. Events should not be logged to the console window. |
| /nologo | This switch suppresses the startup banner and copyright information. |
| /version | This switch displays the version of the MSBuild tool. |
| @file | This switch reads command-line instructions from a batch file. |
| /noautoresponse | This switch disables the automatic include of the MSBuild.rsp file. |
| /target:targetnames | This switch identifies the targets to execute. The targets are delimited by commas or semicolons. |
| /property:name=value | This switch sets the value of a property. Multiple properties are delimited by commas or semicolons. |
| /logger:logger | This switch logs MSBuild events to a logger. |
| /consoleloggerparameters: parameters | This switch sets the parameters of the console logger. |
| /verbosity:level | This switch sets the amount of information written to the event log. The levels are as follows:
|
| /validate:schema | This switch validates the project file. If no schema is provided, the default schema is used to perform the validation. |
MSBuild Walkthrough
This section provides a walkthrough of a normal MSBuild project. The project contains two tasks: The first task compiles an assembly from the available source files, and the second task creates a DLL from a source file. The project then compiles the remaining sources files. This requires a reference to the DLL. The walkthrough MSBuild project is documented with steps. Here is the project, followed by a description of each step:
<?xml version="1.0" encoding="utf-8"?> <!-- Step One--> <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <!-- Step Two --> <ItemGroup> <Compile Include="source1.cs"/> <Compile Include="source2.cs"/> </ItemGroup> <!-- Step Three --> <PropertyGroup> <DebugType>none</DebugType> </PropertyGroup> <PropertyGroup> <AssemblyName>sample.exe</AssemblyName> </PropertyGroup> <!-- Step Four --> <Target Name="Application1"> <Csc Sources="*.cs" OutputAssembly="$(AssemblyName)" DebugType="$(DebugType)"/> </Target> <!-- Step Five--> <Target Name="Application2"> <Csc Sources="source3.cs" TargetType="library"/> <Csc Sources="@(compile)" References="source3.dll" OutputAssembly="$(AssemblyName)" DebugType="$(DebugType)"/> </Target> </Project>
-
Step 1 establishes the schema for the MSBuild schema.
-
Step 2 creates an item collection for the Compile element. The source files source1.cs and source2.cs are named in the collection.
-
Step 3 sets the defaults for the DebugType and AssemblyName properties.
-
Step 4 creates target Application1, which has a single task. The task compiles the source files in the current directory. It uses both the AssemblyName and DebugType properties.
-
Step 5 creates target Application2, which contains two tasks: The first task compiles source3.cs and places the results in a library assembly; the second task compiles the item collection and references the library assembly.
This MSBuild command line reads the sample.proj project file. The output is the donis.exe assembly. The debugtype property is assigned full, whereas the assemblyname property is assigned donis.exe. This overwrites the default values of those properties. Finally, MSBuild invokes the Application1 target:
C:\>msbuild /p:debugtype=full,assemblyname=donis.exe sample.proj /target:application1
The following MSBuild command executes the tasks of the Application2 target:
C:\ >msbuild /p:debugtype=full,assemblyname=donis.exe sample.proj /target:application2
EAN: 2147483647
Pages: 161