Thursday, September 03, 2009

NotesMSBuild

NotesMSBuild
=============

Contents
=========
Paths
MSBuild schema
MSBuild summary
MSBuild complete structure
Output Element
MSBuild tasks
MSBuild conditions
MSBuild reserved properties
MSBuild command line
MSBuild Well-known item metadata


Paths
======
When MSBUILD executes, the default root path of any relative path references made in the *.proj file, is the path where the *.proj file is executing from.
For example, if *.proj is in C:\test, then any relative path reference in the *.proj file starts from C:\test.


MSBuild schema
===============
The official schema or xsd for MSBuild can be found in:
Program Files\Microsoft Visual Studio 8\Xml\Schemas\1033\Microsoft.Build.xsd


MSBuild summary
================
Reference: In the MSDN, look for .Net Development - .Net Framework SDK - General Reference - MSBuild Reference.

MSBuild is a tool that lets developer perform various operations on a set of files given some specified conditions. To those who know the Makefile utility in Linux/Unix, MSBuild performs similar build tasks. From what I've read, MSBuild should be quite similar to NUnit and similar tools.

MSBuild is defined using XML file format, its structure is shown in the section "MSBuild complete structure" below.
Being XML based, it has the typical child elements and attributes structure that are in other XML formats.
The key items that drive MSBuild as I see it are the:
i) Targets - this allow the user to specify what to do
ii) Tasks - this allow the MSBuild designer to pre-specify the various tasks to be performed for each of the defined Targets.

The MSBuild design is typical saved as fileName.proj

To make use of the names defined in the MSBuild project file:
$()  Extracts the value of a property
@()  Extracts the value of an item as a list, that is, vector
%()  Extracts value of an item as a single string, that is, scalar


Example:

MSBuild complete structure
===========================
The complete MSBuild structure is shown in the tree / hierarchy below. The purpose of this diagram is to provide a quick illustration of the child elements and attribute relationships which is not easy to see from the official schema / xsd.

The top level element is the Project element.
: denotes attributes of the element
+ denotes child elements
Element names which begin with small letters, {item, itemMetaData, property, parameter} are actually
user defined names.



Project
    : DefaultTargets  eg DefaultTargets="tarA;TarB"
    : InitialTargets  eg InitialTargets="tarC;tarD"
    : xmlns           eg xmlns="http://schemas.microsoft.com/developer/msbuild/2003"
    + Choose
        + Otherwise
            + Choose
            + ItemGroup
            + PropertyGroup
        + When
            : Condition,  eg Condition="'StringA'=='StringB'"
            + Choose
            + ItemGroup
            + PropertyGroup
    + Import
        : Condition
        : Project,  eg Project="ProjectPath"
    + ItemGroup
        : Condition
        + item
            : Condition
            : Exclude,  eg Exclude="MyFile.cs"
            : Include,  eg Include="*.cs"
            + itemMetaData
    + ProjectExtensions
    + PropertyGroup
        : Condition
        + property
            :Condition
    + Target
        : Condition
        : DependsOnTargets
        : Inputs
        : Name
        : Outputs
        + Error
            : Condition
            : Text
        + Message
            : Condition
            : Text
        + OnError
            : Condition
            : ExecuteTargets, eg ExecuteTargets="TargetName"
        + task
            : Condition
            : ContinueOnError   eg ContinueOnError="true/false"
            : parameter         eg par1="val1" par2="val2" par3="val3"
            + Output
                : Condition
                : ItemName      either ItemName or PropertyName is required
                : PropertyName
                : TaskParameter
        + Warning
            : Condition
            : Text
    + UsingTask
        : AssemblyFile
        : AssemblyName
        : Condition
        : TaskName














Output Element
==============
Output is an element not a task. The general structure for the Output Element is:

    [PropertyName="PropertyName" | ItemName="Item name"]
    Condition = "'String A' == 'String B'" />

Either the PropertyName or the ItemName attribute must be included with each Output element.
The value for the Output's TaskParameter must be the special name of the parameter of the task.
In the example below where Output is used with the Copy Task, the parameter "CopiedFiles" is a special name and is one of the defined parameters for COPY (see Copy task reference). The list of copied files is being held it the item called "SuccessfullyCopiedFiles". This list can be used by calling @(SuccessfullyCopiedFiles)



    
        SourceFiles="@(MySourceFiles)"
DestinationFiles="............"
        DestinationFolder="@(MyDestFolder)">
        
            TaskParameter="CopiedFiles"
            ItemName="SuccessfullyCopiedFiles"/>
    


MSBuild Tasks
==============
The following tasks list is taken from http://msdn.microsoft.com/en-us/library/7z253716(VS.80).aspx


AL (Assembly Linker) Task
Describes the AL task and its parameters.

AspNetCompiler Task
Wraps aspnet_compiler.exe, a utility to precompile ASP.NET applications.

AssignCulture Task
Assigns culture identifiers to items.

Copy Task
Describes the Copy task and its parameters.

CreateItem Task
Describes the CreateItem task and its parameters.

CreateProperty Task
Describes the CreateProperty task and its parameters.

Csc Task
Describes the Csc task and its parameters.

Delete Task
Describes the Delete task and its parameters.

Exec Task
Describes the Exec task and its parameters.

