Éléments MSBuild
Les éléments sont des entrées du système de génération qui 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 du type d'élément auquel ils appartiennent, les termes « élément » et « valeur d'élément » peuvent être utilisés indifféremment.
Création d'éléments dans un fichier projet
Les éléments sont déclarés dans le fichier projet en tant qu'éléments enfants d'un élément 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 comprenant 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, il est ajouté à la liste de valeurs du type d'élément Compile. Un élément ne peut pas être supprimé 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
Des valeurs sont assignées aux éléments positionnés en dehors des éléments Target 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 comme suit :
Les éléments peuvent être émis par n'importe quelle tâche. Pour émettre un élément, l'élément Task doit avoir un élément enfant Output ayant un attribut ItemName.
Les éléments peuvent être émis par la tâche CreateItem. 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
Les types d'élément sont référencés dans tout le fichier projet à l'aide de la syntaxe @(ItemType). Par exemple, le type d'élément dans l'exemple précédent serait référencé à l'aide de @(Compile). Cette syntaxe vous permet de passer des éléments aux tâches en spécifiant le type d'élément en tant que 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 même type sont séparés par des points-virgules (;) lorsqu'il est développé. Utilisez la syntaxe @(ItemType, 'séparateur') pour spécifier un séparateur autre que celui 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, pour spécifier tous les fichiers .cs situés dans le répertoire contenant le fichier projet, utilisez l'élément suivant dans votre fichier projet.
<CSFile Include="*.cs"/>
Un élément qui sélectionne tous les fichiers .vb sur le lecteur D: serait
<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>
L'attribut Exclude affecte seulement les éléments ajoutés par l'attribut Include dans l'élément item qui les contient. Par exemple :
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
n'exclurait pas le fichier Form1.cs, qui a été ajouté dans l'élément item précédent.
Pour plus d'informations, consultez Comment : exclure des fichiers de la build.
Utilisation de l'attribut Remove
À compter de .NET Framework 3.5, les éléments Target peuvent contenir des éléments ItemGroup pouvant contenir des éléments item. Ces éléments item peuvent contenir l'attribut Remove qui supprime des éléments (fichiers) spécifiques du type d'élément. Par exemple, le code XML suivant supprime chaque fichier .config du type d'élément Compile.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
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 des informations supplémentaires sur les éléments, ou pour le traitement par lot des tâches et des cibles. Pour plus d'informations sur le traitement par lot, 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 Culture qui ont la valeur Fr aux éléments « one.cs » et « 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. Les valeurs des métadonnées peuvent être modifiées à tout moment. L'affectation d'une valeur vide à des métadonnées contribue à les supprimer efficacement de la build.
Référencement de métadonnées d'éléments dans un fichier projet
Les métadonnées d'élément sont référencées dans tout le fichier projet à l'aide de la syntaxe %(ItemMetadataName). Lorsqu'il existe une ambiguïté, vous pouvez les qualifier à l'aide du nom du type d'élément, par exemple %(ItemType.ItemMetaDataName). L'exemple suivant utilise les métadonnées Display pour le traitement par lot de 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 correspond au nom de fichier de l'élément. Pour obtenir la liste des métadonnées d'éléments connus, consultez Métadonnées d'éléments connus MSBuild.
Transformation de types d'élément à l'aide de métadonnées
Les listes d'éléments peuvent être transformées en nouvelles listes d'éléments à l'aide de métadonnées. Par exemple, un type d'élément CppFiles qui a des éléments représentant des fichiers .cpp peut être transformé en 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, l'élément ItemDefinitionGroup vous permet d'ajouter des métadonnées par défaut à tout type d'élément. À l'instar des métadonnées connues, les métadonnées par défaut sont associées à tous les éléments d'un type spécifié. Les métadonnées par défaut peuvent être substituées explicitement dans une définition d'élément. Par exemple, le code XML suivant affecte aux éléments Compile « one.cs » et « three.cs » les métadonnées BuildDay avec la valeur « Monday » et affecte à l'élément « two.cs » les métadonnées BuildDay avec la valeur « Tuesday ».
<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.
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
Concepts
Traitement par lots de MSBuild