Teilen über

Konfigurieren von Zielen und Aufgaben

  • Artikel

Ausgewählte MSBuild-Aufgaben können so festgelegt werden, dass sie in der Zielumgebung ausgeführt werden, 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 abzielt, werden ausgewählte Aufgaben in einem 32-Bit-Prozess ausgeführt.

Hinweis

Wenn eine Buildaufgabe in einer .NET-Sprache wie z.B. Visual C# oder Visual Basic geschrieben ist und keine nativen Ressourcen oder Tools verwendet, wird sie in jedem Zielkontext ohne Anpassung ausgeführt.

UsingTask-Attribute und Aufgabenparameter

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

  • Das Runtime-Attribut, sofern vorhanden, legt die Version der Common Language Runtime (CLR) fest, und kann einen der folgenden Werte annehmen: CLR2, CLR4, CurrentRuntime oder * (beliebige Runtime).

  • Das Architecture-Attribut, sofern vorhanden, legt Plattform und Bitanzahl fest und kann einen der folgenden Werte annehmen: x86, x64, CurrentArchitecture oder * (beliebige Architektur).

  • Das TaskFactory-Attribut, sofern vorhanden, legt die Aufgabenfactory fest, die die Aufgabeninstanz erstellt und ausführt, und nimmt nur den Wert TaskHostFactory an. Weitere Informationen finden Sie im Abschnitt Aufgabenfactorys weiter unten in diesem Artikel.

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

Sie können auch mit den Parametern MSBuildRuntime und MSBuildArchitecture den Zielkontext eines einzelnen Aufgabenaufrufs festlegen.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Bevor MSBuild eine Aufgabe ausführt, wird nach einer übereinstimmenden UsingTask mit gleichem Zielkontext gesucht. In der UsingTask, jedoch nicht in der entsprechenden Aufgabe angegebene Parameter werden als übereinstimmend betrachtet. In der Aufgabe, jedoch nicht in der entsprechenden UsingTask angegebene Parameter werden auch als übereinstimmend betrachtet. Wenn Parameterwerte weder in der UsingTask noch in der Aufgabe angegeben sind, sind die Werte standardmäßig * (beliebiger Parameter).

Warnung

Wenn mehr als eine UsingTask vorhanden ist und alle übereinstimmende TaskName-, Runtime- und Architecture-Attribute haben, ersetzt die zuerst ausgewertete die anderen. Dieses Verhalten unterscheidet sich von dem der Elemente Property und Target.

Wenn Parameter für die Aufgabe festgelegt sind, versucht MSBuild, eine UsingTask zu finden, die mit diesen Parametern übereinstimmt oder zumindest nicht in Konflikt mit ihnen steht. Mehr als eine UsingTask können den Zielkontext der gleichen Aufgabe angeben. Beispielsweise könnte eine Aufgabe mit verschiedenen ausführbaren Dateien für unterschiedliche Zielumgebungen dieser ähneln:

<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 xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <MyTool MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Außerkraftsetzung von UsingTasks-Standardelementen

Generell werden UsingTask-Elemente von MSBuild mit dem Motto „der Erste gewinnt“ behandelt. Am Version 17.2 unterstützt MSBuild die Außerkraftsetzung dieses Verhaltens mithilfe des Override-Parameters. Ein UsingTask-Element mit dem Parameter Override, der auf true festgelegt ist, hat Priorität gegenüber anderen UsingTask-Elementen mit demselben TaskName.

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

Warnung

Dieser Schritt kann nur einmal pro Aufgabe ausgeführt werden. Für Builds, die versuchen, mehrere Außerkraftsetzungen für denselben Vorgang hinzuzufügen, wird der MSBuild-Fehler MSB4275 ausgelöst.

Aufgabenfactorys

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

Aufgabenfactory Beschreibung
AssemblyTaskFactory Dies ist der Standardwert. Führt die Aufgabe im Prozess aus.
TaskHostFactory Führt die Aufgabe außerhalb des Prozesses aus.
RoslynCodeTaskFactory Für Inlineaufgaben, die in C# oder Visual Basic erstellt wurden und auf .NET Standard ausgerichtet sind; funktioniert mit msbuild.exe und mit dotnet build.
CodeTaskFactory Für Inlineaufgaben, die in C# oder Visual Basic erstellt wurden und auf .NET Framework ausgerichtet sind; funktioniert nur mit msbuild.exe.

