Konfigurieren von Zielen und Aufgaben

Ausgewählte MSBuild-Aufgaben können so festgelegt werden, dass sie in der Umgebung ausgeführt werden, auf die sie abzielen, wenn der Entwicklungscomputer die Zielumgebung unterstützt. Wenn Sie beispielsweise einen 64-Bit-Windows-Computer verwenden, um eine Anwendung zu erstellen, die auf eine 32-Bit-Windows-Architektur ausgerichtet ist, werden ausgewählte Aufgaben in einem 32-Bit-Prozess ausgeführt.

Verwenden vonTask-Attributen und Vorgangsparametern

Die folgenden UsingTask Attribute wirken sich auf alle Vorgänge einer Aufgabe in einem bestimmten Buildprozess aus:

• Wenn Runtime vorhanden, legt das Attribut die ClR-Version (Common Language Runtime) fest und kann einen der folgenden Werte annehmen: CLR2, , CLR4, , CurrentRuntime( NET ab .NET SDK 10/Visual Studio 2026/MSBuild 18.0) oder * (beliebige Laufzeit).

• Wenn Architecture vorhanden, legt das Attribut die Plattform und Bitanzahl fest und kann einen der folgenden Werte annehmen: x86, , , x64, CurrentArchitectureoder * (eine beliebige Architektur).

• Wenn TaskFactory vorhanden, legt das Attribut die Taskfactory fest, die die Aufgabeninstanz erstellt und ausführt, und verwendet nur den Wert TaskHostFactory. Weitere Informationen finden Sie später in diesem Dokument unter Task factories.

<UsingTask TaskName="SimpleTask"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" />

Sie können auch die MSBuildRuntime- und MSBuildArchitecture-Parameter verwenden, um den Zielkontext eines einzelnen Taskaufrufs festzulegen.

<Project>
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Bevor MSBuild eine Aufgabe ausführt, sucht es nach einer Entsprechung UsingTask mit demselben Zielkontext. Parameter, die in der UsingTask , aber nicht im entsprechenden Vorgang angegeben sind, werden als übereinstimmend betrachtet. Parameter, die in der Aufgabe angegeben, jedoch nicht im entsprechenden UsingTask sind, werden ebenfalls als übereinstimmend betrachtet. Wenn Parameterwerte weder im UsingTask noch in der Aufgabe angegeben werden, werden die Werte standardmäßig auf * festgelegt (jeder beliebige Parameter).

Wenn Parameter für die Aufgabe festgelegt werden, versucht MSBuild, eine Aufgabe zu finden, die mit diesen Parametern übereinstimmt oder zumindest nicht in Konflikt mit ihnen steht. UsingTask Mehrere können den Zielkontext derselben Aufgabe angeben. Eine Aufgabe mit unterschiedlichen ausführbaren Dateien für unterschiedliche Zielumgebungen kann z. B. wie folgt aussehen:

<UsingTask TaskName="MyTool"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.v2.0.dll" />

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

<Project>
    <Target Name="MyTarget">
        <MyTool MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Überschreiben der Standardeinstellung für UsingTasks

Standardmäßig behandelt MSBuild das UsingTask-Element nach dem Prinzip "das erste gewinnt". Ab 17.2 unterstützt MSBuild Änderungen dieses Verhaltens mit dem Override Parameter. Eine UsingTask mit dem Parameter Override auf true gesetzt hat Vorrang vor allen anderen UsingTasks mit demselben TaskName.

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    Override="true"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

Aufgabenfabriken

In der folgenden Tabelle sind die Aufgabenfabriken aufgeführt, die von der MSBuild-Installation bereitgestellt werden:

Der Vorgangs-Factory-Mechanismus ist erweiterbar, sodass Sie auch von Drittanbietern erstellte Funktionen verwenden oder eigene erstellen können. Ein Grund für die Erstellung einer Datei wäre die Unterstützung einer anderen Sprache für das Schreiben von Inlineaufgaben.

TaskHostFactory

