Item, élément (MSBuild)

Article
04/16/2024

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.

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>

Partager via