Éléments MSBuild

  • Article

Les éléments MSBuild sont des entrées du système de génération, et ils représentent généralement des fichiers. Les éléments sont groupés dans différents types d'élément selon leurs noms d'élément. Les types d'élément sont des listes nommées d'éléments qui peuvent être utilisés comme paramètres pour les tâches. Les tâches utilisent les valeurs d'élément pour exécuter les étapes du processus de génération.

Les éléments étant nommés en fonction de le type d'élément auquel ils appartiennent, les termes « élément » et « valeur d'élément » peuvent être utilisés indifféremment.

Dans cette rubrique

  • Création d'éléments dans un fichier projet

  • Création d'éléments pendant l'exécution

  • Référencement d'éléments dans un fichier projet

  • Utilisation de caractères génériques pour spécifier des éléments

  • Utilisation de l'attribut Exclude

  • Métadonnées d'élément

    • Référencement de métadonnées d'éléments dans un fichier projet

    • Métadonnées d'éléments connus

    • Types d'éléments de transformation à l'aide de métadonnées

  • Définitions d'éléments

  • Attributs pour les éléments dans un ItemGroup d'une cible

    • Supprimez l'attribut

    • Attribut de KeepMetadata

    • Attribut de RemoveMetadata

    • Attribut de KeepDuplicates

Création d'éléments dans un fichier projet

Vous déclarez des éléments dans le fichier projet en tant qu'éléments enfants d'un élément d' ItemGroup . Le nom de l'élément enfant est le type de l'élément. L'attribut Include de l'élément spécifie quels éléments (fichiers) inclure avec ce type d'élément. Par exemple, le code XML suivant crée un type d'élément nommé Compile, qui inclut deux fichiers.

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

L'élément « file2.cs » ne remplace pas l'élément « file1.cs » ; à la place, le nom de fichier est ajouté à la liste de valeurs du type d'élément de Compile . Vous ne pouvez pas supprimer un élément d'un type d'élément pendant la phase d'évaluation d'une build.

Le code XML suivant crée le même type d'élément en déclarant les deux fichiers dans un attribut Include. Notez que les noms de fichiers sont séparés par un point-virgule.

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

Création d'éléments pendant l'exécution

Les éléments qui sont des éléments en dehors de cible sont assignés des valeurs pendant la phase d'évaluation d'une build. Pendant la phase d'exécution suivante, des éléments peuvent être créés ou modifiés des façons suivantes :

  • Une tâche peut émettre un élément. Pour émettre un élément, l'élément Task doit avoir un élément enfant Output ayant un attribut ItemName.

  • La tâche de CreateItem peut émettre un élément. Cette utilisation est déconseillée.

  • À compter de .NET Framework 3.5, les éléments Target peuvent contenir des éléments ItemGroup pouvant contenir des éléments item.

Référencement d'éléments dans un fichier projet

Pour référencer des types d'élément dans tout le fichier projet, utilisez la syntaxe @ (ItemType). Par exemple, vous référenceriez le type d'élément dans l'exemple précédent à l'aide de @(Compile). En utilisant cette syntaxe, vous pouvez passer des éléments aux tâches en spécifiant le type d'élément comme paramètre de cette tâche. Pour plus d’informations, consultez Comment : sélectionner des fichiers pour la build.

Par défaut, les éléments d'un type d'élément sont séparés par des points-virgules (;) lorsqu'il est développé. Vous pouvez utiliser la syntaxe @ (Typeélément, « séparateur") pour spécifier un séparateur autre que la valeur par défaut. Pour plus d’informations, consultez Comment : afficher une liste d'éléments séparés par des virgules.

Utilisation de caractères génériques pour spécifier des éléments

Vous pouvez utiliser les caractères génériques **, * et ? pour spécifier un groupe de fichiers comme entrées pour une build au lieu de répertorier chaque fichier séparément.

  • Le caractère générique ? correspond à un seul caractère.

  • Le caractère générique * correspond à zéro, un ou plusieurs caractères.

  • La séquence de caractères génériques ** correspond à un chemin d'accès partiel.

Par exemple, vous pouvez spécifier tous les fichiers .cs du répertoire qui contient le fichier projet à l'aide de l'élément suivant dans votre fichier projet.

<CSFile Include="*.cs"/>

L'élément suivant sélectionne tous les fichiers .vb sur le lecteur D : lecteur :

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

Pour plus d'informations sur les caractères génériques, consultez Comment : sélectionner des fichiers pour la build.

Utilisation de l'attribut Exclude

Les éléments item peuvent contenir l'attribut Exclude qui exclut des éléments (fichiers) spécifiques du type d'élément. L'attribut Exclude est généralement utilisé avec des caractères génériques. Par exemple, le code XML suivant ajoute chaque fichier .cs du répertoire au type d'élément CSFile, à l'exception du fichier DoNotBuild.cs.

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

Les affecte d'attribut d' Exclude seulement les éléments ajoutés par l'attribut d' Include dans l'élément item qui les contient. L'exemple suivant n'exclurait pas le fichier Form1.cs, qui a été ajouté à l'élément précédent.

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

Pour plus d’informations, consultez Comment : exclure des fichiers de la build.

Métadonnées d'élément

Les éléments peuvent contenir des métadonnées en plus de les informations dans les attributs d' Include et d' Exclude . Ces métadonnées peuvent être utilisées par les tâches qui nécessitent davantage d'informations sur les éléments ou le traitement par lots de tâches et des cibles. Pour plus d’informations, consultez Traitement par lots de MSBuild.

Les métadonnées sont une collection de paires clé-valeur déclarées dans le fichier projet en tant qu'éléments enfants d'un élément item. Le nom de l'élément enfant est le nom des métadonnées, et la valeur de l'élément enfant est la valeur des métadonnées.

