Éléments MSBuild

Article
09/04/2008

Mise à jour : novembre 2007

Les éléments représentent les entrées du système de génération qui sont regroupées en collections suivant leurs noms de collections définis par l'utilisateur. Ces collections d'éléments peuvent être utilisées comme paramètres des tâches, lesquelles utilisent les éléments contenus dans la collection pour exécuter les étapes du processus de génération.

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

Les éléments sont déclarés dans le fichier projet en créant un élément qui soit enfant d'un élément ItemGroup portant le nom de l'élément. L'attribut Include de l'élément spécifie quels fichiers inclure avec cette collection d'éléments. Par exemple, le code suivant crée une collection d'éléments nommée Compile et composée de deux fichiers.

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

Le code suivant crée la même collection d'éléments en déclarant les deux fichiers dans un attribut Include, séparés par un point-virgule.

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

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

Vous référencez les collections d'éléments dans le fichier projet avec la syntaxe @(ItemCollectionName). Par exemple, vous référenceriez la collection d'éléments de l'exemple ci-dessus avec @(Compile). Cette syntaxe vous permet de passer des collections d'éléments aux tâches en spécifiant la collection d'éléments en tant que paramètre de cette tâche. Pour plus d'informations, consultez Comment : utiliser des caractères génériques pour générer tous les fichiers dans un répertoire.

Par défaut, les éléments dans les collections d'éléments sont séparés par des points-virgules (;) lorsqu'ils sont développés. Utilisez la syntaxe @(ItemCollectionName', 'séparateur') pour spécifier un séparateur autre que celui par défaut. Pour plus d'informations, consultez Comment : afficher une collection 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 génération au lieu de répertorier chaque fichier séparément. Par exemple, pour spécifier tous les fichiers .cs ou .vb dans le même répertoire que le fichier projet, utilisez l'un des éléments suivants dans votre fichier projet :

- ou -

Remarque :
Vous pouvez uniquement utiliser des caractères génériques avec les éléments pour spécifier les entrées pour une génération. Par exemple, vous ne pouvez pas utiliser de caractères génériques pour spécifier les entrées au paramètre Sources dans la tâche Csc. MSBuild acceptera les caractères génériques comme valeurs de paramètre, mais les traitera comme littéraux de chaîne et ne les évaluera pas. L'exemple suivant utiliserait le littéral de chaîne .cs comme la valeur du paramètre Sources*.

Vous pouvez uniquement utiliser des caractères génériques avec les éléments pour spécifier les entrées pour une génération. Par exemple, vous ne pouvez pas utiliser de caractères génériques pour spécifier les entrées au paramètre Sources dans la tâche Csc. MSBuild acceptera les caractères génériques comme valeurs de paramètre, mais les traitera comme littéraux de chaîne et ne les évaluera pas. L'exemple suivant utiliserait le littéral de chaîne *.cs comme la valeur du paramètre Sources.

<Target Name="Compile">
    <CSC Sources="*.cs" />
</Target>

Pour plus d'informations sur les caractères génériques, consultez Comment : utiliser des caractères génériques pour générer tous les fichiers dans un répertoire.

Utilisation de l'attribut Exclude

Les éléments peuvent également contenir l'attribut Exclude qui exclut des fichiers spécifiques de la collection d'éléments. L'attribut Exclude est utile lorsqu'il est utilisé conjointement à des caractères génériques. Par exemple, le code suivant ajoute tous les fichiers .cs dans le répertoire à l'exception du fichier DoNotBuild.cs.

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

Pour plus d'informations, consultez Comment : générer tous les fichiers dans un répertoire sauf un.

Métadonnées d'élément

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

Les métadonnées d'éléments sont déclarées dans le fichier projet en créant un élément portant le nom des métadonnées en tant qu'élément enfant de l'élément. Un élément peut avoir plusieurs valeurs de métadonnées ou n'en avoir aucune. Par exemple, l'élément suivant a des métadonnées Culture dont la valeur est Fr.

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

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

Vous référencez les métadonnées d'éléments dans le fichier projet avec la syntaxe %(ItemMetadataName). Lorsque l'ambiguïté existe, elles peuvent être qualifiées par le nom de la collection d'éléments, par exemple %(ItemCollectionName.ItemMetaDataName). L'exemple suivant utilise les métadonnées Display pour traiter par lots la tâche Message. Pour plus d'informations sur l'utilisation de métadonnées d'éléments pour le traitement par lots, consultez Comment : traiter des tâches par lots avec des métadonnées d'élément.

<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

Chaque fois qu'un élément est ajouté dans une collection d'éléments, celui-ci est créé et reçoit des métadonnées d'éléments connus, tels que %(Nom de fichier), qui contiennent le nom de fichier de l'élément. Pour la liste complète des métadonnées d'éléments connus, consultez Métadonnées d'éléments connus MSBuild.

Transformation des collections d'éléments

Les collections d'éléments peuvent être transformées en collections d'autres éléments. Par exemple, une collection de fichiers .cpp peut être transformée en une collection de fichiers .obj à l'aide d'une expression telle que @(CppFiles -> '%(Filename).obj'). Pour plus d'informations, consultez Transformations MSBuild.

Voir aussi

Partager via