MSBuild Team Blog : Jay Shrestha

ToolsVersion metadata for items used in MSBuild task's

msbuild — Tue, 17 Jul 2007 19:39:00 GMT

Greetings MSBuilders!

In Visual Studio 2005 you could only target the 2.0 Framework tools. MSBuild targets files which define the build process and MSBuild tasks to use the 1.1 framework tools were not supported . With the help of our CPX team we released MSBee to provide support for .NET 1.1.

With the release of MSBuild Orcas we’ve taken this a step further and made multi-targeting a full-fledged feature. For an overview of this feature check out the blog post Multi-Targeting how does it work

In order to make it easier for our customers to use the Multi-Targeting feature specifically when building multiple projects with different Tools version - in Orcas MSBuild we have introduced a new reserved metadata “ToolsVersion” on items which will be used in the Projects attribute of the MSBuild task. This new metadata is only applicable to items passed in the Projects attribute of the MSBuild task. The purpose of this is to provide our customers a flexible way to pass different ToolsVersion for different projects being built using the MSBuild task. If you use the ToolsVersion attribute of the MSBuild task then it will be applied to all the projects being built using the MSBuild task.

For instance if you are building multiple projects using the MSBuild task where most of them needs to be built with 2.0 framework and tools (compilers) but 1 has to be built using 3.5 because it uses the Windows Presentation Foundation framework your project file would look something like this -

(… represents additional project files)

a.proj

</Target>

</Project>

By using the ToolsVersion metadata you can simplify the above to use a single MSBuild task by writing the project file as following:

a.proj

</ProjectToBuild>

</ProjectToBuild>

</ItemGroup>

</Target>

</Project>

</ProjectToBuild>

</ItemGroup>

</Target>

</Project>

One of the benefit we get from these new sets of metadata is to be able to consolidate all projects into a single MSBuild task invocation and not have to do any batching or conditional MSBuild tasks. In doing so it also allows us to parallelize all the projects listed (contained in an item) in the Projects attribute if “BuildInParallel=true” attribute is present in the MSBuild task as we can only parallelize projects within a single invocation of MSBuild task. For additional details on build parallelization you can check out the blog post: Building Projects in parallel.

[ Author: Jay Shrestha, MSBuild Software Engineer ]

Properties and AdditionalProperties metadata for items used in MSBuild task's

msbuild — Tue, 17 Jul 2007 19:34:00 GMT

Greetings MSBuilders!

Passing properties to projects specifically when you want to pass different sets of properties to different projects listed in the same item has always been challenging. To achieve this is Visual Studio 2005 you would have to break the item according to the properties you wanted to pass it or use batching techniques to batch the MSBuild task and provide different properties to projects based on condition or other proprietary method.

To ease this problem, in Orcas MSBuild we have introduced 2 new reserved metadata “Properties” and “AdditionalProperties” on items which will be used in the Projects attribute of the MSBuild task. This new metadata is only applicable to items passed in the Projects attribute of the MSBuild task. The purpose of this is to provide our customers a flexible way to pass different Properties for different projects being built using the MSBuild task. If you use the Properties attribute of the MSBuild task then it will be applied to all the projects being built using the MSBuild task unless you batch the MSBuild task and conditionally provide different properties for each project in the item list

Properties metadata

For instance if you are building multiple solution files using the MSBuild task where you want certain solution files to be built using the Release configuration and other using the Debug configuration, with 2.0 MSBuild you will need to have multiple instances of MSBuild task where each will build certain sets of project with Release configuration and the other with Debug configuration. Your project file would look similar to the following

(… represents additional solution files)

a.proj

</Target>

</Project>

By using the Properties metadata you can simplify the above to use a single MSBuild task by writing the project file as following:

a.proj

<Properties>Configuration=Debug</ Properties >

</ProjectToBuild>

< Properties > Configuration=Release</ Properties >

</ProjectToBuild>

</ItemGroup>

</Target>

</Project>

< Properties > Configuration=Release</ Properties >

</ProjectToBuild>

</ItemGroup>

</Target>

</Project>

AdditionalProperties metadata

For instance if you are building multiple solution files using the MSBuild task where you want to build all the solution in Release configuration and some with x86 architecture and some with ia64 architecture, with 2.0 MSBuild you will need to have multiple instances of MSBuild task where each will build certain sets of project with Release configuration and x86 Architecture and the other with Release configuration and ia64 architectre. Your project file would look similar to the following

(… represents additional solution files)

a.proj

</Target>

</Project>

By using the AdditionalProperties metadata you can simplify the above to use a single MSBuild task by writing the project file as following:

