Vue d'ensemble de MSBuild

Article
08/21/2008

Mise à jour : novembre 2007

Microsoft Build Engine (MSBuild) est la nouvelle plateforme de génération pour Microsoft et Visual Studio. MSBuild fonctionne de façon transparente quant au traitement et à la génération de logiciels, ce qui permet aux développeurs de concevoir et de créer des produits dans des environnements de laboratoire de génération où Visual Studio n'est pas installé. Cette rubrique fournit une brève vue d'ensemble des points suivants :

Éléments de base d'un fichier projet MSBuild.
Mode d'utilisation de MSBuild pour générer les projets.
Fonctionnalités avancées de MSBuild.
Utilisation de MSBuild par Visual Studio pour générer des projets.

Fichier projet

MSBuild introduit un nouveau format de fichier projet XML, simple à comprendre, facile à étendre et intégralement pris en charge par Microsoft. Le format du fichier projet MSBuild permet aux développeurs de décrire intégralement les éléments à générer, ainsi que la façon dont ils doivent l'être en fonction des différentes plateformes et configurations. De plus, le format de fichier projet permet aux développeurs de créer des règles de génération réutilisables qui peuvent être réparties en fichiers distincts, de telle sorte que les générations puissent être exécutées de façon cohérente sur différents projets du produit. Les sections suivantes décrivent quelques-uns des éléments de base du format de fichier projet MSBuild.

Éléments

Les éléments représentent les entrées du système de génération et sont regroupés en collections dont les noms sont 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.

Les éléments sont déclarés dans le fichier projet en créant un élément avec le nom de la collection d'éléments comme enfant d'un élément ItemGroup. 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>

Vous référencez les collections d'éléments dans le fichier projet avec la syntaxe @(ItemCollectionName). Par exemple, vous référencez la collection d'éléments de l'exemple ci-dessus de la façon suivante : @(Compile).

Les éléments peuvent être déclarés à l'aide de caractères génériques et peuvent contenir des métadonnées supplémentaires dans le cas de scénarios de génération plus avancés. Pour plus d'informations sur les éléments, consultez Éléments MSBuild.

Propriétés

Les propriétés sont des paires clé/valeur qui peuvent être utilisées pour configurer les générations. Il existe plusieurs différences entre les éléments et les propriétés :

Les éléments sont stockés dans des collections tandis que les propriétés contiennent une seule valeur scalaire.
Les éléments ne peuvent pas être supprimés des collections d'éléments tandis que les valeurs des propriétés peuvent être modifiées après qu'elles ont été définies.
Les éléments peuvent contenir des métadonnées et utiliser la notation %(ItemMetadata), ce qui n'est pas le cas des propriétés.

Les propriétés sont déclarées en créant un élément avec le nom de la propriété comme enfant d'un élément PropertyGroup. Par exemple, le code suivant crée une propriété nommée BuildDir avec la valeur Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Vous référencez les propriétés dans la totalité du fichier projet avec la syntaxe $(PropertyName). Par exemple, vous référencez la propriété de l'exemple précédent avec $(BuildDir). Pour plus d'informations sur les propriétés, consultez Propriétés MSBuild.

Tâches

Les tâches sont des unités de code exécutable réutilisables auxquelles les projets MSBuild ont recours pour exécuter des opérations de génération. Par exemple, une tâche peut compiler des fichiers d'entrée ou exécuter un outil externe. Une fois créées, les tâches peuvent être partagées et réutilisées par plusieurs développeurs dans différents projets.

La logique d'exécution d'une tâche est écrite en code managé et mappée à MSBuild avec l'élément UsingTask. Vous pouvez écrire votre propre tâche en créant un type managé qui implémente l'interface ITask. Pour plus d'informations sur les tâches d'écriture, consultez Comment : écrire une tâche.

