MSBuild

  • Article

Microsoft Build Engine est une plateforme permettant de générer des applications. Ce moteur, également appelé MSBuild, fournit un schéma XML pour un fichier projet qui contrôle la manière dont la plateforme de génération traite et génère les logiciels. Visual Studio utilise MSBuild, mais MSBuild ne dépend pas de Visual Studio. En appelant msbuild.exe ou dotnet build sur votre fichier projet ou solution, vous pouvez orchestrer et générer des produits dans des environnements où Visual Studio n’est pas installé.

Visual Studio utilise MSBuild pour charger et générer des projets managés. Les fichiers projet de Visual Studio (.csproj, .vbproj, .vcxproj et autres) contiennent du code XML MSBuild qui s’exécute lors de la génération d’un projet avec l’environnement IDE. Les projets Visual Studio importent tous les paramètres et processus de génération nécessaires pour effectuer le travail de développement classique, mais vous pouvez les développer ou les modifier à partir de Visual Studio ou en utilisant un éditeur XML.

Pour installer MSBuild sur un système Windows qui ne dispose pas de Visual Studio, accédez à Build Tools pour Visual Studio sur la page des téléchargements. L’installation de MSBuild par cette méthode vous permet d’obtenir MSBuild.exe.

Pour .NET Core et .NET 5 ou version ultérieure, une autre façon d’obtenir l’équivalent de MSBuild consiste à installer le kit de développement logiciel (SDK) .NET. La commande build .NET dotnet build est disponible avec le SDK .NET sur macOS, Windows ou Linux. La commande build .NET dotnet build est un wrapper mince sur la version .NET Core de MSBuild.exe. Vous pouvez employer l’interface de ligne de commande (CLI) .NET Core, qui utilise MSBuild, pour générer des projets ciblant .NET Core et .NET 5 et ultérieur.

À compter de Visual Studio 2022, quand vous générez des projets dans Visual Studio, la version 64 bits de MSBuild est utilisée.

Pour obtenir des informations sur MSBuild pour C++, consultez MSBuild (C++).

Les exemples suivants illustrent les cas où vous pouvez exécuter des builds en appelant MSBuild à partir de la ligne de commande MSBuild au lieu de l’environnement IDE (environnement de développement intégré) de Visual Studio.

  • Visual Studio n'est pas installé.

  • Vous souhaitez utiliser la version 64 bits de MSBuild et vous utilisez Visual Studio 2019 ou une version antérieure. Cette version MSBuild est généralement inutile, mais elle permet à MSBuild d'accéder à plus de mémoire.

  • Vous souhaitez exécuter une build dans plusieurs processus. Toutefois, vous pouvez utiliser l'IDE pour obtenir le même résultat sur les projets dans C++ et C#.

  • Vous souhaitez modifier le système de génération. Par exemple, vous pouvez souhaiter effectuer les actions suivantes :

    • Prétraitez les fichiers avant qu'ils n'atteignent le compilateur.

    • Copiez les sorties de génération à un autre emplacement.

    • Créez des fichiers compressés à partir des sorties de génération.

    • Procédez à une étape de post-traitement. Par exemple, vous pouvez souhaiter horodater un assembly avec une version différente.

Vous pouvez écrire du code dans l'IDE de Visual Studio, mais les générations s'exécutent à l'aide de MSBuild. Vous pouvez également générer le code dans l’IDE sur un ordinateur de développement, mais exécuter MSBuild à partir de la ligne de commande pour générer du code intégré à partir d’un dépôt source avec la collaboration de plusieurs développeurs.

Notes

Vous pouvez utiliser Azure Pipelines pour compiler, tester et déployer automatiquement votre application. Votre système de génération peut automatiquement exécuter des générations lorsque les développeurs archivent du code (par exemple, dans le cadre d'une stratégie continue d'intégration) ou selon une planification (par exemple, une build nocturne de test de vérification de build). Azure Pipelines compile votre code à l’aide de MSBuild. Pour plus d’informations, consultez Azure Pipelines.

Pour obtenir un tutoriel d’introduction à MSBuild sur Windows, consultez Procédure pas à pas : utilisation de MSBuild.

Utiliser MSBuild dans une invite de commandes

Pour exécuter MSBuild dans une invite de commandes, transmettez un fichier projet à MSBuild.exe, avec les options de ligne de commande appropriées. Les options de ligne de commande vous permettent de définir des propriétés, d'exécuter des cibles spécifiques et de définir d'autres options qui contrôlent le processus de génération. Par exemple, la syntaxe de ligne de commande suivante permet de générer le fichier MyProj.proj avec la propriété Configuration définie sur Debug.

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

MSBuild ne modifie pas son comportement en fonction de l'extension du fichier, mais la convention est d'utiliser des extensions se terminant par proj telles que .csproj, .vcxproj, ou .vbproj, pour le fichier d'entrée principal de MSBuild, appelé « fichier de projet »

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

Important

Avant de télécharger un projet, déterminez la crédibilité du code.