Les métadonnées sont associées à l'élément item qui les contient. Par exemple, le code XML suivant ajoute les métadonnées d' Culture qui a la valeur Fr « one.cs » et aux éléments « two.cs » du type d'élément CSFile.

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

Un élément peut avoir plusieurs valeurs de métadonnées ou n'en avoir aucune. Vous pouvez modifier les valeurs de métadonnées à tout moment. Si vous définissez des métadonnées à une valeur vide, vous supprimez l'efficacité de la génération.

Référencement de métadonnées d'éléments dans un fichier projet

Vous pouvez référencer des métadonnées d'élément dans tout le fichier projet à l'aide de la syntaxe % (ItemMetadataName). Si l'ambiguïté existe, vous pouvez qualifier une référence à l'aide de le nom du type d'élément. Par exemple, vous pouvez spécifier % (ItemType.ItemMetaDataName). L'exemple suivant utilise les métadonnées d'affichage pour le traitement par lot la tâche message. Pour plus d'informations sur l'utilisation des métadonnées d'élément dans le cadre du traitement par lot, consultez Métadonnées d'éléments dans le traitement par lots de tâches.

<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>

Métadonnées d'éléments connus

Lorsqu'un élément est ajouté à un type d'élément, des métadonnées connues lui sont assignées. Par exemple, tous les éléments ont les métadonnées connues %(Filename), dont la valeur est le nom de fichier de l'élément. Pour plus d’informations, consultez Métadonnées d'éléments connus MSBuild.

Types d'éléments de transformation à l'aide de métadonnées

Vous pouvez transformer des listes d'éléments en nouvelles listes d'éléments en utilisant des métadonnées. Par exemple, vous pouvez transformer un type d'élément CppFiles qui contient les éléments qui représentent les fichiers .cpp dans une liste correspondante de fichiers .obj à l'aide de l'expression @(CppFiles -> '%(Filename).obj').

Le code suivant crée un type d'élément CultureResource qui contient des copies de tous les éléments EmbeddedResource comportant les métadonnées Culture. La valeur des métadonnées Culture devient la valeur des nouvelles métadonnées CultureResource.TargetDirectory.

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

Pour plus d’informations, consultez Transformations MSBuild.

Définitions d'éléments

À compter de.NET Framework 3.5, vous pouvez ajouter des métadonnées par défaut à tout type d'élément à l'aide de Élément ItemDefinitionGroup. Comme les métadonnées connues, les métadonnées par défaut sont associées à tous les éléments du type d'élément que vous spécifiez. Vous pouvez explicitement la substitution de métadonnées par défaut dans une définition d'élément. Par exemple, le code XML suivant affiche les éléments « one.cs » et « three.cs » d' Compile les métadonnées BuildDay avec la valeur « mon ». Le code donne à l'élément « two.cs » les métadonnées BuildDay avec la valeur « mardi ».

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

Pour plus d’informations, consultez Définitions d'éléments.

Attributs pour les éléments dans un ItemGroup d'une cible

À compter de .NET Framework 3.5, les éléments Target peuvent contenir des éléments ItemGroup pouvant contenir des éléments item. Les attributs de cette section sont valides lorsqu'ils sont spécifiés pour un élément dans ItemGroup qui est dans Target.

Supprimez l'attribut

Les éléments de ItemGroup d'une cible peuvent contenir l'attribut d' Remove , qui supprime des éléments (fichiers) spécifiques du type d'élément. Cet attribut a été introduit dans le .NET Framework 3.5.

L'exemple suivant supprime chaque fichier .config du type d'élément compile.

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

Attribut de KeepMetadata

Si un élément est généré dans une cible, l'élément peut contenir l'attribut d' KeepMetadata . Si cet attribut est spécifié, seuls les métadonnées qui est spécifié dans la liste délimitée par des points-virgules des noms sont transférées de l'élément source vers l'élément cible. Une valeur vide pour cet attribut est équivalente à ne pas le spécifier. L'attribut d' KeepMetadata a été introduit dans le.NET Framework 4,5.

L'exemple suivant indique comment utiliser l'attribut d' KeepMetadata .

<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: 
-->

Attribut de RemoveMetadata

Si un élément est généré dans une cible, l'élément peut contenir l'attribut d' RemoveMetadata . Si cet attribut est spécifié, toutes les métadonnées sont transférées de l'élément source vers l'élément cible exception de les métadonnées dont les noms sont contenus dans la liste délimitée par des points-virgules des noms. Une valeur vide pour cet attribut est équivalente à ne pas le spécifier. L'attribut d' RemoveMetadata a été introduit dans le.NET Framework 4,5.

L'exemple suivant indique comment utiliser l'attribut d' RemoveMetadata .

<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: 
-->

Attribut de KeepDuplicates

Si un élément est généré dans une cible, l'élément peut contenir l'attribut d' KeepDuplicates . KeepDuplicates est un attribut d' Boolean qui spécifie si un élément doit être ajouté au groupe cible si l'élément est un doublon exact d'un élément existant.

Si l'élément de source et cible font inclure la même chose la valeur mais les différentes métadonnées, l'élément est ajouté même si KeepDuplicates a la valeur false. Une valeur vide pour cet attribut est équivalente à ne pas le spécifier. L'attribut d' KeepDuplicates a été introduit dans le.NET Framework 4,5.

L'exemple suivant indique comment utiliser l'attribut d' KeepDuplicates .

<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
-->

Voir aussi

Tâches

Comment : sélectionner des fichiers pour la build

Comment : exclure des fichiers de la build

Comment : afficher une liste d'éléments séparés par des virgules

Référence

Item, élément (MSBuild)

Concepts

Définitions d'éléments

Traitement par lots de MSBuild

Autres ressources

Concepts MSBuild

MSBuild