Item, élément (MSBuild)

  • Article

Contient un élément défini par l'utilisateur et ses métadonnées. Chaque élément utilisé dans un projet MSBuild doit être spécifié en tant qu’enfant d’un élément ItemGroup.

<Projet>
 <ItemGroup>
  <Item>

Syntaxe

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

Spécifier des métadonnées en tant qu’attributs

Dans MSBuild version 15.1 ou ultérieure, toutes les métadonnées dont le nom n’entre pas en conflit avec la liste actuelle des attributs peuvent éventuellement être exprimées en tant qu’attribut.

Par exemple, pour spécifier une liste de packages NuGet, vous utiliseriez normalement une syntaxe similaire à la suivante.

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

À présent, toutefois, vous pouvez passer les métadonnées Version en tant qu’attribut, comme dans la syntaxe suivante :

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

Attributs et éléments

Les sections suivantes décrivent des attributs, des éléments enfants et des éléments parents.

Attributs

Attribut Description
Include Attribut facultatif.

Fichier ou caractère générique à inclure dans la liste des éléments.
Exclude Attribut facultatif.

Fichier ou caractère générique à exclure de la liste des éléments.
Condition Attribut facultatif.

Condition à évaluer. Pour plus d’informations, consultez l’article Conditions (Conditions MSBuild).
Remove Attribut facultatif.

Fichier ou caractère générique à supprimer de la liste des éléments.
MatchOnMetadata Attribut facultatif.

Modifie les attributs Remove qui référencent d’autres éléments pour qu’ils correspondent aux noms de métadonnées spécifiés au lieu de correspondre aux valeurs des éléments référencés.

Cet attribut est valide uniquement s’il est spécifié avec un attribut Remove qui contient uniquement des références à d’autres éléments (par exemple Remove="@(Compile);@(Content)"). Plus d’informations dans Éléments.
MatchOnMetadataOptions Attribut facultatif.

Spécifie la chaîne correspondant à la stratégie utilisée par MatchOnMetadata. Les valeurs possibles sont CaseSensitive, CaseInsensitive ou PathLike. La valeur par défaut est CaseInsensitive.
KeepDuplicates Attribut facultatif.

Spécifie si un élément doit être ajouté au groupe cible s'il s'agit d'une copie exacte d'un élément existant. Si les éléments source et cible ont les mêmes valeurs Include mais des métadonnées différentes, l'élément est ajouté même si KeepDuplicates est défini sur false. Pour plus d’informations, consultez l’article Éléments MSBuild.

Cet attribut n'est valide que s'il est spécifié pour un élément d'un ItemGroup présent dans un Target.
KeepMetadata Attribut facultatif.

Métadonnées des éléments sources à ajouter aux éléments cibles. Seules les métadonnées dont les noms sont spécifiés dans la liste délimitée par des points-virgules sont transférées depuis un élément source vers un élément cible. Pour plus d’informations, consultez l’article Éléments MSBuild.

Cet attribut n'est valide que s'il est spécifié pour un élément d'un ItemGroup présent dans un Target.
RemoveMetadata Attribut facultatif.

Métadonnées des éléments sources à ne pas transférer aux éléments cibles. Toutes les métadonnées sont transférées depuis un élément source vers un élément cible, à l'exception des métadonnées dont le nom figure dans la liste de noms délimitée par des points-virgules. Pour plus d’informations, consultez l’article Éléments MSBuild.

Cet attribut n'est valide que s'il est spécifié pour un élément d'un ItemGroup présent dans un Target.
Update Attribut facultatif. (Disponible uniquement pour les projets .NET Core dans Visual Studio versions 2017 ou ultérieures).

Vous permet de modifier les métadonnées d’un élément ; généralement utilisé pour remplacer les métadonnées par défaut d’éléments spécifiques après qu’un groupe d’éléments est initialement spécifié (par exemple, avec un caractère générique carte).

Cet attribut est valide seulement s’il est spécifié pour un élément d’un ItemGroup qui n’est pas présent dans un Target.

Éléments enfants

Élément Description
ItemMetadata Clé de métadonnées d'élément définie par l'utilisateur, qui contient la valeur des métadonnées de l'élément. Un élément peut ne contenir aucun élément ItemMetadata ou en contenir plusieurs.

Éléments parents

Élément Description
ItemGroup Élément grouping pour d’autres éléments.

Notes

Les éléments Item définissent les entrées du système de génération et sont regroupés en collections d'éléments, selon leur nom de collection défini par l'utilisateur. Ces collections d’éléments peuvent être utilisées comme paramètres des tâches, lesquelles utilisent les éléments d’une collection pour exécuter les étapes du processus de génération. Pour plus d’informations, consultez l’article Éléments MSBuild.

La notation @(<myType>) permet de développer une collection d’éléments de type <myType> en une liste de chaînes séparées par des points-virgules, et de la transmettre à un paramètre. Si le paramètre est de type string, la valeur du paramètre correspond à la liste des éléments séparés par des points-virgules. Si le paramètre est un tableau de chaînes (string[]), chaque élément est inséré dans le tableau selon l'emplacement des points-virgules. Si le paramètre de tâche est de type ITaskItem[], la valeur correspond au contenu de la collection d'éléments et à toutes les métadonnées associées. Pour délimiter chaque élément à l’aide d’un caractère autre que le point-virgule, utilisez la syntaxe @(<myType>, '<separator>').

Le moteur MSBuild peut évaluer les caractères génériques comme que * et ?, ainsi que les caractères génériques récursifs comme /**/*.cs. Pour plus d’informations, consultez l’article Éléments MSBuild.

Exemples

L'exemple de code suivant montre comment déclarer deux éléments de type CSFile. Le second élément déclaré contient les métadonnées dans lesquelles MyMetadata a la valeur HelloWorld.

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

L’exemple de code suivant montre comment utiliser l’attribut Update pour modifier les métadonnées dans un fichier appelé somefile.cs fourni par le biais d’un glob. (Disponible uniquement pour les projets .NET Core dans Visual Studio versions 2017 ou ultérieures).

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

Voir aussi