Pour .NET Core et .NET 5 ou version ultérieure, vous utilisez généralement dotnet build pour appeler MSBuild. Consultez dotnet build. Si vous installez uniquement le kit de développement logiciel (SDK) .NET, et non Visual Studio ou Visual Studio Build Tools, vous disposez de MSBuild uniquement via dotnet build.

La ligne de commande dotnet build --help répertorie les options de ligne de commande spécifiques à dotnet build, pas toutes les options de MSBuild.exe, mais vous pouvez toujours utiliser toutes les options de ligne de commande répertoriées dans la référence de ligne de commande MSBuild. Les options qui ne sont pas traitées par dotnet build sont transmises à MSBuild.

Fichier projet

MSBuild utilise un format de fichier projet basé sur XML qui est simple et extensible. Le format du fichier projet MSBuild permet aux développeurs de décrire les éléments qui vont être générés, ainsi que la manière dont ils doivent être générés pour différents systèmes d’exploitation 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 builds puissent être exécutées de façon cohérente sur différents projets du produit.

Le système de build Visual Studio stocke la logique spécifique au projet dans le fichier projet lui-même et utilise des fichiers XML MSBuild importés avec des extensions comme .props et .targets pour définir la logique de génération standard. Les fichiers .props définissent les propriétés MSBuild. Les fichiers .targets définissent les cibles MSBuild. Ces importations sont parfois visibles dans le fichier projet Visual Studio. Toutefois, dans les projets plus récents comme .NET Core, .NET 5 et .NET 6, les importations ne sont pas visibles dans le fichier projet. Au lieu de cela, une référence du kit SDK est affichée, comme dans l’exemple suivant :

<Project Sdk="Microsoft.Net.Sdk">

Il s’agit de projets de style SDK. Quand vous référencez un kit SDK comme le kit SDK .NET, les importations de fichiers .props et .target sont spécifiées implicitement par le kit SDK.

Les sections suivantes décrivent certains éléments de base du format de fichier projet MSBuild. Pour suivre un tutoriel sur la création d’un fichier projet de base, voir Procédure pas à pas : Créer un fichier projet MSBuild à partir de zéro.

Propriétés

Les propriétés sont des paires clé/valeur qui peuvent être utilisées pour configurer les générations. Les propriétés sont déclarées en créant un élément portant 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 pouvez définir une propriété conditionnellement en plaçant un attribut Condition dans l'élément. Le contenu des éléments conditionnels est ignoré, à moins que la condition ait la valeur true. Dans l’exemple suivant, la propriété Configuration est définie si elle ne l’a pas encore été.

<Configuration  Condition=" '$(Configuration)' == '' ">DefaultValue</Configuration>

Les propriétés sont référencées dans tout le fichier projet à l’aide de la syntaxe $(<PropertyName>). Par exemple, vous pouvez référencer les propriétés dans les exemples précédents en utilisant $(BuildDir) et $(Configuration).

Pour plus d’informations sur les propriétés, consultez Propriétés MSBuild.

Éléments

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 regroupés en différents types d’élément selon les noms d’élément définis par l’utilisateur. Ces types d’éléments peuvent être utilisés comme paramètres des tâches, lesquelles utilisent les éléments 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 du type d’élément comme enfant d’un élément ItemGroup. Par exemple, le code suivant crée un type d'élément nommé Compile et composé de deux fichiers.

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

Les types d’élément peuvent être 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 serait référencé avec la syntaxe @(Compile).

Dans MSBuild, les noms d'éléments et des attributs respectent la casse. En revanche, ce n'est pas le cas pour les noms de propriétés, d'items et de métadonnées. L'exemple suivant crée le type d'élément Compile, comPile ou toute autre variation au niveau de la casse, et la valeur « one.cs;two.cs » est affectée au type d'item.

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

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’article Éléments MSBuild.

Tâches

Les tâches sont des unités de code exécutable que les projets MSBuild utilisent pour effectuer des opérations de build. Par exemple, une tâche peut compiler des fichiers d'entrée ou exécuter un outil externe. Les tâches peuvent être réutilisées et partagé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 l’écriture de tâches, voir Écriture de tâches.

MSBuild inclut des tâches courantes que vous pouvez modifier selon vos spécifications. Voici des exemples : Copy, qui copie des fichiers, MakeDir, qui crée des répertoires et Csc, qui compile des fichiers de code source Visual C#. Pour connaître la liste des tâches disponibles et obtenir des informations sur leur utilisation, voir Informations de référence sur les tâches.

Une tâche est exécutée dans un fichier projet MSBuild en créant un élément qui porte le nom de la tâche comme enfant d’un élément Cible. En général, les tâches acceptent les paramètres passés comme des attributs de l’élément. Les propriétés et les éléments MSBuild peuvent être utilisés en tant que paramètres. Par exemple, le code suivant appelle la tâche MakeDir et lui transmet 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 l’article Tâches MSBuild.

Targets

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 d'accroître la lisibilité et de permettre une expansion. 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 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 ensuite la tâche Csc comportant la liste 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 être utilisées pour 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 l’article Targets (Cibles MSBuild).

