MSBuild-Toolset (ToolsVersion)MSBuild Toolset (ToolsVersion)

MSBuild verwendet ein Toolset von Aufgaben, Zielen und Tools für die Erstellung einer Anwendung.MSBuild uses a Toolset of tasks, targets, and tools to build an application. Ein MSBuild-Toolset umfasst in der Regel eine Datei mit allgemeinen Aufgaben (microsoft.common.tasks), eine Datei mit allgemeinen Zielen (microsoft.common.targets) und Compiler wie csc.exe und vbc.exe.Typically, a MSBuild Toolset includes a microsoft.common.tasks file, a microsoft.common.targets file, and compilers such as csc.exe and vbc.exe. Die meisten Toolsets können verwendet werden, um Anwendungen für mehr als eine Version von .NET Framework und mehr als eine Systemplattform zu kompilieren.Most Toolsets can be used to compile applications to more than one version of the .NET Framework and more than one system platform. Das Toolset MSBuild 2.0 kann allerdings nur für .NET Framework 2.0 verwendet werden.However, the MSBuild 2.0 Toolset can be used to target only the .NET Framework 2.0.

ToolsVersion-AttributToolsVersion attribute

Geben Sie das Toolset im Attribut ToolsVersion des Project-Elements in der Projektdatei an.Specify the Toolset in the ToolsVersion attribute on the Project element in the project file. Das folgende Beispiel gibt an, dass das Projekt mit dem MSBuild-Toolset „Current“ erstellt werden soll.The following example specifies that the project should be built by using the MSBuild "Current" Toolset.

<Project ToolsVersion="Current" ... </Project>

Geben Sie das Toolset im Attribut ToolsVersion des Project-Elements in der Projektdatei an.Specify the Toolset in the ToolsVersion attribute on the Project element in the project file. Das folgende Beispiel gibt an, dass das Projekt mit dem MSBuild 15.0-Toolset erstellt werden soll.The following example specifies that the project should be built by using the MSBuild 15.0 Toolset.

<Project ToolsVersion="15.0" ... </Project>

Note

Einige Projekttypen verwenden das sdk-Attribut anstelle von ToolsVersion.Some project types use the sdk attribute instead of ToolsVersion. Weitere Informationen finden Sie unter Pakete, Metapakete und Frameworks und Erweiterungen des CSPROJ-Formats für .NET Core.For more information, see Packages, metadata, and frameworks and Additions to the csproj format for .NET Core.

So funktioniert das ToolsVersion-AttributHow the ToolsVersion attribute works

Wenn Sie in Visual Studio ein Projekt erstellen oder ein vorhandenes Projekt aktualisieren, ist automatisch ein Attribut mit dem Namen ToolsVersion in der Projektdatei vorhanden, und sein Wert entspricht der Version von MSBuild, die in der Visual Studio-Edition enthalten ist.When you create a project in Visual Studio, or upgrade an existing project, an attribute named ToolsVersion is automatically included in the project file and its value corresponds to the version of MSBuild that is included in the Visual Studio edition. Weitere Informationen finden Sie unter Übersicht über Frameworkziele.For more information, see Framework targeting overview.

Wenn ein ToolsVersion-Wert in einer Projektdatei definiert wird, verwendet MSBuild diesen Wert, um die Werte der Toolseteigenschaften zu bestimmen, die für das Projekt verfügbar sind.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. Eine Toolseteigenschaft ist $(MSBuildToolsPath), die den Pfad der .NET Framework-Tools angibt.One Toolset property is $(MSBuildToolsPath), which specifies the path of the .NET Framework tools. Nur diese Toolseteigenschaft (oder $(MSBuildBinPath)) ist erforderlich.Only that Toolset property (or $(MSBuildBinPath)), is required.

Ab Visual Studio 2013 ist die Version des MSBuild-Toolsets die gleiche wie die Visual Studio-Versionsnummer.Starting in Visual Studio 2013, the MSBuild Toolset version is the same as the Visual Studio version number. MSBuild weist standardmäßig dieses Toolset in Visual Studio und in der Befehlszeile auf, unabhängig von der in der Projektdatei angegebenen Toolset-Version.MSBuild defaults to this Toolset within Visual Studio and on the command line, regardless of the Toolset version specified in the project file. Dieses Verhalten kann durch Verwendung des -ToolsVersion-Flags überschrieben werden.This behavior can be overridden by using the -ToolsVersion flag. Weitere Informationen erhalten Sie unter Überschreiben der ToolsVersion-Einstellungen.For more information, see Override ToolsVersion settings.

Im folgenden Beispiel findet MSBuild die Microsoft.CSharp.targets-Datei mithilfe der reservierten Eigenschaft MSBuildToolsPath.In the following example, MSBuild finds the Microsoft.CSharp.targets file by using the MSBuildToolsPath reserved property.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

