MSBuild-Aufgabe

Erstellt MSBuild-Projekte aus einem anderen MSBuild-Projekt.

Parameter

In der folgenden Tabelle werden die Parameter der MSBuild-Aufgabe beschrieben.

Parameter	Beschreibungen
BuildInParallel	Optionaler Boolean-Parameter. Bei true werden die im Projects-Parameter angegebenen Projekte nach Möglichkeit parallel erstellt. Der Standardwert ist false.
Projects	Erforderlicher ITaskItem[]-Parameter. Gibt die Projektdateien an, die erstellt werden sollen.
Properties	Optionaler String-Parameter. Eine durch Semikolons getrennte Liste der Eigenschaftenname-Wert-Paare, die als globale Eigenschaften auf das untergeordnete Projekt angewendet sollen. Die Angabe dieses Parameters entspricht funktional dem Festlegen von Eigenschaften mit dem /property-Schalter beim Erstellen mit MSBuild.exe. Beispiele: Properties="Configuration=Debug;Optimize=$(Optimize)" Wenn Eigenschaften über den Properties-Parameter an das Projekt übergeben werden, erstellt MSBuild eine neue Instanz des Projekts, selbst wenn die Projektdatei schon geladen wurde. Nach der Erstellung einer neuen Instanz des Projekts wird es von MSBuild als anderes Projekt mit anderen globalen Eigenschaften behandelt, das parallel mit anderen Instanzen des Projekts erstellt werden kann. Beispielsweise könnte eine Releasekonfiguration gleichzeitig mit einer Debugkonfiguration erstellt werden.
RebaseOutputs	Optionaler Boolean-Parameter. Wenn der Wert true lautet, werden die relativen Pfade von Zielausgabeelementen aus den erstellten Projekten so angepasst, dass sie sich auf das aufrufende Projekt beziehen. Der Standardwert ist false.
RemoveProperties	Optionaler String-Parameter. Gibt den Satz zu entfernender globaler Eigenschaften an.
RunEachTargetSeparately	Optionaler Boolean-Parameter. Bei true werden die Ziele in der Liste von der MSBuild-Aufgabe einzeln und nicht gleichzeitig an MSBuild übergeben. Durch das Festlegen dieses Parameters auf true wird garantiert, dass nachfolgende Ziele aufgerufen werden, auch wenn bei vorher aufgerufenen Zielen ein Fehler aufgetreten ist. Andernfalls würde ein Buildfehler den Aufruf aller nachfolgenden Ziele beenden. Der Standardwert ist false.
SkipNonexistentProjects	Optionaler Boolean-Parameter. Beim Wert true werden auf dem Datenträger nicht vorhandene Projektdateien übersprungen. Andernfalls werden solche Projekte einen Fehler verursachen.
StopOnFirstFailure	Optionaler Boolean-Parameter. Falls true, wenn eines der Projekte nicht erstellt werden kann, werden keine weiteren Projekte erstellt. Derzeit wird dies bei paralleler Erstellung (mit mehreren Prozessoren) nicht unterstützt.
TargetAndPropertyListSeparators	Optionaler String[]-Parameter. Gibt eine Liste der Ziele und Eigenschaften als Project-Elementmetadaten an.) Bei Separatoren werden Escapezeichen vor der Verarbeitung entfernt. z. B. %3B (';' mit Escapezeichen) wird behandelt, als wäre es ein ';' ohne Escapezeichen.
TargetOutputs	Optionaler schreibgeschützter ITaskItem[]-Ausgabeparameter. Gibt die Ausgaben der erstellten Ziele von allen Projektdateien zurück. Es werden nur die Ausgaben der angegebenen Ziele zurückgegeben, jedoch keine Ausgaben, die möglicherweise für Ziele vorhanden sind, von denen diese Ziele abhängen. Der TargetOutputs-Parameter enthält außerdem die folgenden Metadaten: MSBuildSourceProjectFile: Die MSBuild-Projektdatei, die das Ziel enthält, das die Ausgaben festgelegt hat. MSBuildSourceTargetName: Das Ziel, das die Ausgaben festgelegt hat. Hinweis Wenn Sie die Ausgaben für jede Projektdatei oder jedes Ziel separat ermitteln möchten, führen Sie die MSBuild-Aufgabe für jede Projektdatei bzw. jedes Ziel separat aus.Wenn Sie die MSBuild-Aufgabe nur einmal ausführen, um alle Projektdateien zu erstellen, werden die Ausgaben aller Ziele in einem Array zusammengefasst.
Targets	Optionaler String-Parameter. Gibt das Ziel oder die Ziele für die Erstellung der Projektdateien an. Trennen Sie mehrere Zielnamen in der Liste durch Semikolons voneinander. Wenn in der MSBuild-Aufgabe keine Ziele angegeben sind, werden die in den Projektdateien angegebenen Standardziele erstellt. Hinweis Die Ziele müssen in allen Projektdateien vorhanden sein.Andernfalls tritt ein Buildfehler auf.
ToolsVersion	Optionaler String-Parameter. Gibt die ToolsVersion an, die beim Erstellen von Projekten an diese Aufgabe übergeben wird. Ermöglicht einer MSBuild-Aufgabe das Erstellen eines Projekts für eine andere als die im Projekt angegebene Version von .NET Framework. Gültige Werte sind 2.0, 3.0 und 3.5. Der Standardwert ist 3.5.
UnloadProjectsOnCompletion	Optionaler Boolean-Parameter. Beim Wert true wird das Projekt nach Abschluss des Vorgangs entladen.
UseResultsCache	Optionaler Boolean-Parameter. Bei true wird das zwischengespeicherte Ergebnis, wenn vorhanden, zurückgegeben. Wenn die MSBuild-Aufgabe ausgeführt wird, wird das Ergebnis in einem Bereich (ProjectFileName, GlobalProperties)[TargetNames] zwischengespeichert werden als Liste von Build-Elementen