MSBuild est fourni avec plusieurs tâches courantes, telles que Copy, qui copie les fichiers, MakeDir, qui crée des répertoires et Csc, qui compile les fichiers de code source Visual C#. Pour obtenir la liste complète des tâches disponibles et des informations sur leur utilisation, consultez Référence des tâches MSBuild.

Vous pouvez exécuter une tâche dans un fichier projet MSBuild en créant un élément avec le nom de la tâche comme enfant d'un élément Target. Les tâches acceptent généralement des paramètres, qui sont passés en tant qu'attributs de l'élément. Les propriétés et les collections d'élément MSBuild peuvent être utilisées en tant que paramètres. Par exemple, le code suivant appelle la tâche MakeDir et lui passe la valeur de la propriété BuildDir déclarée dans l'exemple précédent.

<Target Name="MakeBuildDirectory">
    <MakeDir
        Directories="$(BuildDir)" />
</Target>

Pour plus d'informations sur les tâches, consultez Tâches MSBuild.

Cibles

Les cibles regroupent les tâches selon un ordre particulier et exposent les sections du fichier projet comme points d'entrée du processus de génération. Les cibles sont souvent groupées en sections logiques afin de permettre un agrandissement et d'accroître la lisibilité. L'éclatement des étapes de génération en plusieurs cibles permet d'appeler une partie du processus de génération à partir d'autres cibles sans devoir copier cette section de code dans chaque cible. Par exemple, si plusieurs points d'entrée du processus de génération requièrent la génération de références, vous pouvez créer une cible qui génère les références et exécuter cette cible à partir de chaque point d'entrée nécessaire.

Les cibles sont déclarées dans le fichier projet avec l'élément Target. Par exemple, le code suivant crée une cible nommée Compile, qui appelle la tâche Csc avec la collection d'éléments déclarée dans l'exemple précédent.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

Dans des scénarios plus avancés, les cibles peuvent décrire les relations entre chacune d'elles et exécuter une analyse de dépendance, qui permet d'ignorer des sections entières du processus de génération si la cible correspondante est à jour. Pour plus d'informations sur les cibles, consultez Cibles de MSBuild.

Génération avec MSBuild

Vous pouvez exécuter MSBuild à partir de la ligne de commande en passant un fichier projet à MSBuild.exe, avec les options de ligne de commande appropriées. Les options de ligne de commande permettent de définir des propriétés, d'exécuter des cibles spécifiques et de spécifier des journaux. Par exemple, vous utilisez la syntaxe de ligne de commande suivante pour générer le fichier MyProj.proj avec la propriété Configuration ayant Debug comme valeur.

MSBuild.exe MyProj.proj /property:Configuration=Debug

Pour plus d'informations sur les options de ligne de commande MSBuild, consultez Référence de la ligne de commande MSBuild.

Note de sécurité :
Avant de générer un projet téléchargé, déterminez la fiabilité du code. Les fichiers projet MSBuild ont la capacité d'exécuter des tâches susceptibles d'endommager votre système.

Concepts avancés

MSBuild peut être utilisé pour des opérations plus avancées lors des générations, comme l'enregistrement des erreurs, des avertissements et autres messages dans la console ou dans des journaux, l'exécution d'une analyse de dépendance sur les cibles et le traitement par lots des tâches et des cibles sur les métadonnées d'élément. Pour plus d'informations sur ces concepts avancés, consultez Concepts avancés de MSBuild.

Intégration Visual Studio

Visual Studio utilise le format de fichier projet MSBuild pour stocker les informations de génération des projets managés. Les paramètres de projet ajoutés et modifiés via Visual Studio sont reflétés dans le fichier .*proj généré pour chaque projet. Visual Studio utilise une instance hébergée de MSBuild pour générer des projets managés, ce qui signifie qu'un projet managé peut être généré dans Visual Studio et à partir de la ligne de commande (même si Visual Studio n'est pas installé), avec des résultats identiques. Pour plus d'informations sur la façon dont Visual Studio utilise MSBuild, consultez Concepts avancés de MSBuild.