MSBuild-Toolset (ToolsVersion)

  • Artikel

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:

Zugehöriger Inhalt