Hinweise

Zusätzlich zu den oben aufgeführten Parametern erbt diese Aufgabe Parameter von der TaskExtension-Klasse, die selbst von der Task-Klasse erbt. Eine Liste mit diesen zusätzlichen Parametern und ihren Beschreibungen finden Sie unter TaskExtension-Basisklasse.

Anders als beim Aufrufen von MSBuild.exe über die Exec-Aufgabe wird bei dieser Aufgabe derselbe MSBuild-Prozess verwendet, um die untergeordneten Projekte zu erstellen. Die Liste mit bereits erstellten Zielen, die übersprungen werden können, wird von übergeordneten und untergeordneten Builds gemeinsam genutzt. Diese Aufgabe nimmt außerdem weniger Zeit in Anspruch, da kein neuer MSBuild-Prozess erstellt wird.

Diese Aufgabe kann nicht nur Projektdateien verarbeiten, sondern auch Projektmappendateien.

Alle Konfigurationen, die von MSBuild zum gleichzeitigen Erstellen von Projekten benötigt werden, müssen mithilfe einer Konfigurationsdatei konfigurierbar gemacht werden, auch wenn eine Konfiguration Remoteinfrastruktur (z. B. Ports, Protokolle, Timeouts, Wiederholungen usw.) umfasst. Nach Möglichkeit sollten Konfigurationselemente in der MSBuild-Aufgabe als Aufgabenparameter angegeben werden.

Ab MSBuild 3.5 bringen Projektmappenprojekte TargetOutputs aus allen hiermit erstellten Unterprojekten hervor.

Übergeben von Eigenschaften an Projekte

In den MSBuild-Versionen vor MSBuild 3.5 war das Übergeben unterschiedlicher Eigenschaftensätze an verschiedene im MSBuild-Element aufgeführte Projekte sehr schwierig. Bei der Verwendung des Eigenschaftenattributs der MSBuild-Aufgabe wurde ihre Einstellung auf alle zu erstellenden Projekte angewendet. Um das zu verhindern, musste die MSBuild-Aufgabe unter Angabe unterschiedlicher Eigenschaften für jedes Projekt in der Elementliste als Batch verarbeitet werden.

MSBuild 3.5 bietet jedoch zwei neue reservierte Metadatenelemente, Properties und AdditionalProperties. Sie gewährleisten die Flexibilität, die zur Übergabe unterschiedlicher Eigenschaften für verschiedene mit der MSBuild-Aufgabe erstellte Projekte erforderlich ist.