Bevor eine Aufgabe ausgeführt wird, überprüft MSBuild, ob sie im aktuellen Softwarekontext ausgeführt werden soll. Wenn die Aufgabe so festgelegt ist, übergibt MSBuild sie an den AssemblyTaskFactory, der sie im aktuellen Prozess ausführt. Andernfalls übergibt MSBuild die Aufgabe an den TaskHostFactory, der die Aufgabe in einem Prozess ausführt, der dem Zielkontext entspricht. Auch wenn der aktuelle Kontext und der Zielkontext übereinstimmen, können Sie erzwingen, dass eine Aufgabe aus Gründen der Isolation, Sicherheit oder anderen Gründen außerhalb des Prozesses ausgeführt wird, indem Sie TaskFactory auf TaskHostFactory setzen.

<UsingTask TaskName="MisbehavingTask"
    TaskFactory="TaskHostFactory"
    AssemblyFile="$(MSBuildToolsPath)\MyTasks.dll">
</UsingTask>

Wenn TaskHostFactory explizit angegeben wird, ist der Prozess, der die Aufgabe ausführt, kurzlebig. Auf diese Weise kann das Betriebssystem alle Ressourcen im Zusammenhang mit dem Vorgang unmittelbar nach der Ausführung bereinigen. Deshalb sollten Sie TaskHostFactory angeben, wenn Sie auf Aufgaben verweisen, die im selben Buildprozess erstellt wurden, in dem sie verwendet werden, um Fehler 'Datei in Verwendung' beim Aktualisieren der Aufgabenassembly nach dem Build zu vermeiden.

RoslynCodeTaskFactory

Dies RoslynCodeTaskFactory stellt einen Mechanismus bereit, mit dem Sie C#- oder Visual Basic-Code für einen Vorgang in einer Projektdatei zur sofortigen Verwendung schreiben können. Der Code wird während des Buildprozesses kompiliert, um eine Aufgabe zu erzeugen, die Sie in diesem Build ausführen können. Der Code, den Sie schreiben, zielt auf .NET Standard ab, sodass er bei der Ausführung dotnet buildverwendet werden kann, die die .NET Core-Version (und .NET 5 und höher) von MSBuild sowie msbuild.exedas .NET Framework verwendet. RoslynCodeTaskFactory eignet sich am besten für Anpassungen, die in der MSBuild-Logik nur ein bisschen zu schwer zu erledigen sind, aber nicht komplex genug, um ein separates Projekt zu erstellen. Siehe Erstellen einer MSBuild-Inlineaufgabe mit RoslynCodeTaskFactory.

CodeTaskFactory

CodeTaskFactory ist eine ältere Version von RoslynCodeTaskFactory, die auf die .NET Framework-Version von MSBuild beschränkt ist. Siehe MSBuild-Inlineaufgaben. Diese Task-Factory wird unterstützt, aber neuerer Code sollte RoslynCodeTaskFactory für eine breitere Anwendbarkeit verwenden.

TaskHosts in MSBuild

MSBuild führt Aufgaben als Teil des Buildprozesses aus, und manchmal müssen diese Aufgaben in einem anderen Laufzeit- oder Architekturkontext als der Standardbuildprozess ausgeführt werden. Um dies zu unterstützen, kann MSBuild einen "TaskHost" verwenden – einen separaten MSBuild-Prozess, der für die Ausführung von Aufgaben unter der angeforderten Umgebung verantwortlich ist. TaskHosts stellen Isolation, Kompatibilität und Unterstützung für die Zielbestimmung verschiedener Frameworks oder Plattformen sicher.

In der Vergangenheit haben TaskHosts Aufgaben aktiviert, die in separaten .NET Framework-Prozessen bestimmter Versionen ausgeführt werden (z. B. CLR2 oder CLR4). Diese Unterstützung wurde von den Runtime und Architecture Attributen des <UsingTask> Elements in der Projektdatei oder Zieldatei gesteuert.

• Architecture kann Werte wie x86, x64, , CurrentArchitectureoder * für "beliebige Architektur" angeben.
• Runtime kann Werte wie CLR2, CLR4, und (kürzlich) NET oder CurrentRuntime.

Für die meisten MSBuild-Aufgaben reicht der Standardprozess aus. Für benutzerdefinierte oder komplexere Aufgaben – insbesondere bei plattformspezifischen Abhängigkeiten – entsperrt TaskHosts jedoch Kompatibilität und Flexibilität, indem eine geeignete Laufzeit automatisch gestartet wird.

Verwenden von .NET TaskHost