Sie können den Wert von MSBuildToolsPath ändern, indem Sie ein benutzerdefiniertes Toolset definieren.You can modify the value of MSBuildToolsPath by defining a custom Toolset. Weitere Informationen finden Sie unter Standardmäßige und benutzerdefinierte Toolsetkonfigurationen.For more information, see Standard and custom Toolset configurations

Wenn Sie eine Lösung in der Befehlszeile erstellen und eine ToolsVersion für msbuild.exe angeben, werden alle Projekte und ihre projektübergreifenden Abhängigkeiten entsprechend dieser ToolsVersion erstellt, auch wenn jedes Projekt in der Lösung seine eigene ToolsVersion angibt.When you build a solution on the command line and specify a ToolsVersion for msbuild.exe, all projects and their project-to-project dependencies are built according to that ToolsVersion, even if each project in the solution specifies its own ToolsVersion. Informationen dazu, wie Sie den ToolsVersion-Wert projektweise definieren, finden Sie unter Überschreiben von ToolsVersion-Einstellungen.To define the ToolsVersion value on a per project basis, see Overriding ToolsVersion settings.

Das Attribut ToolsVersion wird auch für die Projektmigration verwendet.The ToolsVersion attribute is also used for project migration. Wenn Sie beispielsweise ein Visual Studio 2008-Projekt in Visual Studio 2010 öffnen, wird die Projektdatei so aktualisiert, dass die ToolsVersion="4.0" enthalten ist.For example, if you open a Visual Studio 2008 project in Visual Studio 2010, the project file is updated to include ToolsVersion="4.0". Wenn Sie anschließend versuchen, das Projekt in Visual Studio 2008 zu öffnen, erkennt es nicht die aktualisierte ToolsVersion und erstellt das Projekt daher so, als wäre das Attribut noch auf 3.5 festgelegt.If you then try to open that project in Visual Studio 2008, it doesn't recognize the upgraded ToolsVersion and therefore builds the project as though the attribute was still set to 3.5.

Visual Studio 2010 und Visual Studio 2012 verwenden beide die ToolsVersion 4.0.Visual Studio 2010 and Visual Studio 2012 use a ToolsVersion of 4.0. Visual Studio 2013 verwendet die ToolsVersion 12.0.Visual Studio 2013 uses a ToolsVersion of 12.0. Visual Studio 2015 verwendet ToolsVersion 14.0 und Visual Studio 2017 ToolsVersion 15.0.Visual Studio 2015 uses ToolsVersion 14.0, and Visual Studio 2017 uses ToolsVersion 15.0. In vielen Fällen können Sie das Projekt in mehreren Versionen von Visual Studio ohne Änderung öffnen.In many cases, you can open the project in multiple versions of Visual Studio without modification. Visual Studio verwendet immer das korrekte Toolset, Sie erhalten jedoch eine Benachrichtigung, wenn die verwendete Version nicht mit der Version in der Projektdatei übereinstimmt.Visual Studio always uses the correct Toolset, but you will be notified if the version used does not match the version in the project file. In fast allen Fällen hat diese Warnung keine Auswirkungen, da die Toolsets meistens kompatibel sind.In almost all cases, this warning is benign as the Toolsets are compatible in most cases.

Mithilfe von Unter-Toolsets, die weiter unten in diesem Thema beschrieben werden, kann MSBuild je nach Kontext, in dem der Build ausgeführt wird, automatisch zwischen den Toolsets wechseln.Sub-toolsets, which are described later in this topic, allow MSBuild to automatically switch which set of tools to use based on the context in which the build is being run. Beispielsweise verwendet MSBuild in Visual Studio 2012 automatisch ein neueres Toolset als in Visual Studio 2010, ohne dass die Projektdatei explizit geändert werden muss.For example, MSBuild uses a newer set of tools when it's run in Visual Studio 2012 than when it's run in Visual Studio 2010, without your having to explicitly change the project file.

ToolsetimplementierungToolset implementation

Sie implementieren ein Toolset, indem Sie die Pfade der verschiedenen Tools, Ziele und Aufgaben auswählen, die das Toolset ausmachen.Implement a Toolset by selecting the paths of the various tools, targets, and tasks that make up the Toolset. Die Tools im Toolset, das von MSBuild definiert wird, stammen aus den folgenden Quellen:The tools in the Toolset that MSBuild defines come from the following sources:

  • .NET Framework-OrdnerThe .NET Framework folder.

  • Zusätzliche verwaltete ToolsAdditional managed tools.

    Dazu zählen ResGen.exe und TlbImp.exe.The managed tools include ResGen.exe and TlbImp.exe.

MSBuild bietet zwei Möglichkeiten, auf das Toolset zuzugreifen:MSBuild provides two ways to access the Toolset:

