Item-Element (MSBuild)

Artikel
06/19/2023

Enthält ein benutzerdefiniertes Element und die zugehörigen Metadaten. Jedes Element, das in einem MSBuild-Projekt verwendet wird, muss als untergeordnetes Element eines ItemGroup-Elements angegeben werden.

Syntax

<Item Include="*.cs"
        Exclude="MyFile.cs"
        Condition="'String A'=='String B'">
    <ItemMetadata1>...</ItemMetadata1>
    <ItemMetadata2>...</ItemMetadata2>
</Item>

Metadaten als Attribute angeben

In MSBuild 15.1 oder höher können Metadaten mit einem Namen, der der aktuellen Liste der Attribute nicht widerspricht, optional als Attribut ausgedrückt werden.

Um beispielsweise eine Liste von NuGet-Paketen anzugeben, würden Sie normalerweise etwas wie die folgende Syntax verwenden.

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json">
    <Version>9.0.1-beta1<Version>
  </PackageReference>
</ItemGroup>

Nun können Sie jedoch die Version-Metadaten als Attribut übergeben, z.B. die folgende Syntax:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="9.0.1-beta1" />
</ItemGroup>

Attribute und Elemente

In den folgenden Abschnitten werden Attribute sowie untergeordnete und übergeordnete Elemente beschrieben.

Attribute

Attribut	Beschreibung
`Include`	Optionales Attribut. Die Datei oder der Platzhalter, die bzw. der in die Liste der Elemente eingeschlossen werden soll.
`Exclude`	Optionales Attribut. Die Datei oder der Platzhalter, die bzw. der aus der Liste der Elemente ausgeschlossen werden soll.
`Condition`	Optionales Attribut. Die auszuwertende Bedingung. Weitere Informationen finden Sie unter Conditions (MSBuild-Bedingungen).
`Remove`	Optionales Attribut. Die Datei oder der Platzhalter, die bzw. der aus der Liste der Elemente entfernt werden soll.
`MatchOnMetadata`	Optionales Attribut. Ändert `Remove`-Attribute, die auf andere Elemente verweisen, sodass der Abgleich anhand der angegebenen Metadatennamen und nicht anhand der Werte der referenzierten Elemente erfolgt. Dieses Attribut ist nur gültig, wenn es zusammen mit einem `Remove`-Attribut angegeben wird, das nur Verweise auf andere Elemente enthält (z. B. `Remove="@(Compile);@(Content)"`). Weitere Informationen finden Sie unter Elemente.
`MatchOnMetadataOptions`	Optionales Attribut. Gibt die von `MatchOnMetadata` verwendete Strategie zum Abgleich von Zeichenfolgen an. Mögliche Werte sind `CaseSensitive`, `CaseInsensitive` oder `PathLike`. Der Standardwert ist `CaseInsensitive`.
`KeepDuplicates`	Optionales Attribut. Gibt an, ob ein Element der Zielgruppe hinzugefügt werden soll, wenn es sich um ein exaktes Duplikat eines vorhandenen Elements handelt. Wenn das Quell- und Zielelement den gleichen `Include`-Wert aber unterschiedliche Metadaten aufweisen, wird das Element auch dann hinzugefügt, wenn `KeepDuplicates` auf `false` festgelegt ist. Weitere Informationen finden Sie unter Elemente. Dieses Attribut ist nur gültig, wenn es für ein Element in einer `ItemGroup` angegeben wird, die sich in einem `Target` befindet.
`KeepMetadata`	Optionales Attribut. Die Metadaten für die Quellelemente, die den Zielelementen hinzugefügt werden sollen. Nur die Metadaten, deren Namen in der durch Semikolon getrennten Liste angegeben werden, werden von einem Quellelement in ein Zielelement übertragen. Weitere Informationen finden Sie unter Elemente. Dieses Attribut ist nur gültig, wenn es für ein Element in einer `ItemGroup` angegeben wird, die sich in einem `Target` befindet.
`RemoveMetadata`	Optionales Attribut. Die Metadaten für die Quellelemente, die nicht an der Zielelemente übertragen werden sollen. Alle Metadaten werden aus einem Quellelement in ein Zielelement mit Ausnahme von Metadaten übertragen, deren Namen in der durch Semikolons getrennten Liste der Namen enthalten sind. Weitere Informationen finden Sie unter Elemente. Dieses Attribut ist nur gültig, wenn es für ein Element in einer `ItemGroup` angegeben wird, die sich in einem `Target` befindet.
`Update`	Optionales Attribut. (Nur für .NET Core-Projekte in Visual Studio 2017 oder höher verfügbar.) Ermöglicht es Ihnen, Metadaten eines Elements zu ändern; wird in der Regel verwendet, um die Standardmetadaten bestimmter Elemente außer Kraft zu setzen, nachdem eine Gruppe von Elementen anfänglich angegeben wurde (z. B. mit einem Wild Karte). Dieses Attribut ist nur gültig, wenn es für ein Element in einer `ItemGroup` angegeben wird, die sich nicht in einem `Target` befindet.

