Difference between ToolsVersion and TargetFrameworkVersion

Question

What is the difference between ToolsVersion and TargetFrameworkVersion?

<Project DefaultTargets="Build"  ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
   ......  
    <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>

Answer 1

The difference is that TargetFrameworkVersion actually has any effect, whereas ToolsVersion is normally fully and totally ignored by you tool chain if you are using any VS up from VS2013.

As Daniel states succinctly:

The target framework is for which .net framework features/classes are available to use in your code.

---

As for ToolsVersion (within the Projectelement of your project file):

It's ignored, unless you specify MSBUILDLEGACYDEFAULTTOOLSVERSION: note the "legacy" in the var name.

This is actually evidenced in the MSDN docs, but you have to jump back and forth between the versions and having background facts like Compiling for ToolsVersion 12 with Visual Studio 2015 also helps.

Here's the relevant MSDN sections: (all emph. mine)

MSBuild Toolset (ToolsVersion)

When a ToolsVersion value is defined in a project file, MSBuild uses that value to determine the values of the Toolset properties that are available to the project. One Toolset property is $(MSBuildToolsPath), which specifies the path of the .NET Framework tools. Only that Toolset property (or $(MSBuildBinPath)), is required.

... this is factually wrong, and comparing VS2015 docs with the VS2012 docs, we see that the paragraph was copied down.

However, the VS2015 docs continue with a second paragraph, that is missing in the VS2012 version:

Starting in Visual Studio 2013, the MSBuild Toolset version is the same as the Visual Studio version number. MSBuild defaults to this Toolset within Visual Studio and on the command line, regardless of the toolset version specified in project file. This behavior can be overridden by using the /ToolsVersion flag. For more information, see Overriding ToolsVersion Settings.

And following the link, we see:

Overriding ToolsVersion Settings

...

Order of Precedence

The order of precedence, from highest to lowest, used to determine the ToolsVersion is:

1. The ToolsVersion attribute on the MSBuild task used to build the project, if any.
2. The /toolsversion (or /tv) switch that's used in the msbuild.exe command, if any.
3. If the environment variable MSBUILDTREATALLTOOLSVERSIONSASCURRENT is set, then use the current ToolsVersion.

4. If the environment variable MSBUILDTREATHIGHERTOOLSVERSIONASCURRENT is set and the ToolsVersion defined in the project file is greater than the current ToolsVersion, use the current ToolsVersion.

5. If the environment variable MSBUILDLEGACYDEFAULTTOOLSVERSION is set, or if ToolsVersion is not set, then the following steps are used:

   1. The ToolsVersion attribute of the Project element of the project file. If this attribute doesn’t exist, it is assumed to be the current version.
   2. The default tools version in the MSBuild.exe.config file.
   3. The default tools version in the registry. For more information, see Standard and Custom Toolset Configurations.

6. If the environment variable MSBUILDLEGACYDEFAULTTOOLSVERSION is not set, then the following steps are used:

   1. If the environment variable MSBUILDDEFAULTTOOLSVERSION is set to a ToolsVersion that exists, use it.
   2. If DefaultOverrideToolsVersion is set in MSBuild.exe.config, use it.
   3. If DefaultOverrideToolsVersion is set in the registry, use it.
   4. Otherwise, use the current ToolsVersion.

Note that the project file is only used in the highlighted case.

Answer 2

The tools version is what version of MSBuild to use. The target framework is for which .net framework features/classes are available to use in your code.