In den Toolseteigenschaften sind die Pfade der Tools angegeben.Toolset properties specify the paths of the tools. Ab Visual Studio 2017 ist für MSBuild kein Speicherort mehr festgelegt.Starting in Visual Studio 2017, MSBuild no longer has a fixed location. Standardmäßig befindet sich MSBuild im Ordner MSBuild\15.0\Bin relativ zum Installationsort von Visual Studio.By default, it is located in the MSBuild\15.0\Bin folder relative to the Visual Studio installation location. In früheren Versionen verwendet MSBuild den Wert des ToolsVersion-Attributs in der Projektdatei, um den entsprechenden Registrierungsschlüssel zu suchen, und verwendet dann die Informationen im Registrierungsschlüssel, um die Toolseteigenschaften festzulegen.In earlier versions, MSBuild uses the value of the ToolsVersion attribute in the project file to locate the corresponding registry key, and then uses the information in the registry key to set the Toolset properties. Wenn ToolsVersion z. B. den Wert 12.0 hat, dann legt MSBuild die Toolseteigenschaften entsprechend diesem Registrierungsschlüssel fest: HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0.For example, if ToolsVersion has the value 12.0, then MSBuild sets the Toolset properties according to this registry key: HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0.

Dies sind die Toolseteigenschaften:These are Toolset properties:

  • MSBuildToolsPath gibt den Pfad der MSBuild-Binärdateien an.MSBuildToolsPath specifies the path of the MSBuild binaries.

  • SDK40ToolsPath gibt den Pfad der zusätzlichen verwalteten Tools für MSBuild 4.x (4.0 oder 4.5).SDK40ToolsPath specifies the path of additional managed tools for MSBuild 4.x (which could be 4.0 or 4.5).

  • SDK35ToolsPath gibt den Pfad der zusätzlichen verwalteten Tools für MSBuild 3,5 an.SDK35ToolsPath specifies the path of additional managed tools for MSBuild 3.5.

Alternativ können Sie die Toolsets programmgesteuert bestimmen, indem Sie die Methoden der ToolLocationHelper-Klasse aufrufen.Alternately, you can determine the Toolset programmatically by calling the methods of the ToolLocationHelper class. Die Klasse beinhaltet diese Methoden:The class includes these methods:

Unter-ToolsetsSub-toolsets

In MSBuild-Versionen für Version 15.0 verwendet MSBuild einen Registrierungsschlüssel, um den Pfad der grundlegenden Tools anzugeben.For versions MSBuild prior to 15.0, MSBuild uses a registry key to specify the path of the basic tools. Wenn der Schlüssel einen Unterschlüssel hat, verwendet MSBuild ihn, um den Pfad eines Unter-Toolsets anzugeben, das zusätzliche Tools enthält.If the key has a subkey, MSBuild uses it to specify the path of a sub-toolset that contains additional tools. In diesem Fall wird das Toolset definiert, indem die in beiden Schlüsseln definierten Eigenschaftendefinitionen kombiniert werden.In this case, the Toolset is defined by combining the property definitions that are defined in both keys.

Note

Wenn bei Toolseteigenschaftennamen Konflikte auftreten, überschreibt der Wert, der für den Unterschlüsselpfad definiert ist, den Wert, der für den Stammschlüsselpfad definiert ist.If Toolset property names collide, the value that's defined for the subkey path overrides the value that's defined for the root key path.

Unter-Toolsets werden bei Vorhandensein der Buildeigenschaft VisualStudioVersion aktiv.Sub-toolsets become active in the presence of the VisualStudioVersion build property. Diese Eigenschaft verwendet einen der folgenden Werte:This property may take one of these values:

  • "10.0" specifies the .NET Framework 4 sub-toolset"10.0" specifies the .NET Framework 4 sub-toolset

  • "11.0" specifies the .NET Framework 4.5 sub-toolset"11.0" specifies the .NET Framework 4.5 sub-toolset

  • "12.0" specifies the .NET Framework 4.5.1 sub-toolset"12.0" specifies the .NET Framework 4.5.1 sub-toolset

Die Unter-Toolsets 10.0 und 11.0 sollten mit der ToolsVersion 4.0 verwendet werden.Sub-toolsets 10.0 and 11.0 should be used with ToolsVersion 4.0. In späteren Versionen sollten die Version der Unter-Toolsets und die ToolsVersion übereinstimmen.In later versions, the sub-toolset version and the ToolsVersion should match.

Während eines Builds ermittelt MSBuild automatisch den Wert für die Eigenschaft VisualStudioVersion und legt einen Standardwert fest, wenn er noch nicht definiert ist.During a build, MSBuild automatically determines and sets a default value for the VisualStudioVersion property if it's not already defined.

MSBuild stellt Überladungen für die ToolLocationHelper-Methoden bereit, die einen VisualStudioVersion-Enumerationswert als Parameter hinzufügen.MSBuild provides overloads for the ToolLocationHelper methods that add a VisualStudioVersion enumerated value as a parameter

Unter-Toolsets wurden in .NET Framework 4.5 eingeführt.Sub-toolsets were introduced in the .NET Framework 4.5.

Siehe auchSee also