Untergeordnete Elemente

Element	Beschreibung
ItemMetadata	Ein benutzerdefinierter Elementmetadatenschlüssel, der den Elementmetadatenwert enthält. Es kann keine oder mehrere `ItemMetadata`-Elemente in einem Element geben.

Übergeordnete Elemente

Element	Beschreibung
ItemGroup	Grouping-Element für Elemente.

Hinweise

Item-Elemente definieren Eingaben ins Buildsystem und sind basierend auf ihren benutzerdefinierten Auflistungsnamen in Elementauflistungen gruppiert. Diese Elementtypen können als Parameter für Aufgaben verwendet werden, die mithilfe der einzelnen Elemente in den Auflistungen die Schritte des Buildprozesses ausführen. Weitere Informationen finden Sie unter Elemente.

Mithilfe der Notation @(<myType>) kann eine Auflistung von Elementen vom Typ <myType> in eine durch Semikolons getrennte Liste von Zeichenfolgen erweitert und an einen Parameter übergeben werden. Wenn der Parameter vom Typ string ist, entspricht der Wert des Parameters der Liste der Elemente, die durch Semikolons getrennt sind. Wenn der Parameter ein Array von Zeichenfolgen ist (string[]), werden die einzelnen Elemente ins Array basierend auf der Position der Semikolons eingefügt. Ist der Task-Parameter vom Typ ITaskItem[], entspricht der Wert dem Inhalt der Elementauflistung einschließlich ggf. angefügter Metadaten. Um Elemente mit einem anderen Zeichen als einem Semikolon voneinander zu trennen, verwenden Sie die Syntax @(<myType>, '<Trennlinie>').

Die MSBuild-Engine kann Platzhalter wie * und ? sowie rekursive Platzhalter wie /**/*.cs auswerten. Weitere Informationen finden Sie unter Elemente.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie zwei Elemente vom Typ CSFile deklariert werden. Das zweite deklarierte Element enthält Metadaten, für die MyMetadata auf HelloWorld festgelegt ist.

<ItemGroup>
    <CSFile Include="engine.cs; form.cs" />
    <CSFile Include="main.cs" >
        <MyMetadata>HelloWorld</MyMetadata>
    </CSFile>
</ItemGroup>

Das folgende Codebeispiel zeigt, wie Sie das Update-Attribut verwenden, um die Metadaten in einer Datei namens somefile.cs zu ändern, die durch ein Globmuster enthalten war. (Nur für .NET Core-Projekte in Visual Studio 2017 oder höher verfügbar.)

<ItemGroup>
    <Compile Update="somefile.cs">  // or Update="*.designer.cs"
        <MetadataKey>MetadataValue</MetadataKey>
    </Compile>
</ItemGroup>