Journaux d’activité de génération

Vous pouvez consigner les erreurs de build, les avertissements et les messages dans la console ou un autre périphérique de sortie. Pour plus d’informations, consultez Obtention de journaux de génération avec MSBuild.

Utiliser MSBuild dans Visual Studio

Visual Studio utilise le format de fichier de projet MSBuild pour stocker les informations de build des projets managés. Les paramètres de projet ajoutés ou modifiés à l’aide de l’interface Visual Studio sont répercutés dans le fichier .*proj qui est généré pour chaque projet. Visual Studio utilise une instance hébergée de MSBuild pour générer des projets managés. Cela signifie qu’un projet managé peut être généré dans Visual Studio ou au niveau d’une invite de commandes (même si Visual Studio n’est pas installé). Les résultats sont identiques.

Pour suivre un didacticiel sur l’utilisation de MSBuild dans Visual Studio, consultez la Procédure pas à pas : utilisation de MSBuild.

Multi-ciblage

Visual Studio permet de compiler une application pour l’exécuter sur la version de votre choix de .NET Framework ou de .NET Core, y compris .NET 5 ou version ultérieure. Par exemple, vous pouvez compiler une application qui doit s’exécuter sur .NET Framework version 4 sur une plateforme 32 bits. Vous pouvez compiler la même application pour qu’elle s’exécute sur .NET Framework version 4.8 sur une plateforme 64 bits. Le multi-ciblage désigne la possibilité de compiler en plusieurs Frameworks.

Voici une partie des avantages offerts par le multi-ciblage :

  • Vous pouvez développer des applications qui ciblent des versions antérieures de .NET Framework, par exemple les versions 3.5 et 4.7.2.

  • Vous pouvez cibler un profil Framework, qui est un sous-ensemble prédéfini d’une version cible de .NET Framework.

  • Si un service pack pour la version actuelle de .NET Framework est publié, vous pouvez le cibler.

  • Le multi-ciblage garantit qu'une application utilise uniquement les fonctionnalités qui sont disponibles dans le framework et la plateforme cibles.

Pour plus d’informations, consultez l’article Multiciblage de MSBuild.

Personnalisation de la build

MSBuild prend en charge un large éventail de scénarios de génération personnalisés. La plupart des fonctionnalités intégrées peuvent être remplacées ou étendues. Consultez Personnaliser votre build.

Accès à MSBuild par programmation

Si vous développez un outil de génération, vous pouvez appeler MSBuild par programmation à partir d’une application .NET. L’API MSBuild vous permet de contrôler tous les aspects d’un système de génération complexe. MSBuild fournit un package NuGet avec une API complète (l’espace de noms Microsoft.Build) que vous pouvez utiliser à partir d’une application .NET à ces fins. Consultez Utiliser l’API MSBuild.

MSBuild est open source

MSBuild est un projet open source qui accepte les contributions des utilisateurs, tout comme le reste de l’écosystème .NET. Le dépôt contenant la source de MSBuild est disponible dans GitHub : dépôt GitHub MSBuild.

Voir aussi

Intitulé Description
Procédure pas à pas : Créer un fichier projet MSBuild à partir de zéro Indique comment créer de façon incrémentielle un fichier projet de base, en utilisant uniquement un éditeur de texte.
Procédure pas à pas : Utilisation de MSBuild Présente les composantes de MSBuild et indique comment écrire, manipuler et déboguer des projets MSBuild sans fermer l'IDE de Visual Studio.
Concepts MSBuild Présente les quatre composantes de MSBuild : propriétés, éléments, cibles et tâches.
Éléments Décrit les concepts généraux sous-jacents au format de fichier MSBuild et la manière dont les éléments s’ajustent les uns aux autres.
MSBuild (propriétés) Présente les propriétés et les collections de propriétés. Les propriétés sont des paires clé/valeur qui peuvent être utilisées pour configurer les générations.
Cibles Explique comment grouper les tâches dans un ordre particulier et autoriser des sections du processus de génération à être appelées sur la ligne de commande.
Tâches Montre comment créer une unité de code exécutable qui peut être utilisée par MSBuild pour exécuter des opérations de génération atomiques.
Conditions Explique comment utiliser l'attribut Condition dans un élément MSBuild.
Traitement par lot Explique comment MSBuild catégorise les listes d’éléments par métadonnées pour l’exécution dans les tâches et les cibles.
Multiciblage Montre comment cibler plusieurs versions .NET et/ou plusieurs plateformes.
Obtention de journaux de génération Décrit comment consigner des événements, des messages et des erreurs de build.
Comment MSBuild génère des projets Décrit le processus de génération interne utilisé au sein de MSBuild
Créer une tâche personnalisée pour la génération de code Montre comment créer une tâche personnalisée, avec un exemple de code.
Utiliser MSBuild pour générer un client d’API REST Montre comment étendre la build pour gérer la génération de client d’API REST, avec un exemple de code.
Ressources supplémentaires Répertorie les ressources de communauté et de prise en charge pour des informations supplémentaires sur MSBuild.

Informations de référence