Mit der Freigabe des .NET 10 SDK und von Visual Studio 2026 hat MSBuild Unterstützung für eine .NET TaskHost eingeführt. Mit diesem Feature kann MSBuild Aufgaben ausführen, die eine .NET-Laufzeit für einen separaten .NET-Prozess verwenden müssen. Dies wird über das Runtime="NET" Attribut im <UsingTask> Element aktiviert:

<UsingTask TaskName="MyNetTask"
           Runtime="NET"
           AssemblyFile="path\to\task.dll" />

Wenn dieses Attribut festgelegt ist:

• MSBuild verwaltet automatisch einen Pool des .NET TaskHost-Prozesses und führt die angegebene Aufgabe auf einem Knoten in diesem Pool aus.
• Aufgaben können die exklusiv für moderne .NET-Runtimes verfügbaren APIs oder Bibliotheken nutzen.
• Isolation schützt den Buildprozess vor Abhängigkeits- oder Versionskonflikten.

Der Versuch, das .NET TaskHost-Feature mit einem .NET SDK zu verwenden, bevor 10.0.100 ausgeführt wird, führt zu Fehlern für Ihre Benutzer beim Erstellen. Um dies zu verhindern, können Sie eine Versionsüberprüfung durchführen, um festzustellen, ob das Feature sicher zu verwenden ist. Hier verwenden wir eine Vergleichsfunktion für MSBuild-Eigenschaften, um zu prüfen, ob der aktuelle Build in einer Version 10.0.100 oder höher erfolgt. Ist dies der Fall, wird die NET Runtime verwendet. Andernfalls, wenn wir unterhalb der SDK-Version 10.0.100 sind und auf der .NET Framework-Version von MSBuild ausgeführt werden, verwenden wir stattdessen eine .NET Framework-Taskimplementation.

<UsingTask .... AssemblyFile="my/netcore/tasks.dll" Runtime="NET" Condition="$([MSBuild]::VersionGreaterThanOrEquals('$(SdkAnalysisLevel)', '10.0.100'))" />
<UsingTask .... AssemblyFile="my/netframework/tasks.dll" Condition="!$([MSBuild]::VersionGreaterThanOrEquals('$(SdkAnalysisLevel)', '10.0.100')) and $(MSBuildRuntimeType) == 'Full' " />

Warum .NET TaskHost verwenden?

• Zugriff auf moderne .NET-APIs: .NET TaskHost ermöglicht Aufgaben die Verwendung von Features und Bibliotheken, die nur in den letzten .NET-Versionen verfügbar sind.
• Verbesserte Kompatibilität: Das Trennen der Aufgabenausführung kann Versionsverwaltungs- und Abhängigkeitskonflikte vermeiden.
• Zukünftige Dokumentprüfung: Wir beabsichtigen, die TaskHost-Unterstützung weiter zu erweitern und SDK/Resolver-Logik zu vereinheitlichen (siehe dotnet/msbuild#12895 für laufende Arbeiten).

Phantomaufgabenparameter

Wie alle anderen Vorgangsparameter können MSBuildRuntime und MSBuildArchitecture aus den Buildeigenschaften festgelegt werden.

<Project>
    <PropertyGroup>
        <FrameworkVersion>3.0</FrameworkVersion>
    </PropertyGroup>
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="$(FrameworkVerion)" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Im Gegensatz zu anderen Aufgabenparametern sind MSBuildRuntime und MSBuildArchitecture der Aufgabe selbst nicht sichtbar. Um eine Aufgabe zu schreiben, die den Kontext kennt, in dem sie ausgeführt wird, müssen Sie entweder den Kontext testen, indem Sie das .NET Framework aufrufen, oder Buildeigenschaften verwenden, um die Kontextinformationen über andere Aufgabenparameter zu übergeben.

Die Parameter MSBuildRuntime und MSBuildArchitecture bieten die flexibelste Möglichkeit zum Festlegen des Zielkontexts, aber ihr Anwendungsbereich ist auch am begrenztesten. Da sie einerseits für die Aufgabeninstanz selbst festgelegt sind und erst ausgewertet werden, wenn die Aufgabe ausgeführt werden soll, können sie ihren Wert vom vollständigen Umfang der Eigenschaften ableiten, die sowohl zur Auswertungszeit als auch zur Buildzeit verfügbar sind. Andererseits gelten diese Parameter nur für eine bestimmte Instanz eines Vorgangs in einem bestimmten Ziel.

Verwandte Inhalte

• Konfigurieren von Zielen und Aufgaben
• UsingTask-Element