Standard and Custom Toolset Configurations
MSBuild 3.5 includes two pre-defined Toolsets. Toolsets 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.
Note
We recommend that you read Using MSBuild to Target Specific .NET Framework Versions to better understand Toolsets, target frameworks, and ToolsVersions before you continue.
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.
Visual Studio 2008 includes two "standard" Toolsets. One Toolset, which was also included with MSBuild 2.0 in Visual Studio 2005, targets .NET Framework 2.0. The other Toolset, which is included in MSBuild 3.5, can target .NET Framework 2.0, .NET Framework 3.0, and .NET Framework 3.5.
Standard Toolset Configurations
MSBuild 3.5 includes the following standard Toolsets:
ToolsVersion |
MSBuildToolsPath or MSBuildBinPath |
|---|---|
2.0 |
<Windows installation path>\Microsoft.Net\Framework\v2.0.50727\ |
3.5 |
<Windows installation path>\Microsoft.NET\Framework\v3.5.20223\ |
The standard Toolsets are available anywhere on the computer when you run MSBuild.exe or create an instance of the MSBuild Engine, unless the information in the Toolset is overridden in the MSBuild.exe.config file or a host-specific configuration file.
The ToolsVersion value, which is specified as an attribute in the Project tag of the project file, determines which Toolset is used by a Visual Studio generated project. You can think of ToolsVersion as the "name" of a Toolset. If a ToolsVersion is not specified in the project, a default ToolsVersion is used. For MSBuild 3.5, the default ToolsVersion value is set to 2.0. This means that projects that build without an explicit ToolsVersion will use the 2.0 toolset that was included with Visual Studio 2005. Visual Studio 2008 projects automatically generate all projects with a ToolsVersion value of 3.5. Because it uses this new Toolset, it can target all three .NET Framework versions.
Standard Toolset information is defined in the following registry keys:
Registry Hive |
String Key Name |
String Key Value |
|---|---|---|
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\3.5\ |
DefaultToolsVersion |
2.0 |
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\2.0\ |
ToolsPath |
.NET Framework 2.0 Install Path |
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\3.5\ |
ToolsPath |
.NET Framework 3.5 Install Path |
DefaultToolsVersion specifies which Toolset to use when you build a project that does not specify a Toolset. For example, the DefaultToolsVersion value for MSBuild in Visual Studio 2008 is 2.0. The value of DefaultToolsVersion can be overridden in host-specific configuration files. The other values define the installation paths for the .NET Framework versions.
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. (Alternatively, you can also use environment variables if you are not interested in defining a separate Toolset.)
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.