a.proj

<AdditionalProperties> Architecture=x86</ AdditionalProperties >

</ProjectToBuild>

< AdditionalProperties > Architecture=ia64</ AdditionalProperties >

</ProjectToBuild>

</ItemGroup>

</Target>

</Project>

[ Author: Jay Shrestha, MSBuild Software Engineer ]

Building projects in parallel

msbuild — Thu, 26 Apr 2007 20:40:00 GMT

Greetings MSBuilders!

Orcas MSBuild introduces a new feature allowing build authors to build projects in parallel. To enable this feature we have introduced a new parameter to the MSBuild task called “BuildInParallel” and a new command line parameter called “maxcpucount” or “m”. Note that if you do not set the “maxcpucount”, even though you set “BuildInParallel” parameter to true, your projects will be built serially.

Each MSBuild process (including the main or parent process started from command line) contains a component called the node. Projects are processed and built by the node component. Thus using “maxcpucount” of 2 will result in 2 MSBuild processes. If your projects have dependencies on other projects that are being built in parallel, then you will need to set appropriate project to project references so that dependent projects get built first. For instance in the below example (Example 1) if project d has a dependency on project c, building them in parallel could result in any of these projects being built first or both building concurrently. If project d got built first then your build would fail. In order to prevent this you will need to set up a project to project reference from project d to project c. Thus, if project d is built first, it will first follow the project to project reference and build project c, then it would build project d. Setting a project to project reference include invoking the MSBuild task to build the dependent project. Example 2 briefly demonstrates this.

The order at which the projects are built is dependent on the scheduling algorithm of MSBuild. You cannot assume any particular order.

Example 1:

a.proj

</Target>

</Project>

b.proj

</Target>

</Project>

c.proj

</PropertyGroup>

</Target>

</Project>

d.proj

</PropertyGroup>

</ItemGroup>

</Target>

</Project>

Command line: msbuild a.proj /m:2

In order to prevent the build from failing in case project c and project d build simultaneously we need to set up the following project to project reference

Example 2

c.proj

</PropertyGroup>

</Target>

</Project>

d.proj

</PropertyGroup>

</ItemGroup>

</Target>

</Target>

</Project>

[Author: Jay, MSBuild Software Engineer]

Caching Behaviour in Orcas msbuild

msbuild — Thu, 26 Apr 2007 20:27:00 GMT

Greetings MSBuilders!

Orcas MSBuild introduces a new parameter for the CallTarget and MSBuild task called “UseResultsCache”. Enabling this feature allows the MSBuild engine to cache the built target results like the outputs attribute from the target. At this point you may be wondering why do we need to cache the results of a target. Well - we have also introduced a new parameter in the MSBuild task called “UnloadProjectsOnCompletion”. Enabling this feature will cause the MSBuild engine to unload the project from memory once it has completed building. In version 2, once a project is loaded it is resident in memory. When building lots of project, this can cause memory usage problems. To prevent using lots of memory we introduced the unloading of projects when it has completed building. The drawback to this feature is that once the project has been unloaded than you cannot load it again (you will get an error). In your build process you may often have targets that you may need to call to gather some information even after the project has been unload and to support this we introduced target result caching. If the results of a target has been cached than even if the project is unloaded we will be able to retrieve the results.

For example in Microsoft.Common.Targets we have targets like GetCopyToOutputDirectoryItems and GetTargetPath which could get called after the project is unloaded - for instance from another project referencing this unloaded project (which may have already completed build and unload). The referencing project calls the GetCopyToOutputDirectoryItems and GetTargetPath targets. If the results of these targets where not cached than we would error. However if you look at Microsoft.Common.Targets we use CallTarget and UseResultsCache to cache the results before the build is completed (During the CoreBuild target) so rather than getting an the cached results are returned back to the referencing project.

Example:

a.proj

</Target>

</Target>

</Project>

b.proj

</MSBuild>

</Target>

</Project>

Building project b.proj using the command line “msbuild.exe b.proj /tv:3.5” will generate an error :

a.proj : error MSB4161: Project " a.proj" was loaded and unloaded during the current

build. Reloading a project during the build can result in errors or an inconsistent build state. Either avoid unloading

project " a.proj" or cache the evaluation results of target(s) "Normal" before unloading the project.

If you now change a.proj to –

</Target>

</Target>

</Project>

Building project b.proj using the command line “msbuild.exe b.proj /tv:3.5” will succeed and you will see the output of target Normal from project a being printed from project b.

[Author: Jay, MSBuild Software Engineer ]