MSBuild Team Blog

MSBuild, Orcas, and Multi-targeting

Disclaimer: Since I am talking about Orcas, and as of yet unreleased software, what follows is subject to change.

So if you were curious enough to dig into what the October 2006 Orcas CTP contained, you might have seen something related to MSBuild - namely, Multi-Targeting. Here's what the release notes for the CTP says, with respect to MSBuild and Multi-Targeting:

MSBuild Multi-targeting: Support multitargeting within the IDE by enabling Visual Studio to leverage MSBuild using the tasks and targets that were shipped in Visual Studio 2005. Additionally, command line solutions will build using the toolset appropriate for the .NET Framework version that is being targeted.

I just wanted to provide more clarity around what this means, because it does not entirely present an accurate picture. To make things worse, the topic of multi-targeting itself is a bit cloudy and confusing, so I want to shed some light on the big picture. 

Firstly, multi-targeting support within Visual Studio Orcas is not entirely available in the October CTP just yet. The MSBuild support is all there, but the IDE features to leverage it fully are still in development. However, MSBuild is entirely capable of multi-targeting as described, so I’ll try to distill what “multi-targeting” means as it relates to MSBuild.

By the time Orcas releases, there will be three different frameworks that will be available to you for building your applications:  

• .NET Framework 2.0 (Visual Studio 2005 timeframe)
• .NET Framework 3.0 (Vista timeframe)
• .NET Framework 3.5 (Orcas timeframe).

What makes things even more interesting is that by the time Orcas ships, there will only be two toolsets that can build code for these three frameworks, so toolsets and frameworks don’t exactly map one to one. By toolset, I am referring to the set of tools and build process that ships in the .NET Framework that allow you to build your code to run on the platform. The two toolsets are:

• .NET Framework 2.0 toolset (csc.exe, vbc.exe, tasks and targets files that shipped along with Visual Studio 2005)
• .NET Framework 3.5 toolset (csc.exe, vbc.exe, tasks and targets files that will ship in Orcas)

Today, you use the .NET Framework 2.0 toolset to build code targeting .NET Framework 2.0 and .NET Framework 3.0. Also, MSBuild version numbers line up with the version of the framework that it ships in - so we are calling MSBuild that you already use today as 2.0, and the Orcas version is currently called MSBuild 3.5. 

In order to provide a compelling upgrade story and an easy migration scenario between Visual Studio 2005 and Visual Studio Orcas, we (MSBuild team) had to follow a few ground rules without compromise. It turns out that these rules also boil down to fundamental principles that any good build tool should adhere to:

1. Always maintain clean separation between the build engine and the toolset. A new version of the MSBuild engine/MSBuild.exe should be able to build using a previously shipped toolset.
2. When building projects authored to build using an older toolset, a newer version of MSBuild.exe should not automatically move you forward to the new toolset, forcing you to take on additional dependencies that you don't need.
3. Switching to the new toolset and building using a newer set of tools, compilers, etc should be as easy, as long as you are moving between compatible versions of the framework.

So how does all of this manifest itself in the Orcas CTP that I started this little post with? That's the fun part.

The Orcas tools are installed in the %windir%\Microsoft.Net\Framework\v3.5.xxxxx. That's where the new version of MSBuild lives in Orcas (at least for now - remember, this is all very preliminary and subject to change as we tweak things). MSBuild 3.5 is entirely side by side with MSBuild 2.0. Here's a quick rundown of what it means to use MSBuild 3.5:

• You can use it to build projects and solutions created using Visual Studio 2005, and it will continue to use the 2.0 tools and targets files to build the project - no new tools are used at all, giving you the same build results as if you were using the previous version of MSBuild. You will want to do this to use the new engine features, improved performance of the new version of MSBuild without taking on a new build process.
• You can use it to build existing .NET 2.0 / Visual Studio 2005 projects using the Orcas / .NET Framework 3.5 toolset by using the /ToolsVersion:3.5 from the command line. The other available toolset of course, is /ToolsVersion:2.0 to explicitly build using 2.0.
• You can author projects that automatically build with the new toolset - simply edit your Visual Studio authored project file, add a ToolsVersion="3.5" attribute on the <Project> element, and build with msbuild.exe version 3.5.
• Visual Studio Orcas will explicitly author projects to use the new 3.5 toolset - this is because Visual Studio Orcas requires the new compilers and targets files that ships in the .NET Framework 3.5.
• If you are using the 3.5 toolset, you can also specify a <TargetFrameworkVersion> property in your project that will give you version specific build process rules based on the framework you are targeting. It is this property that enables MSBuild and the rest of the 3.5 tools to target all three different versions of the framework. Obviously, the 2.0 build process does not honor this property in the same way the 3.5 toolset does. I will get into the details of TargetFrameworkVersion in a subsequent post.

I've tried to show the side by side aspects in the figure below. Note that MSBuild 2.0 cannot use the 3.5 toolset, but MSBuild 3.5 can consume both toolsets.

In summary, here are the key takeaways

• MSBuild 3.5 will not force you to a new toolset and build process
• The concept of a Toolset (specified using ToolsVersion attribute) is new - think of a toolset as a matched set of tasks, targets, and command line tools that can build for a particular version of the framework.
• MSBuild Orcas will include a build process that is "Target Framework Version" aware, and can support .NET Framework 2.0, 3.0 and 3.5.
• You can build a project with either the 2.0 or the 3.5 toolset by explicitly overriding the ToolsVersion you use. 

That's just the start of it - there's a ton of functionality in there, and I will cover it over the coming weeks. Please let us know what you think about all of this, as gathering feedback is the primary purpose of releasing CTPs. Like I mentioned earlier, as is with any pre-release software, keep in mind that all of this could change based on what you tell us and based on what we find!

[ Author : Faisal Mohamood ]