MSBuild Multitargeting

By using Visual Studio, you can compile an application to run on any one of several versions of the .NET Framework. For example, you can compile an application to run on the .NET Framework version 2.0, and compile the same application to run on the .NET Framework version 4. The ability to compile to more than one framework is named multitargeting.

These are some of the benefits of multitargeting:

• You can develop applications that target earlier versions of the .NET Framework, for example, versions 2.0, 3.0, and 3.5.

• You can target frameworks other than the .NET Framework, for example, the Silverlight Framework.

• You can target a framework profile, which is a predefined subset of a target framework.

• If any service packs for the .NET Framework version 4 are released, you could target them.

• Multitargeting guarantees that an application uses only the functionality that is available in the target framework.

A target framework is the particular version of the .NET Framework that your project is built to run on. It is necessary because it enables compiler features that are exclusive to that version of the .NET Framework 2.0, or references to assemblies that are included only in that version of the Framework.

When you compile an application to target a specific framework, you must coordinate these three sets of software components:

• Tool set, which contains the compilers, tasks, and targets that are used to create the application.

• Reference assemblies, which are used to design and build the application.

• Runtime assemblies, which are used to run the application.

Tool Set (ToolsVersion)

A tool set is a matched set of MSBuild tasks, MSBuild targets, and tools that installs with MSBuild and the .NET Framework. A tool set includes compilers such as csc.exe and vbc.exe, the common targets file (microsoft.common.targets), and the common tasks file (microsoft.common.tasks). The 4.0 tool set can be used to target .NET Framework versions 2.0, 3.0, 3.5 and 4. The 2.0 tool set, however, can only be used to target .NET Framework version 2.0.

You designate the tool set by setting the ToolsVersion attribute of the Project element of a project file, for example,

<Project ToolsVersion="4.0" ...

You can use the version 4.0 tool set to compile applications to run on a variety of target frameworks, provided that a target pack is installed for every framework you want to target. For more information, see "Target Packs" later in this topic.

You can also create your own custom Toolsets. For more information, see Standard and Custom Toolset Configurations.

Reference Assemblies

Typically, frameworks have associated reference assemblies. A reference assembly is a simplified assembly that does not have code, and that exposes only the public types and members.

At design time and build time, Visual Studio uses the reference assemblies for the target framework as filters to make available only the types and members that are compatible with that framework. For example, when you are targeting the .NET Framework version 3.5, types and members that are provided only by the .NET Framework version 4 are not displayed in Visual Studio designers such as the .NET tab of the Add Reference dialog box, and are not available to the build process.

For example, LINQ is a new technology that is included in Visual Studio 2008. .NET Framework 3.5 is the only version of the .NET Framework that has LINQ-related assemblies. Therefore, you cannot use LINQ unless your project specifically targets .NET Framework 3.5 or later. Similarly, Windows Presentation Foundation (WPF) is included in Windows Vista. You cannot build WPF applications unless your project targets .NET Framework 3.0 or later versions of the .NET Framework.

Target Packs

Reference assemblies are made available when the corresponding target pack is installed. A target pack contains reference assemblies and a FrameworkList.xml file that lists them. The FrameworkList.xml file is also known as the redistribution (redist) list.

Target packs are available from these sources:

• Target packs for the .NET Framework versions 2.0, 3.0, and 3.5 are included in the .NET Framework version 3.5 SP1.

• Target packs for the .NET Framework version 3.5 client profile, the .NET Framework version 4 and version 4 client profile, and Silverlight are included in Visual Studio.

Typically, target packs are installed in the ..\Program Files (x86)\Reference Assemblies\Microsoft\Framework\ folder. The target pack for the .NET Framework version 2.0 is typically installed in ..\Windows\Microsoft.NET\Framework\v2.0.50727\ folder.

When you build a solution or project on the command line, specifying a ToolsVersion attribute for msbuild.exe causes all projects and their project-to-project dependencies to be built according to that tools version, even if each project in the solution specifies its own ToolsVersion attribute in its Project Element (MSBuild).

Runtime Assemblies

You cannot set a target framework in Visual Studio unless the target pack for that framework is installed. For example, to target the .NET Framework version 3.0, its reference assemblies and the compatible assemblies must be installed. At runtime, the common language runtime (CLR) fusion loader binds the application to the runtime assemblies of the framework that it targets.

Selecting a Target Framework

To select a target framework for an existing project

1. In Solution Explorer, right-click the project node and then click Properties.

2. On the Application tab, on the Target Framework list, select a framework. Only frameworks that have a target pack installed are displayed on this list.

   Visual Studio uses your selection to set the values of these three elements in the project file:

   • The TargetFrameworkIdentifier element names the target framework, for example,

     <TargetFrameworkIdentifier>Silverlight</TargetFrameworkIdentifier>

     If this element is missing, its value defaults to ".NETFramework".

   • The TargetFrameworkVersion element names the target framework version, for example,

     <TargetFrameworkVersion>v3.0</TargetFrameworkVersion>

   • The TargetFrameworkProfile element names the target framework profile, for example,

     <TargetFrameworkProfile>Client</TargetFrameworkVersion>

     If this element is missing, the full framework is targeted.

   These three elements are combined by the Common targets of the Visual Studio build system to form an identifier known as the target framework moniker (TFM).

Scenario: Visual Studio Targets the .NET Framework Version 3.5

Assume that Visual Studio is running under the .NET Framework version 4. To target the .NET Framework version 3.5, you must have the associated reference assemblies and runtime assemblies installed. These assemblies are included in the .NET Framework version 3.5 SP1.

In this scenario, the Visual Studio designers display only what is filtered by the .NET Framework version 3.5 reference assemblies, and when you build a project, it is built against those reference assemblies. When you run the project, it runs on the .NET Framework version 3.5 runtime assemblies, which in turn run on CLR version 2.0.

When you deploy the application to another computer, it must have the .NET Framework version 3.5 installed. You can check for version 3.5 on the target computer, and install it if it is required, by using a suitable redistribution package (redist).

Scenario Two: Visual Studio Runs on the .NET Framework Version 4.1 and Targets the .NET Framework Version 4

Assume that a .NET Framework version 4.1 becomes available, and that version 4 and version 4.1 both run under CLR version 4. If the .NET Framework version 4.1 is installed, Visual Studio would automatically run under it.

For a project that targets the .NET Framework version 4, the version 4 reference assemblies would filter the types and members that are available in the Visual Studio designers, the project would be built against those reference assemblies, and the resulting application would run against the version 4 runtime assemblies.

See Also

Concepts

Resolving Assemblies at Design Time

Other Resources

MSBuild Advanced Concepts