Freigeben über

MSBuild-Elemente

  • Artikel

MSBuild-Elemente sind Eingaben in das Buildsystem, und sie werden in der Regel Dateien dar. Elemente werden auf der Grundlage ihres Elementnamens in Elementtypen gruppiert. Elementtypen sind benannte Listen von Elementen, die als Parameter für Aufgaben verwendet werden können. In den Aufgaben werden die Schritte des Buildprozesses mithilfe der Elementwerte ausgeführt.

Da Elemente anhand des Elementtyps benannt werden, zu dem sie gehören, können die Begriffe "Element" und "Elementwert" synonym verwendet werden.

In diesem Thema

  • Erstellen von Elementen in einer Projektdatei

  • Erstellen von Elementen während der Ausführung

  • Verweisen auf Elemente in einer Projektdatei

  • Verwenden von Platzhaltern zum Festlegen von Elementen

  • Verwenden des Exclude-Attributs

  • Elementmetadaten

    • Verweisen auf Elementmetadaten in einer Projektdatei

    • Bekannte Elementmetadaten

    • Elementtypen mithilfe von Metadaten transformieren

  • Elementdefinitionen

  • Attribute für Elemente in einer Gruppe von Elementen eines Ziels

    • Entfernen Sie das Attribut

    • KeepMetadata-Attribut

    • RemoveMetadata-Attribut

    • KeepDuplicates-Attribut

Erstellen von Elementen in einer Projektdatei

Sie deklarieren Elemente in der Projektdatei als untergeordnete Elemente eines - Elements Elementgruppe. Der Name des untergeordneten Elements ist der Typ des Elements. Durch das Include-Attribut des Elements wird angegeben, welche Elemente (Dateien) in den jeweiligen Elementtyp aufgenommen werden sollen. Beispielsweise erstellt die folgende XML einen Elementtyp, der Compile", die zwei Dateien enthält.

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

Das Element "file2.cs" ersetzt nicht das Element "file1.cs"; Stattdessen wird der Dateiname die Liste der Werte für den Compile-Elementtyp angefügt. Sie können kein Element aus einem Elementtyp während der Auswertungsphase eines Builds entfernen.

Das folgende XML erstellt den gleichen Elementtyp, indem beide Dateien in einem Include-Attribut deklariert werden. Beachten Sie, dass die Dateinamen durch ein Semikolon getrennt werden.

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

Erstellen von Elementen während der Ausführung

Elemente, die außerhalb Ziel-Elemente sind, werden die Werte im Rahmen der Auswertungsphase eines Builds. Während der anschließenden Ausführungsphase können Elemente folgendermaßen erstellt oder geändert werden:

  • Jede Aufgabe kann ein Element ausgeben. Um ein Element auszugeben, muss das Task-Element über ein untergeordnetes Output-Element mit einem ItemName-Attribut verfügen.

  • Die CreateItem Aufgabe kann ein Element ausgeben. Diese Verwendung ist veraltet.

  • Ab .NET Framework 3.5 können Target-Elemente ItemGroup-Elemente mit Elementelementen enthalten.

Verweisen auf Elemente in einer Projektdatei

Um Elementtypen in der Projektdatei zu verweisen, verwenden Sie die Syntax @ (ItemType). Beispielsweise können Sie den Elementtyp im vorherigen Beispiel verweisen, indem Sie @(Compile) haben. Wenn Sie diese Syntax verwenden, können Sie Elemente an Aufgaben übergeben, indem Sie den Elementtyp als Parameter dieser Aufgabe angeben. Weitere Informationen finden Sie unter Gewusst wie: Auswählen von Dateien für den Buildvorgang.

Standardmäßig werden die Elemente eines Elementtyps durch Semikolons (;) getrennt beim erweitert wurde. Sie können die Syntax @ verwenden (ItemType, "Trennzeichen") um ein vom Standardtrennzeichen abweichendes anzugeben. Weitere Informationen finden Sie unter Gewusst wie: Anzeigen einer durch Trennzeichen getrennten Elementliste.

Verwenden von Platzhaltern zum Festlegen von Elementen

Sie können die Platzhalter **, * und ? verwenden, um eine Gruppe von Dateien als Eingaben für einen Build anzugeben, anstatt jede Datei separat aufzulisten.

  • Das Platzhalterzeichen ? entspricht einem einzelnen Zeichen.

  • Das Platzhalterzeichen * entspricht 0 (null) oder mehr Zeichen.

  • Das Platzhalterzeichensequenz ** entspricht einem partiellen Pfad.

Sie können beispielsweise alle CS-Dateien im Verzeichnis angeben, das die Projektdatei enthält, indem Sie das folgende Element in der Projektdatei verwendet.

<CSFile Include="*.cs"/>

Das folgende Element wählt alle VB-Dateien auf D aus: Laufwerk:

<VBFile Include="D:/**/*.vb"/>

Weitere Informationen zu Platzhaltern finden Sie unter Gewusst wie: Auswählen von Dateien für den Buildvorgang.

Verwenden des Exclude-Attributs

Elementelemente können auch das Exclude-Attribut enthalten, das bestimmte Elemente (Dateien) aus dem Elementtyp ausschließt. Das Exclude-Attribut wird in aller Regel mit Platzhaltern verwendet. Das folgende XML fügt beispielsweise alle CS-Dateien im Verzeichnis mit Ausnahme der Datei DoNotBuild.cs dem CSFile-Elementtyp hinzu.

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

Die Exclude-Attributaffekte nur die Elemente, die vom Include-Attribut im Elementelement hinzugefügt wurden, das beide enthält. Im folgenden Beispiel wird nicht die Datei Form1.cs, die im vorherigen Elementelement hinzugefügt wurde.

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

Weitere Informationen finden Sie unter Gewusst wie: Ausschließen von Dateien vom Buildvorgang.

Elementmetadaten

Elemente Metadaten enthalten zusätzlich zu den Informationen in den Include und Exclude-Attributen. Diese Metadaten können von Aufgaben verwendet werden, die weitere Informationen über die Elemente benötigen oder die Batchverarbeitung von Aufgaben und Zielen. Weitere Informationen finden Sie unter MSBuild-Batchverarbeitung.

Metadaten stellen eine Auflistung von Schlüssel-Wert-Paaren dar, die in der Projektdatei als untergeordnete Elemente eines Elementelements deklariert werden. Der Name des untergeordneten Elements entspricht dem Namen der Metadaten, und der Wert des untergeordneten Elements entspricht dem Wert der Metadaten.

Die Metadaten sind dem Elementelement zugeordnet, das diese enthält. Das folgende XML fügt beispielsweise zu Culture Metadaten, die den Wert Fr zu den "one.cs" und dem Element Elemente des CSFile-Elementtyps hinzu.

<ItemGroup>
    <CSFile Include="one.cs;two.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Ein Element kann über 0 (null) oder mehr Metadatenwerte verfügen. Sie können Metadatenwerte jederzeit ändern. Wenn Sie die Metadaten in einen leeren Wert, Sie diese aus dem Build entfernen.

Verweisen auf Elementmetadaten in einer Projektdatei

Sie können Elementmetadaten in der Projektdatei verweisen, indem Sie die Syntax % (ItemMetadataName) verwenden. Bei Mehrdeutigkeiten vorhanden ist, können Sie einen Verweis qualifizieren, indem Sie den Namen des Elementtyps verwenden. Beispielsweise können Sie % (ItemType.ItemMetaDataName) angeben. Im folgenden Beispiel werden die Display-Metadaten, um die Message-Aufgabe auszuführen zu verarbeiten. Weitere Informationen zur Batchverarbeitung mit den Elementmetadaten finden Sie unter Elementmetadaten bei der Batchverarbeitung von Aufgaben.

<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

Wenn einem Elementtyp ein Element hinzugefügt wird, werden diesem Element bekannte Metadaten zugewiesen. Beispielsweise verfügen alle Elemente die bekannten Metadaten %(Filename), deren Wert der Dateiname des Elements ist. Weitere Informationen finden Sie unter MSBuild bekannte Elementmetadaten.

Elementtypen mithilfe von Metadaten transformieren

Sie können Elementlisten in neue Elementlisten transformieren, indem Sie Metadaten verwenden. Beispielsweise können Sie einen Elementtyp CppFiles transformieren, der Elemente enthält, die CPP-Dateien in eine entsprechende Liste von OBJ-Dateien darstellen, indem Sie den Ausdruck @(CppFiles -> '%(Filename).obj') verwenden.

Im folgenden Code wird ein CultureResource-Elementtyp mit Kopien aller EmbeddedResource-Elemente mit Culture-Metadaten erstellt. Der Culture-Metadatenwert wird als Wert für die neuen CultureResource.TargetDirectory-Metadaten verwendet.

<Target Name="ProcessCultureResources">
    <ItemGroup>
        <CultureResource Include="@(EmbeddedResource)"
            Condition="'%(EmbeddedResource.Culture)' != ''">
            <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
        </CultureResource>
    </ItemGroup>
</Target>

Weitere Informationen finden Sie unter MSBuild-Transformationen.

Elementdefinitionen

Ab .NET Framework 3.5, können Sie jedem Elementtyp Standardmetadaten hinzufügen, indem Sie ItemDefinitionGroup-Element verwenden. Wie bekannte Metadaten werden die Standardmetadaten allen Elementen des Elementtyps zugeordnet, den Sie angeben. Sie können Standardmetadaten in einer Elementdefinition explizit überschreiben. Beispielsweise gibt die folgende XML die Compile-Elemente "one.cs" und "three.cs" die Metadaten BuildDay mit dem Wert "Monday". Der Code gibt dem Element "two.cs" die Metadaten BuildDay mit dem Wert "Tuesday".

<ItemDefinitionGroup>
    <Compile>
        <BuildDay>Monday</BuildDay>
    </Compile>
</ItemDefinitionGroup>
<ItemGroup>
    <Compile Include="one.cs;three.cs" />
    <Compile Include="two.cs">
        <BuildDay>Tuesday</BuildDay>
    </Compile>
</ItemGroup>

Weitere Informationen finden Sie unter Elementdefinitionen.

Attribute für Elemente in einer Gruppe von Elementen eines Ziels

Ab .NET Framework 3.5 können Target-Elemente ItemGroup-Elemente mit Elementelementen enthalten. Die Attribute in diesem Abschnitt sind gültig, wenn sie für ein Element in ItemGroup angegeben werden, das in Target ist.

Entfernen Sie das Attribut

Elemente in ItemGroup eines Ziels enthalten möglicherweise das Remove-Attribut, das bestimmte Elemente (Dateien) aus dem Elementtyp entfernt. Dieses Attribut wurde in .NET Framework 3.5 eingeführt.

Im folgenden Beispiel entfernt alle CONFIG-Dateien aus dem Compile-Elementtyp.

<Target>
    <ItemGroup>
        <Compile Remove="*.config"/>
    </ItemGroup>
</Target>

KeepMetadata-Attribut

Wenn ein Element innerhalb eines Ziels generiert wird, kann das Elementelement das KeepMetadata-Attribut enthalten. Wenn dieses Attribut angegeben ist, wird nur die Metadaten, die im durch Semikolons getrennte Liste von Namen angegeben wird, vom Quellelement zum Zielelement übertragen werden. Ein leerer Wert dieses Attributs ist zum Angeben es nicht äquivalent. Das KeepMetadata-Attribut wurde in .NET Framework 4.5 eingeführt.

Das folgende Beispiel veranschaulicht, wie das - Attribut KeepMetadata verwendet.

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

    <ItemGroup>
        <FirstItem Include="rhinoceros">
            <Class>mammal</Class>
            <Size>large</Size>
        </FirstItem>

    </ItemGroup>
    <Target Name="MyTarget">
        <ItemGroup>
            <SecondItem Include="@(FirstItem)" KeepMetadata="Class" />
        </ItemGroup>

        <Message Text="FirstItem: %(FirstItem.Identity)" />
        <Message Text="  Class: %(FirstItem.Class)" />
        <Message Text="  Size:  %(FirstItem.Size)"  />

        <Message Text="SecondItem: %(SecondItem.Identity)" />
        <Message Text="  Class: %(SecondItem.Class)" />
        <Message Text="  Size:  %(SecondItem.Size)"  />
    </Target>
