MSBuild-Toolset (ToolsVersion)
Ein MSBuild-Toolset umfasst eine Datei mit allgemeinen Aufgaben (microsoft.common.tasks), eine Datei mit allgemeinen Zielen (microsoft.common.targets) und Compiler wie csc.exe und vbc.exe. Die meisten Toolsets können verwendet werden, um Anwendungen für mehrere Versionen von .NET Framework und mehrere Systemplattformen zu kompilieren. Das Toolset MSBuild 2.0 kann allerdings nur für .NET Framework 2.0 verwendet werden.
Das MSBuild-Attribut ToolsVersion
für das Project-Element in Visual Studio und MSBuild-Projektdateien gilt in Visual Studio 2019 und höher als veraltet. Sie können es sicher löschen. In diesem Artikel wird die Verwendung in älteren Versionen von MSBuild oder für benutzerdefinierte Toolsets beschrieben. Weitere Informationen finden Sie unter Standardmäßige und benutzerdefinierte Toolsetkonfigurationen.
ToolsVersion-Attribut
Geben Sie das Toolset im Attribut ToolsVersion
des Project-Elements in der Projektdatei an. Das folgende Beispiel gibt an, dass das Projekt mit dem MSBuild-Toolset „Current“ erstellt werden soll.
<Project ToolsVersion="Current" ... </Project>
Hinweis
Einige Projekttypen verwenden das sdk
-Attribut anstelle von ToolsVersion
. Weitere Informationen finden Sie unter Erweiterungen des CSPROJ-Formats für .NET Core.
So funktioniert das ToolsVersion-Attribut
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. Weitere Informationen finden Sie unter Übersicht über Frameworkziele.
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. Eine Toolseteigenschaft ist $(MSBuildToolsPath)
, die den Pfad der .NET Framework-Tools angibt. Nur diese Toolseteigenschaft (oder $(MSBuildBinPath)
) ist erforderlich.
Ab Visual Studio 2013 ist die Version des MSBuild-Toolsets die gleiche wie die Visual Studio-Versionsnummer. MSBuild weist standardmäßig dieses Toolset in Visual Studio und in der Befehlszeile auf, unabhängig von der in der Projektdatei angegebenen Toolset-Version. Dieses Verhalten kann durch Verwendung des -ToolsVersion-Flags überschrieben werden. Weitere Informationen erhalten Sie unter Überschreiben der ToolsVersion-Einstellungen.
Im folgenden Beispiel findet MSBuild die Microsoft.CSharp.targets-Datei mithilfe der reservierten Eigenschaft MSBuildToolsPath
.
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
Sie können den Wert von MSBuildToolsPath
ändern, indem Sie ein benutzerdefiniertes Toolset definieren. Weitere Informationen finden Sie unter Standardmäßige und benutzerdefinierte Toolsetkonfigurationen.
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. Informationen dazu, wie Sie den ToolsVersion
-Wert projektweise definieren, finden Sie unter Überschreiben von ToolsVersion-Einstellungen.
Das Attribut ToolsVersion
wird auch für die Projektmigration verwendet. 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. 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.
Visual Studio 2010 und Visual Studio 2012 verwenden beide die ToolsVersion 4.0. Visual Studio 2013 verwendet die ToolsVersion 12.0. Visual Studio 2015 verwendet ToolsVersion 14.0 und Visual Studio 2017 ToolsVersion 15.0. In vielen Fällen können Sie das Projekt in mehreren Versionen von Visual Studio ohne Änderung öffnen. Visual Studio verwendet immer das korrekte Toolset, Sie erhalten jedoch eine Benachrichtigung, wenn die verwendete Version nicht mit der Version in der Projektdatei übereinstimmt. In fast allen Fällen hat diese Warnung keine Auswirkungen, da die Toolsets meistens kompatibel sind.
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. 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.
Toolsetimplementierung
Sie implementieren ein Toolset, indem Sie die Pfade der verschiedenen Tools, Ziele und Aufgaben auswählen, die das Toolset ausmachen. Die Tools im Toolset, das von MSBuild definiert wird, stammen aus den folgenden Quellen:
.NET Framework-Ordner
Zusätzliche verwaltete Tools
Dazu zählen ResGen.exe und TlbImp.exe.
MSBuild bietet zwei Möglichkeiten, auf das Toolset zuzugreifen:
Durch Verwendung von Toolseteigenschaften
Durch Verwendung von ToolLocationHelper-Methoden
In den Toolseteigenschaften sind die Pfade der Tools angegeben. Ab Visual Studio 2017 ist für MSBuild kein Speicherort mehr festgelegt. Standardmäßig befindet sich MSBuild im Ordner MSBuild\15.0\Bin relativ zum Installationsort von Visual Studio. 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. 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.
Dies sind die Toolseteigenschaften:
MSBuildToolsPath
gibt den Pfad der MSBuild-Binärdateien an.SDK40ToolsPath
gibt den Pfad der zusätzlichen verwalteten Tools für MSBuild 4.x (4.0 oder 4.5).SDK35ToolsPath
gibt den Pfad der zusätzlichen verwalteten Tools für MSBuild 3,5 an.
Alternativ können Sie die Toolsets programmgesteuert bestimmen, indem Sie die Methoden der ToolLocationHelper-Klasse aufrufen. Die Klasse beinhaltet diese Methoden:
GetPathToDotNetFramework gibt den Pfad des .NET Framework-Ordners zurück.
GetPathToDotNetFrameworkFile gibt den Pfad einer Datei im .NET Framework-Ordner zurück.
GetPathToDotNetFrameworkSdk gibt den Pfad des Ordners der verwalteten Tools zurück.
GetPathToDotNetFrameworkSdkFile gibt den Pfad einer Datei zurück, die sich in der Regel im Ordner mit verwalteten Tools befindet.
GetPathToBuildTools gibt den Pfad der Build-Tools zurück.