FindUnderPath Task
Determines which items in the specified item collection exist in the specified folder and all of its subfolders.

GenerateApplicationManifest Task
Describes the GenerateApplicationManifest task and its parameters.

GenerateBootstrapper Task
Provides an automated way to detect, download, and install an application and its prerequisites.

GenerateDeploymentManifest Task
Describes the GenerateDeployManifest task and its parameters.

GenerateResource Task
Converts .txt and .resx files to common language runtime binary .resources files.

GetAssemblyIdentity Task
Retrieves the assembly identities from the specified files and outputs the identity information.

GetFrameworkPath Task
Retrieves the path to the .NET Framework assemblies.

GetFrameworkSdkPath Task
Retrieves the path to the .NET Framework SDK.

LC Task
Describes the LC task and its parameters.

MakeDir Task
Describes the MakeDir task and its parameters.

MSBuild Task
Describes the MSBuild task and its parameters.

ReadLinesFromFile Task
Reads a list of items from a text file.

RegisterAssembly Task
Describes the RegisterAssembly task and its parameters.

RemoveDir Task
Describes the RemoveDir task and its parameters.

ResGen Task
Describes the ResGen task and its parameters.

ResolveAssemblyReference Task
Describes the ResolveAssemblyReference task and its parameters.

ResolveComReference Task
Describes the ResolveCOMReference task and its parameters.

ResolveKeySource Task
Determines the strong name key source

ResolveNativeReference Task
Resolves native references.

SGen Task
Creates an XML serialization assembly for types in the specified assembly.

SignFile Task
Signs the specified file using the specified certificate.

Touch Task
Describes the Touch task and its parameters.

UnregisterAssembly Task
Describes the UnregisterAssembly task and its parameters.

Vbc Task
Describes the Vbc task and its parameters.

VCBuild Task
Describes the VCBuild task and its parameters.

WriteLinesToFile Task
Writes the specified items to the specified text file.


MSBuild conditions
===================
'A'=='B'      true if A equals B
'A'!='B'      not true if A equals B
<, >, <=, >=    Compares numerical values. Note: need to use < for < and > for >
Exists('sss')   Eg. Condition="!Exists('$(buildir)')"
!             negation
And           and operator
Or            or operator
()            for grouping of expressions



MSBuild reserved properties
============================
Reference: http://msdn.microsoft.com/en-us/library/ms164309(VS.80).aspx

MSBuildProjectDirectory
 The absolute path of the directory where the project file is located, for example, C:\MyCompany\MyProduct.

MSBuildProjectFile
 The complete file name of the project file, including the file name extension, for example, MyApp.proj.

MSBuildProjectExtension
 The file name extension of the project file, including the period, for example, .proj.

MSBuildProjectFullPath
 The absolute path and complete file name of the project file, for example, C:\MyCompany\MyProduct\MyApp.proj.

MSBuildProjectName
 The file name of the project file without the file name extension, for example, MyApp.

MSBuildBinPath
 The absolute path of the directory where the MSBuild binaries that are currently being used are located, for example, C:\Windows\Microsoft.Net\Framework\v2.0. This property is useful if you need to refer to files in the MSBuild directory.

MSBuildProjectDefaultTargets
 The complete list of targets specified in the DefaultTargets attribute of the Project element. For example, the following Project element would have an MSBuildDefaultTargets property value of A;B;C.


MSBuildExtensionsPath
 The MSBuild folder under the Program Files directory. This location is a useful place to put custom target files. For example, your targets files could be installed at \Program Files\MSBuild\MyFiles\Northwind.targets and then imported in project files with the following XML.



MSBuild command line
=====================

For more information on how to use command line, type:
MSBuild.exe /help

Example on a typical usage:
MSBuild.exe /nologo /targets:targetName /property:name=val /verbosity:quiet|minimal|normal|detailed|diagnostic projectFile.proj


MSBuild Well-known item metadata
=================================
Every item has a set of default metadata specified during their creation. The list given below is taken from:
http://msdn.microsoft.com/en-us/library/ms164313(VS.80).aspx


%(FullPath)
 Contains the full path of the item. For example: C:\MyProject\Source\Program.cs

%(RootDir)
 Contains the root directory of the item. For example: C:\

%(Filename)
 Contains the file name of the item, without the extension. For example: Program

%(Extension)
 Contains the file name extension of the item. For example: .cs

%(RelativeDir)
 Contains the directory path relative to the current working directory. For example: Source\

%(Directory)
 Contains the directory of the item, without the root directory. For example: MyProject\Source\

%(RecursiveDir)
 If the Include attribute contains the wildcard **, this metadata specifies the directory that replaced the wildcard to find the item. This example has no RecursiveDir metadata, but if the the following example was used to include this item, the item would contain a RecursiveDir value of MyProject\Source\.




%(Identity)
 The item specified in the Include attribute.. For example: Source\Program.cs

%(ModifiedTime)
 Contains the timestamp from the last time the item was modified. For example: 2004-07-01 00:21:31.5073316

%(CreatedTime)
 Contains the timestamp from when the item was created. For example: 2004-06-25 09:26:45.8237425

%(AccessedTime)
 Contains the timestamp from the last time the time was accessed. 2004-08-14 16:52:36.3168743

No comments: