MSBuild-Elemente
Elemente sind Eingaben in das Buildsystem und stellen Dateien in der Regel 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.
Erstellen von Elementen in einer Projektdatei
Elemente werden in der Projektdatei als untergeordnete Elemente eines ItemGroup-Elements deklariert. 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. Im folgenden XML wird z. B. der Elementtyp Compile erstellt, der zwei Dateien enthält.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
Das Element "file1.cs" wird nicht durch das Element "file2.cs" ersetzt. Stattdessen wird das Element an die Liste der Werte für den Compile-Elementtyp angefügt. Elemente können nicht während der Auswertungsphase eines Builds aus einem Elementtyp entfernt werden.
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
Elementen außerhalb von Target-Elementen werden die Werte im Rahmen der Auswertungsphase eines Builds zugewiesen. Während der anschließenden Ausführungsphase können die Elemente erstellt oder geändert werden, wie nachfolgend veranschaulicht:
Elemente können von jeder Aufgabe ausgegeben werden. Um ein Element auszugeben, muss das Task-Element über ein untergeordnetes Output-Element mit einem ItemName-Attribut verfügen.
Elemente können von der CreateItem-Aufgabe ausgegeben werden. Diese Verwendung ist veraltet.
Ab .NET Framework 3.5 können Target-Elemente ItemGroup-Elemente mit Elementelementen enthalten.
Verweisen auf Elemente in einer Projektdatei
Auf Elementtypen wird in der gesamten Projektdatei mit der Syntax @(ItemType) verwiesen. Auf den Elementtyp im vorherigen Beispiel wird beispielsweise mit @(Compile) verwiesen. Mithilfe dieser Syntax können Sie Elemente an Aufgaben übergeben. Dabei wird der Elementtyp als Parameter dieser Aufgabe festgelegt. Weitere Informationen finden Sie unter Gewusst wie: Auswählen von Dateien für den Buildvorgang.
Wenn Elementtypen erweitert werden, werden die darin enthaltenen Elemente standardmäßig durch Semikolons (;) getrennt. Verwenden Sie die Syntax @(ItemType, 'Trennzeichen'), um ein vom Standardtrennzeichen abweichendes Trennzeichen festzulegen. 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.
Um beispielsweise alle CS-Dateien anzugeben, die sich im selben Verzeichnis wie die Projektdatei befinden, verwenden Sie das folgende Element in der Projektdatei:
<CSFile Include="*.cs"/>
Folgendes Element wählt alle VB-Dateien auf Laufwerk D: aus:
<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>
Das Exclude-Attribut wirkt sich nur auf die Elemente aus, die vom Include-Attribut im Elementelement hinzugefügt wurden, in dem beide enthalten sind. Beispiel:
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
In diesem Beispiel wird die Datei Form1.cs, die im vorherigen Elementelement hinzugefügt wurde, nicht ausgeschlossen.
Weitere Informationen finden Sie unter Gewusst wie: Ausschließen von Dateien vom Buildvorgang.
Verwenden des Remove-Attributs
Ab .NET Framework 3.5 können Target-Elemente ItemGroup-Elemente mit Elementelementen enthalten. Diese Elementelemente können auch das Remove-Attribut enthalten, das bestimmte Elemente (Dateien) aus dem Elementtyp entfernt. Das folgende XML entfernt beispielsweise alle CONFIG-Dateien aus dem Compile-Elementtyp.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
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 verwendet werden, die zusätzliche Informationen über die Elemente benötigen, oder für die Batchverarbeitung von Aufgaben und Zielen. Weitere Informationen zur Batchverarbeitung 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 dem Element "one.cs" und dem Element "two.cs" des CSFile-Elementtyps Culture-Metadaten mit dem Wert Fr hinzu.
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Ein Element kann über 0 (null) oder mehr Metadatenwerte verfügen. Metadatenwerte können jederzeit geändert werden. Durch Festlegen der Metadaten auf einen leeren Wert werden diese aus dem Build entfernt.
Verweisen auf Elementmetadaten in einer Projektdatei
Auf Elementmetadaten wird in der gesamten Projektdatei mit der Syntax %(ItemMetadataName) verwiesen. Bei Mehrdeutigkeiten können die Daten über den Namen des Elementtyps qualifiziert werden, z. B. %(ItemType.ItemMetaDataName). Im folgenden Beispiel werden die Display-Metadaten verwendet, um eine Batchverarbeitung der Message-Aufgabe auszuführen. 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 über das bekannte Metadatenelement %(Filename), dessen Wert der Dateiname des Elements ist. Eine Liste bekannter Elementmetadaten finden Sie unter MSBuild bekannte Elementmetadaten.
Umwandeln von Elementtypen mit Metadaten
Elementlisten können mit Metadaten in neue Elementlisten umgewandelt werden. Beispielsweise kann der Elementtyp CppFiles, der Elemente enthält, die CPP-Dateien darstellen, mit dem Ausdruck @(CppFiles -> '%(Filename).obj') in eine entsprechende Liste von OBJ-Dateien umgewandelt werden.
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 mit dem ItemDefinitionGroup-Element jedem beliebigen Elementtyp Standardmetadaten hinzufügen. Analog zu bekannten Metadaten sind die Standardmetadaten allen Elementen des angegebenen Elementtyps zugeordnet. Standardmetadaten können in einer Elementdefinition explizit überschrieben werden. Das folgende XML ordnet beispielsweise den Compile-Elementen "one.cs" und "three.cs" die BuildDay-Metadaten mit dem Wert "Monday" zu und ordnet dem Element "two.cs" die BuildDay-Metadaten mit dem Wert "Tuesday" zu.
<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.
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