Hinweis
Diese neuen Metadatenelemente sind nur auf Elemente anwendbar, die im Projektattribut der MSBuild-Aufgabe übergeben werden.

Multiprozessor-Buildvorteile

Einer der größten Vorteile dieser neuen Metadaten wird offensichtlich, wenn Sie Projekte parallel auf einem Mehrprozessorsystem erstellen. Die Metadaten ermöglichen die Konsolidierung aller Projekte in einem MSBuild-Aufgabe-Aufruf, ohne dass Batchverarbeitung oder bedingte MSBuild -Aufgaben ausgeführt werden müssen. Sie brauchen nur eine einzige MSBuild-Aufgabe aufzurufen, und alle im Projektattribut aufgeführten Projekte werden parallel erstellt. (Dazu muss jedoch das BuildInParallel=true-Attribut in der MSBuild-Aufgabe vorhanden sein.) Weitere Informationen finden Sie unter Erstellung für mehrere Prozessoren.

Properties-Metadaten

Ein häufiges Szenario ist die Erstellung mehrerer Projektmappendateien mit der MSBuild-Aufgabe unter Verwendung unterschiedlichen Buildkonfigurationen. Sie können Projektmappe a1 mit der Debugkonfiguration und Projektmappe a2 mit der Releasekonfiguration erstellen. In MSBuild 2.0 würde diese Projektdatei wie folgt aussehen:

Hinweis
Im folgenden Beispiel stellt "…" zusätzliche Projektmappendateien dar.

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
    </Target>
</Project>

Durch die Verwendung der Properties-Metadaten können Sie diesen Vorgang vereinfachen und eine einzige MSBuild-Aufgabe verwenden, wie nachfolgend dargestellt:

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…">
            <Properties>Configuration=Debug</Properties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"/>
    </Target>
</Project>

- oder -

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…"/>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)" 
          Properties="Configuration=Debug"/>
    </Target>
</Project>

AdditionalProperties-Metadaten

Erwägen Sie beim Erstellen von zwei Projektmappendateien mit der MSBuild-Aufgabe folgendes Szenario: Für beide Projektmappendateien wird die Releasekonfiguration verwendet, aber eine verwendet die x86-Architektur und die andere die ia64-Architektur. In MSBuild 2.0 müssten Sie mehrere Instanzen der MSBuild-Aufgabe erstellen, nämlich eine zum Erstellen des Projekts mit der Releasekonfiguration und der x86-Architektur, und eine zweite, die die Releasekonfiguration mit der ia64-Architektur verwendet. Die Projektdatei würde wie folgt aussehen:

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln…" Properties="Configuration=Release; 
          Architecture=x86"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release; 
          Architecture=ia64"/>
    </Target>
</Project>

Durch die Verwendung der AdditionalProperties-Metadaten können Sie diesen Vorgang vereinfachen und eine einzige MSBuild-Aufgabe verwenden, wie nachfolgend dargestellt:

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…">
            <AdditionalProperties>Architecture=x86
              </AdditionalProperties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <AdditionalProperties>Architecture=ia64
              </AdditionalProperties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)" 
          Properties="Configuration=Release"/>
    </Target>
</Project>

Beispiel

Im folgenden Beispiel wird die MSBuild-Aufgabe verwendet, um die von der ProjectReferences-Elementauflistung angegebenen Projekte zu erstellen. Die sich ergebenden Zielausgaben werden in der AssembliesBuiltByChildProjects-Elementauflistung gespeichert.

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <ProjectReferences Include="*.*proj" />
    </ItemGroup>

    <Target Name="BuildOtherProjects">
        <MSBuild
            Projects="@(ProjectReferences)"
            Targets="Build">
            <Output
                TaskParameter="TargetOutputs"
                ItemName="AssembliesBuiltByChildProjects" />
        </MSBuild>
    </Target>

</Project>

Siehe auch

Konzepte

MSBuild-Aufgaben

Weitere Ressourcen

Referenz zu MSBuild-Aufgaben

Änderungsprotokoll