Standard and Custom Toolset Configurations

MSBuild 4.0 includes three pre-defined Toolsets, which are sets of tasks, targets, and command-line tools that you can use to build a project. You can also create your own custom Toolsets.

Toolset Types

When you define a custom Toolset, the value of the directory that $(MSBuildToolsPath) points to is also defined. Therefore, you can use $(MSBuildToolsPath) in a project file to import tasks and targets instead of hard-coding the task and target values in the project file. This lets you globally define Toolsets either in the registry or in a configuration file so that you can build on developer desktops or in build lab scenarios.

By using Toolsets, you can direct MSBuild to target specific .NET Framework versions. This means that you can build a project that works only with Visual Studio 2008, and that you can also build Visual Studio 2005 projects in Visual Studio 2008.

Standard Toolset Configurations

MSBuild 4.0 includes the following standard Toolsets:

ToolsVersion	Toolset Path (as specified in the MSBuildToolsPath or MSBuildBinPath build property)
2.0	WindowsInstallationPath\Microsoft.NET\Framework\v2.0.50727\
3.5	WindowsInstallationPath\Microsoft.NET\Framework\v3.5.20223\
4.0	WindowsInstallationPath\Microsoft.NET\Framework\v4.0.30319\

The ToolsVersion value determines which Toolset is used by a project that Visual Studio generates. You specify the ToolsVersion as an attribute in the Project element of the project file, but you can override that attribute by using the /toolsversion switch at a command prompt. For information about this attribute, this switch, and other ways to specify the ToolsVersion, see Overriding ToolsVersion Settings.

If the ToolsVersion isn't specified, the following registry keys define it.

Registry Hive	Key Name	String Key Value
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\3.5\	DefaultToolsVersion	2.0
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\4.0\	DefaultToolsVersion	2.0

The following registry keys specify the installation path of .NET Framework versions that are associated with each ToolsVersion. The installation path also specifies the location of MSBuild.exe, which defines the tool set information.

Registry Hive	Key Name	String Key Value
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\2.0\	MSBuildToolsPath	.NET Framework 2.0 Install Path
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\3.5\	MSBuildToolsPath	.NET Framework 3.5 Install Path
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\4.0\	MSBuildToolsPath	.NET Framework 4 Install Path

Note

We recommend that you do not change these settings unless you must. Nevertheless, you can add your own settings and define computer-wide custom Toolset definitions, as described in the next section.

Custom Toolset Definitions

When a standard Toolset does not fulfill your build requirements, you can create a custom Toolset. For example, you may have a build lab scenario in which you must have a separate build system for building Visual C++ projects.By using a custom Toolset, you can assign custom values to the ToolsVersion attribute when you create projects or run MSBuild.exe. Doing this also lets you use the $(MSBuildToolsPath) property to import .targets files from that directory.

Specify your custom Toolset in the configuration file for MSBuild.exe (or for a custom host of MSBuild if you have a separate tool that hosts the MSBuild engine). For example, the configuration file for MSBuild.exe could include the following toolset definition:

<msbuildToolsets default="3.0">
   <toolset toolsVersion="4.0">
      <property name="MSBuildToolsPath" 
        value="C:\Windows\Microsoft .NET\Framework\v3.0" />
   </toolset>
</msbuildToolsets>

<msbuildToolsets> is a custom .NET configuration section that must also be defined in the configuration file, as follows:

<configSections>
   <section name="msbuildToolsets"       
       Type="Microsoft.Build.BuildEngine.ToolsetConfigurationSection, 
       Microsoft.Build.Engine, Version=3.5.0.0, Culture=neutral, 
       PublicKeyToken=b03f5f7f11d50a3a"
   </section>
</configSections>

Note

To be read correctly, the configSections tag must be the first tag under the configuration tag.

ToolsetConfigurationSection is a custom configuration section that can be used by any host for custom configuration. If you use a custom Toolset, a host does not have to do anything to initialize the build engine except provide the configuration file entries. By defining entries in the registry, you can specify computer-wide Toolsets that apply to MSBuild.exe, Visual Studio, and all hosts of MSBuild.

Note

If a configuration file defines settings for a ToolsVersion that was already defined in the registry, the two definitions are not merged. The definition in the configuration file takes precedence and the settings in the registry for that ToolsVersion are ignored.

The following properties are specific to the value of ToolsVersion that is used in projects:

• $(MSBuildBinPath) - MSBuildBinPath is set to the ToolsPath value that is specified either in the registry or the configuration file where the ToolsVersion is defined. The $(MSBuildToolsPath) setting in the registry or configuration file specifies the location of the Toolset. In the project file, this maps to the $(MSBuildBinPath) property, and also to the $(MSBuildToolsPath) property.

• $(MSBuildToolsPath) - This reserved property is supplied by the MSBuildToolsPath property that is specified in the configuration file. (This property replaces $(MSBuildBinPath). However, $(MSBuildBinPath) is carried forward for compatibility.)

You can also add custom, ToolsVersion-specific properties to the configuration file by using the same syntax that you use to add the MSBuildToolsPath property. These custom properties are available to the project file by using the same name as the value specified in the configuration file.

See Also

Other Resources

MSBuild Advanced Concepts

Change History

Date	History	Reason
	Clarified information about the default tools version.	Information enhancement.