</Project>

<!--
Output:
  FirstItem: rhinoceros
    Class: mammal
    Size:  large
  SecondItem: rhinoceros
    Class: mammal
    Size: 
-->

RemoveMetadata-Attribut

Wenn ein Element innerhalb eines Ziels generiert wird, kann das Elementelement das RemoveMetadata-Attribut enthalten. Wenn dieses Attribut festgelegt ist, werden alle Metadaten vom Quellelement zum Zielelement außer Metadaten übertragen, deren Namen im durch Semikolons getrennte Liste von Namen enthalten sind. Ein leerer Wert dieses Attributs ist zum Angeben es nicht äquivalent. Das RemoveMetadata-Attribut wurde in .NET Framework 4.5 eingeführt.

Das folgende Beispiel veranschaulicht, wie das - Attribut RemoveMetadata verwendet.

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

    <PropertyGroup>
        <MetadataToRemove>Size;Material</MetadataToRemove>
    </PropertyGroup>

    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item2 Include="@(Item1)" RemoveMetadata="$(MetadataToRemove)" />
        </ItemGroup>

        <Message Text="Item1: %(Item1.Identity)" />
        <Message Text="  Size:     %(Item1.Size)" />
        <Message Text="  Color:    %(Item1.Color)" />
        <Message Text="  Material: %(Item1.Material)" />
        <Message Text="Item2: %(Item2.Identity)" />
        <Message Text="  Size:     %(Item2.Size)" />
        <Message Text="  Color:    %(Item2.Color)" />
        <Message Text="  Material: %(Item2.Material)" />
    </Target>
</Project>

<!--
Output: 
  Item1: stapler
    Size:     medium
    Color:    black
    Material: plastic
  Item2: stapler
    Size:     
    Color:    black
    Material: 
-->

KeepDuplicates-Attribut

Wenn ein Element innerhalb eines Ziels generiert wird, kann das Elementelement das KeepDuplicates-Attribut enthalten. KeepDuplicates ist ein Boolean-Attribut, das angibt, ob ein Element zur Zielgruppe hinzugefügt werden soll, wenn das Element ein exaktes Duplikat eines vorhandenen Elements ist.

Wenn das Quell- und Zielelement denselben Einschliessungswert aber unterschiedliche Metadaten haben, wird das Element hinzugefügt, wenn KeepDuplicates zu false festgelegt ist. Ein leerer Wert dieses Attributs ist zum Angeben es nicht äquivalent. Das KeepDuplicates-Attribut wurde in .NET Framework 4.5 eingeführt.

Das folgende Beispiel veranschaulicht, wie das - Attribut KeepDuplicates verwendet.

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

    <ItemGroup>
        <Item1 Include="hourglass;boomerang" />
        <Item2 Include="hourglass;boomerang" />
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item1 Include="hourglass" KeepDuplicates="false" />
            <Item2 Include="hourglass" />
        </ItemGroup>

        <Message Text="Item1: @(Item1)" />
        <Message Text="  %(Item1.Identity)  Count: @(Item1->Count())" />
        <Message Text="Item2: @(Item2)" />
        <Message Text="  %(Item2.Identity)  Count: @(Item2->Count())" />
    </Target>
</Project>

<!--
Output: 
  Item1: hourglass;boomerang
    hourglass  Count: 1
    boomerang  Count: 1
  Item2: hourglass;boomerang;hourglass
    hourglass  Count: 2
    boomerang  Count: 1
-->

Siehe auch

Aufgaben

Gewusst wie: Auswählen von Dateien für den Buildvorgang

Gewusst wie: Ausschließen von Dateien vom Buildvorgang

Gewusst wie: Anzeigen einer durch Trennzeichen getrennten Elementliste

Referenz

Item-Element (MSBuild)

Konzepte

Elementdefinitionen

MSBuild-Batchverarbeitung

Weitere Ressourcen

MSBuild-Grundlagen

MSBuild