Standard and Custom Toolset Configurations
An MSBuild Toolset contains tasks, targets, and tools that you can use to build an application project. MSBuild includes a standard Toolset, but you can also create custom Toolsets. For information about how to specify a Toolset, see MSBuild Toolset (ToolsVersion)
Standard Toolset Configurations
MSBuild 4.5 includes the following standard Toolsets:
ToolsVersion |
Toolset Path (as specified in the MSBuildToolsPath or MSBuildBinPath build property) |
|---|---|
2.0 |
Windows installation path\Microsoft.Net\Framework\v2.0.50727\ |
3.5 |
Windows installation path\Microsoft.NET\Framework\v3.5.20223\ |
4.0 |
Windows installation path\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 keys define the ToolsVersion.
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 Toolset 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 |
Sub-toolsets
If the registry key in the previous table has a subkey, MSBuild uses it to determine the path of a sub-toolset that contains more tools. The following subkey is an example:
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\4.0\11.0
The VisualStudioVersion build property indicates whether a sub-toolset becomes active. For example, a VisualStudioVersion value of "11.0" specifies the .NET Framework 4.5 sub-toolset. For more information, see the Sub-toolsets section of MSBuild Toolset (ToolsVersion).
Note
We recommend that you avoid changing these settings. Nevertheless, you can add your own settings and define computer-wide custom toolset definitions, as the next section describes.
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 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. By doing this, you can also use the $(MSBuildToolsPath) property to import .targets files from that directory.
Specify a custom Toolset in the configuration file for MSBuild.exe (or for the custom tool that hosts the MSBuild engine if that is what you are using). 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> 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, <configSections> must be the first subsection in the <configuration> section.
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) is set to the ToolsPath value that is specified either in the registry or in the configuration file where the ToolsVersion is defined. The $(MSBuildToolsPath) setting in the registry or the 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) is a reserved property that 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. To make these custom properties available to the project file, use the same name as the name of the value that is specified in the configuration file.