MSBuild-Elemente

Artikel
09/02/2008

Aktualisiert: November 2007

Elemente stellen Eingaben für das Buildsystem dar und werden auf Grundlage ihrer benutzerdefinierten Auflistungsnamen in Elementauflistungen gruppiert. Diese Elementauflistungen können als Parameter für Aufgaben verwendet werden, die die in der Auflistung enthaltenen Elemente verwenden, um die einzelnen Schritte des Buildvorgangs auszuführen.

Erstellen von Elementen in einer Projektdatei

Elemente werden in der Projektdatei deklariert, indem ein Element als untergeordnetes Element eines ItemGroup-Elements mit dem Namen des Elements erstellt wird. Durch das Include-Attribut des Elements wird angegeben, welche Dateien in die jeweilige Elementauflistung aufgenommen werden sollen. Im folgenden Code wird z. B. eine Elementauflistung mit dem Namen Compile erstellt, die zwei Dateien einschließt.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Mit dem folgenden Code wird die gleiche Elementauflistung erstellt, indem die beiden durch ein Semikolon getrennten Dateien in einem Include-Attribut deklariert werden.

<ItemGroup>
    <Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>

Verweisen auf Elemente in einer Projektdatei

In der gesamten Projektdatei wird mit der Syntax @(ItemCollectionName) auf Elementauflistungen verwiesen. Auf die Elementauflistung im vorherigen Beispiel würden Sie beispielsweise mit @(Compile) verweisen. Mithilfe dieser Syntax können Sie Elementauflistungen an Aufgaben übergeben. Dabei wird die Elementauflistung als Parameter dieser Aufgabe festgelegt. Weitere Informationen finden Sie unter Gewusst wie: Verwenden von Platzhaltern zum Erstellen aller Dateien in einem Verzeichnis.

Wenn Elementauflistungen erweitert werden, werden die darin enthaltenen Elemente standardmäßig durch Semikolons (;) getrennt. Verwenden Sie die Syntax @(Elementauflistungsname, 'Trennzeichen'), um ein vom Standardtrennzeichen abweichendes Trennzeichen festzulegen. Weitere Informationen finden Sie unter Gewusst wie: Anzeigen einer durch Trennzeichen getrennten Elementauflistung.

Verwenden von Platzhaltern zum Festlegen von Elementen

Sie können die Platzhalter **, * und ? verwenden, um eine Gruppe von Dateien als Eingaben für ein Build anzugeben, anstatt jede Datei separat aufzulisten. Um beispielsweise alle CS- oder VB-Dateien anzugeben, die sich im selben Verzeichnis wie die Projektdatei befinden, verwenden Sie eines der folgenden Elemente in der Projektdatei:

– oder –

Hinweis:
Platzhalter können für Elemente nur verwendet werden, um die Eingaben für ein Build anzugeben. Durch Platzhalter können also keine Eingaben für den Sources-Parameter in der Csc-Aufgabe angegeben werden. MSBuild akzeptiert Platzhalter zwar als Parameterwerte, behandelt sie jedoch als Zeichenfolgenliterale und wertet sie nicht aus. Im folgenden Beispiel würde das Zeichenfolgenliteral .cs als Sources*-Parameterwert verwendet werden.

Platzhalter können für Elemente nur verwendet werden, um die Eingaben für ein Build anzugeben. Durch Platzhalter können also keine Eingaben für den Sources-Parameter in der Csc-Aufgabe angegeben werden. MSBuild akzeptiert Platzhalter zwar als Parameterwerte, behandelt sie jedoch als Zeichenfolgenliterale und wertet sie nicht aus. Im folgenden Beispiel würde das Zeichenfolgenliteral *.cs als Sources-Parameterwert verwendet werden.

<Target Name="Compile">
    <CSC Sources="*.cs" />
</Target>

Weitere Informationen zu Platzhaltern finden Sie unter Gewusst wie: Verwenden von Platzhaltern zum Erstellen aller Dateien in einem Verzeichnis.

Verwenden des Exclude-Attributs

Elemente können auch das Exclude-Attribut enthalten, das bestimmte Dateien aus der Elementauflistung ausschließt. Das Exclude-Attribut ist insbesondere in Verbindung mit Platzhaltern hilfreich. Durch den folgenden Code werden z. B. alle CS-Dateien im Verzeichnis mit Ausnahme der Datei DoNotBuild.cs hinzugefügt.

<ItemGroup>
    <CSFile
        Include="*.cs"
        Exclude="DoNotBuild.cs"/>
</ItemGroup>

Weitere Informationen finden Sie unter Gewusst wie: Erstellen aller Dateien in einem Verzeichnis mit Ausnahme einer Datei.

Elementmetadaten

Zusätzlich zu den Informationen aus dem Include-Attribut und dem Exclude-Attribut können Elemente Metadaten enthalten. Diese Metadaten können von Aufgaben, die zusätzliche Informationen über Elemente benötigen, oder für die Batchverarbeitung von Aufgaben und Zielen verwendet werden. Weitere Informationen zur Batchverarbeitung finden Sie unter MSBuild-Batchverarbeitung.

Elementmetadaten werden in der Projektdatei deklariert, indem ein Element mit dem Namen der Metadaten als untergeordnetes Element des Elements erstellt wird. Ein Element kann über 0 (null) oder mehr Metadatenwerte verfügen. Das folgende Element verfügt z. B. über Culture-Metadaten mit dem Wert Fr.

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Verweisen auf Elementmetadaten in einer Projektdatei

In der gesamten Projektdatei wird mit der Syntax @(ItemMetadataName) auf Elementmetadaten verwiesen. Bei Mehrdeutigkeiten können die Daten über den Namen der Elementauflistung qualifiziert werden, z. B. %(Elementauflistungsname.Elementmetadatenname). Im folgenden Beispiel werden Display-Metadaten verwendet, um die Message-Aufgabe im Batchmodus auszuführen. Weitere Informationen zur Verwendung von Elementmetadaten für die Batchverarbeitung finden Sie unter Gewusst wie: Batchverarbeitung von Aufgaben mithilfe von Elementmetadaten.

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <Stuff Include="One.cs" >
            <Display>false</Display>
        </Stuff>
        <Stuff Include="Two.cs">
            <Display>true</Display>
        </Stuff>
    </ItemGroup>
    <Target Name="Batching">
        <Message Text="@(Stuff)" Condition=" '%(Display)' == 'true' "/>
    </Target>
</Project>

Bekannte Elementmetadaten

Sobald ein Element einer Elementauflistung hinzugefügt wird, wird dieses Element erstellt und ihm werden einige bekannte Elementmetadaten zugewiesen. %(Filename) enthält beispielsweise den Dateinamen des Elements. Eine vollständige Liste bekannter Elementmetadaten finden Sie unter Bekannte MSBuild-Elementmetadaten.

Transformieren von Elementauflistungen

Elementauflistungen können in neue Elementauflistungen umgewandelt werden. Eine Elementauflistung von CPP-Dateien kann beispielsweise über einen Ausdruck wie @(CppFiles -> '%(Filename).obj') in eine Elementauflistung von OBJ-Dateien umgewandelt werden. Weitere Informationen finden Sie unter MSBuild-Transformationen.

Siehe auch