Der Aufgabenfactory-Mechanismus ist erweiterbar, sodass Sie auch von Dritten erstellte Aufgabenfactorys verwenden oder eigene erstellen können. Ein Grund für die Erstellung einer Factory 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 zur Ausführung im aktuellen Softwarekontext bestimmt ist. Wenn die Aufgabe hierfür bestimmt ist, übergibt MSBuild sie an die AssemblyTaskFactory, die sie im aktuellen Prozess ausführt; andernfalls übergibt MSBuild die Aufgabe an die TaskHostFactory, welche die Aufgabe in einem Prozess ausführt, der dem Zielkontext entspricht. Auch wenn aktueller Kontext und Zielkontext übereinstimmen, können Sie durch Festlegen von TaskFactory auf TaskHostFactory erzwingen, dass eine Aufgabe prozessextern ausgeführt wird (zur Isolation, zur Sicherheit oder aus anderen Gründen).

<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. Geben Sie aus diesem Grund TaskHostFactory an, wenn auf Aufgaben verwiesen wird, die im selben Buildprozess wie deren Verwendung erstellt wurden, um Fehler in aktuell verwendeten Dateien beim Aktualisieren der Aufgabenassembly nach einem Build zu vermeiden.

RoslynCodeTaskFactory

Die RoslynCodeTaskFactory stellt einen Mechanismus bereit, mit dem Sie C#- oder Visual Basic-Code für eine Aufgabe in einer Projektdatei zur umgehenden Nutzung schreiben können. Der Code wird beim Buildprozess kompiliert, um eine Aufgabe zu generieren, die Sie im betreffenden Build ausführen können. Der geschriebene Code ist auf .NET Standard ausgerichtet, sodass er bei der Ausführung von dotnet build verwendet werden kann, der die .NET Core-Version (sowie .NET 5 und höher) von MSBuild verwendet, sowie bei der Ausführung von msbuild.exe, der .NET Framework nutzt. RoslynCodeTaskFactory eignet sich am besten für Anpassungen, die in der MSBuild-Logik nur schwer umsetzbar sind, aber nicht komplex genug sind, um ein eigenes 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 Aufgabenfactory wird unterstützt, aber bei neuerem Code sollte für eine umfassendere Anwendbarkeit RoslynCodeTaskFactory verwendet werden.

Phantomaufgabenparameter

Wie alle anderen Aufgabenparameter können MSBuildRuntime und MSBuildArchitecture über die Buildeigenschaften festgelegt werden .

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <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 für die Aufgabe selbst nicht ersichtlich. Um eine Aufgabe zu schreiben, die sich des Kontexts bewusst ist, in dem sie ausgeführt wird, müssen Sie entweder den Kontext durch Aufrufen von .NET Framework testen oder Buildeigenschaften verwenden, um die Kontextinformationen über andere Aufgabenparameter zu übergeben.

Hinweis

UsingTask-Attribute können aus Toolset und Umgebungseigenschaften festgelegt werden.

Die Parameter MSBuildRuntime und MSBuildArchitecture bieten die flexibelste Möglichkeit, um den Zielkontext festzulegen, zugleich ist der Umfang aber am stärksten begrenzt. Einerseits können sie ihren Wert aus dem vollen Umfang an Eigenschaften ableiten, die zur Auswertungs- und Buildzeit verfügbar sind, da sie auf der Aufgabeninstanz selbst festgelegt werden und nicht ausgewertet werden, bis die Aufgabe ausgeführt wird. Andererseits gelten diese Parameter nur für eine bestimmte Instanz einer Aufgabe in einem bestimmten Ziel.

Hinweis

Aufgabenparameter werden im Kontext des übergeordneten Knotens ausgewertet, nicht im Kontext des Aufgabenhosts. Umgebungsvariablen, die von der Laufzeit oder Architektur abhängen (wie der Speicherort der Programme) ergeben bei der Auswertung den Wert, der dem übergeordneten Knoten entspricht. Wenn dieselbe Umgebungsvariable jedoch direkt von der Aufgabe gelesen wird, wird sie ordnungsgemäß im Kontext des Aufgabenhosts ausgewertet.

Zugehöriger Inhalt