Tutoriel : Utiliser MSBuild

MSBuild est la plateforme de génération pour Microsoft et Visual Studio. Ce tutoriel vous présente les blocs de construction de MSBuild et vous montre comment écrire, manipuler et déboguer des projets MSBuild. Vous apprendrez à propos de :

• Création et manipulation d’un fichier projet.

• Comment utiliser les propriétés de build.

• Comment utiliser des éléments de build.

Vous pouvez exécuter MSBuild à partir de Visual Studio ou à partir de la fenêtre de commande . Dans ce tutoriel, vous allez créer un fichier projet MSBuild à l’aide de Visual Studio. Vous modifiez le fichier projet dans Visual Studio et utilisez la fenêtre de commande pour générer le projet et examiner les résultats.

Installer MSBuild

Si vous avez Visual Studio, alors vous avez déjà MSBuild d'installé. Avec Visual Studio 2022, il est installé sous le dossier d’installation de Visual Studio. Pour une installation par défaut classique sur Windows 10, MSBuild.exe se trouve sous le dossier d’installation dans MSBuild\Current\Bin.

Dans le programme d’installation de Visual Studio, accédez à Composants Individuels, et recherchez la case à cocher MSBuild. Il est automatiquement sélectionné lorsque vous choisissez l’une des autres charges de travail à installer.

Pour installer MSBuild sur un système qui n’a pas Visual Studio, accédez à Build Tools pour Visual Studio 2022 sur la page de téléchargements . Une autre façon d’obtenir MSBuild consiste à installer le Kit de développement logiciel (SDK) .NET .

Créer un projet MSBuild

Le système de projet Visual Studio est basé sur MSBuild. Il est facile de créer un fichier projet à l’aide de Visual Studio. Dans cette section, vous allez créer un fichier projet C#. Vous pouvez choisir de créer un fichier projet Visual Basic à la place. Dans le contexte de ce didacticiel, la différence entre les deux fichiers projet est mineure.

Pour créer un fichier projet

1. Ouvrez Visual Studio et créez un projet :

   Dans la zone de recherche, tapez winforms, puis choisissez Créer une application Windows Forms (.NET Framework). Dans la boîte de dialogue qui s’affiche, choisissez Créer.

   Dans la zone Nom du projet, tapez BuildApp. Entrez un Emplacement pour la solution, par exemple : D:\.

2. Cliquez sur OK ou Créer pour créer le fichier projet.

Examiner le fichier projet

Dans la section précédente, vous avez utilisé Visual Studio pour créer un fichier projet C#. Le fichier projet est représenté dans l’Explorateur de solutions par le nœud de projet nommé BuildApp. Vous pouvez utiliser l’éditeur de code Visual Studio pour examiner le fichier projet.

Pour examiner le fichier projet

1. Dans Explorateur de solutions, cliquez sur le nœud du projet BuildApp.

2. Dans le navigateur Propriétés, notez que la propriété Fichier projet s’appelle BuildApp.csproj. Tous les fichiers projet sont nommés avec le suffixe proj. Si vous aviez créé un projet Visual Basic, le nom du fichier projet serait BuildApp.vbproj.

3. Cliquez à nouveau avec le bouton droit sur le nœud du projet, puis cliquez sur Modifier buildApp.csproj.

   Le fichier projet apparaît dans l’éditeur de code.

Remarque

Pour certains types de projet, tels que C++, vous devez décharger le projet (cliquez avec le bouton droit sur le fichier projet et choisissez décharger le projet) avant de pouvoir ouvrir et modifier le fichier projet.

Cibles et tâches

Les fichiers projet sont des fichiers au format XML avec le nœud racine Project.

La plupart des projets .NET ont un attribut Sdk. Ces projets sont appelés projets de style SDK. Le référencement d’un KIT de développement logiciel (SDK) signifie que MSBuild importe un ensemble de fichiers qui fournissent l’infrastructure de build pour ce KIT SDK. Si vous ne référencez aucun SDK, vous pouvez toujours utiliser MSBuild, mais vous n’avez pas automatiquement toutes les propriétés et cibles spécifiques au Kit de développement logiciel (SDK) disponibles.

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

Il existe de nombreuses variantes des kits SDK .NET à des fins spéciales ; ils sont décrits dans kits SDK .NET Project.

Le processus de création d’une application est effectué avec les éléments Cible et Tâche.

• Une tâche est la plus petite unité de travail, en d’autres termes, l'« atome » d’une construction. Les tâches sont des composants exécutables indépendants, qui peuvent avoir des entrées et des sorties. Aucune tâche n’est actuellement référencée ou définie dans le fichier projet. Vous ajoutez des tâches au fichier projet dans les sections suivantes. Pour plus d’informations, consultez Tâches.

• Une cible est une séquence nommée de tâches. Il peut s’agir d’une séquence nommée de tâches, mais de manière critique, il représente quelque chose à créer ou à faire. Il doit donc être défini de manière orientée objectif. Pour plus d’informations, consultez l’article Cibles.

La cible par défaut n’est pas définie dans le fichier projet. Au lieu de cela, elle est spécifiée dans les projets importés. L’élément import spécifie les projets importés. Par exemple, dans un projet C#, la cible par défaut est importée à partir du fichier Microsoft.CSharp.targets.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

Les fichiers importés sont insérés efficacement dans le fichier projet où qu’ils soient référencés.

Dans les projets de style SDK, vous ne voyez pas cet élément d’importation, car l’attribut sdk entraîne l’importation implicite de ce fichier.

MSBuild effectue le suivi des cibles d’une build et garantit que chaque cible n’est générée qu’une seule fois.

Ajouter une cible et une tâche

Ajoutez une cible au fichier projet. Ajoutez une tâche à la cible qui imprime un message.

Ajouter une cible et une tâche

1. Ajoutez ces lignes au fichier projet, juste après l’instruction Import ou l’élément Project ouvrant.

   <Target Name="HelloWorld">
   </Target>
   

   Ce code crée une cible nommée HelloWorld. Notez qu’IntelliSense est activé quand vous modifiez le fichier projet.

2. Ajoutez des lignes à la cible HelloWorld afin que la section résultante ressemble à ceci :

   <Target Name="HelloWorld">
     <Message Text="Hello"></Message>
     <Message Text="World"></Message>
   </Target>
   

3. Enregistrez le fichier projet.

La tâche Message est l’une des nombreuses tâches fournies avec MSBuild. Pour obtenir la liste complète des tâches disponibles et des informations d’utilisation, consultez référence de tâche.

La tâche Message prend la valeur de chaîne de l’attribut Text comme entrée et l’affiche sur le périphérique de sortie (ou l’écrit dans un ou plusieurs logs, le cas échéant). La cible HelloWorld exécute la tâche 'Message' à deux reprises : d'abord pour afficher « Bonjour », puis pour afficher « Monde ».

Générer la cible

Si vous essayez de générer ce projet à partir de Visual Studio, il ne génère pas la cible que vous avez définie. C’est parce que Visual Studio choisit la cible par défaut, qui est toujours celle du fichier .targets importé.

Exécutez MSBuild à partir de l’Invite de commandes développeur pour Visual Studio pour générer la cible HelloWorld définie précédemment. Utilisez le commutateur de ligne de commande -target ou -t pour sélectionner la cible.

Note

Dans les sections suivantes, nous désignerons l’Invite de commandes développeur par fenêtre Commande.

Pour générer la cible :

1. Ouvrez la fenêtre de commande .

   Dans la zone de recherche de la barre des tâches, commencez à taper le nom de l’outil, tel que dev ou developer command prompt. Une liste d’applications installées qui correspondent à votre modèle de recherche s’affiche.

   Si vous devez le trouver manuellement, le fichier est LaunchDevCmd.bat dans le dossier {Dossier d’installation de Visual Studio}\Common7\Tools dossier.

2. Dans la fenêtre de commande, accédez au dossier contenant le fichier projet, dans ce cas, D :\BuildApp\BuildApp.

3. Exécutez msbuild avec le commutateur de commandes -t:HelloWorld. Cette commande sélectionne et génère la cible HelloWorld :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie dans la fenêtre commande . Vous devez voir les deux lignes « Hello » et « World » :

   Hello
   World
   

Note

Si vous voyez plutôt The target "HelloWorld" does not exist in the project, vous avez probablement oublié d’enregistrer le fichier projet dans l’éditeur de code. Enregistrez le fichier et réessayez.

En alternant entre l’éditeur de code et la fenêtre de commande, vous pouvez modifier le fichier projet et afficher rapidement les résultats.

Propriétés de build

Les propriétés de compilation sont des paires nom-valeur qui orientent le processus de compilation. Plusieurs propriétés de build sont déjà définies en haut du fichier projet :

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

Toutes les propriétés sont des éléments enfants des éléments PropertyGroup. Le nom de la propriété est le nom de l’élément enfant, et la valeur de la propriété est l’élément de texte de l’élément enfant. Par exemple

<TargetFrameworkVersion>net8.0</TargetFrameworkVersion>

définit la propriété nommée TargetFrameworkVersion, en lui donnant la valeur de chaîne « net8.0 »

Les propriétés de construction peuvent être redéfinies à tout moment. Si

<TargetFrameworkVersion>net6.0</TargetFrameworkVersion>

apparaît ultérieurement dans le fichier projet, ou dans un fichier importé ultérieurement dans le fichier projet, puis TargetFrameworkVersion prend la nouvelle valeur « net6.0 »

Examiner une valeur de propriété

Pour obtenir la valeur d’une propriété, utilisez la syntaxe suivante, où PropertyName est le nom de la propriété :

$(PropertyName)

Utilisez cette syntaxe pour examiner certaines des propriétés du fichier projet.

Pour examiner une valeur de propriété

1. À partir de l’éditeur de code, remplacez la cible HelloWorld par ce code :

   <Target Name="HelloWorld">
     <Message Text="Configuration is $(Configuration)" />
     <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
   </Target>
   

2. Enregistrez le fichier projet.

3. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez le résultat. Vous devez voir ces deux lignes (votre sortie peut différer) :

   Configuration is Debug
   MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\2022\MSBuild\Current\Bin\amd64
   

Propriétés conditionnelles

De nombreuses propriétés telles que Configuration sont définies de manière conditionnelle, autrement dit, l’attribut Condition apparaît dans l’élément de propriété. Les propriétés conditionnelles sont définies ou redéfinies uniquement si la condition prend la valeur « true ». Les propriétés non définies reçoivent la valeur par défaut d’une chaîne vide. Par exemple

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

signifie « Si la propriété Configuration n’a pas encore été définie, définissez-la et donnez-lui la valeur « Déboguer ».

Presque tous les éléments MSBuild peuvent avoir un attribut Condition. Pour plus d’informations sur l’utilisation de l’attribut Condition, consultez Conditions.

Propriétés réservées

MSBuild réserve certains noms de propriétés pour stocker des informations sur le fichier projet et les fichiers binaires MSBuild. MSBuildToolsPath est un exemple de propriété réservée. Les propriétés réservées sont référencées avec la notation $ comme n’importe quelle autre propriété. Pour plus d’informations, consultez Guide pratique pour référencer le nom ou l’emplacement du fichier projet et Propriétés réservées et connues de MSBuild.

Variables d’environnement

Vous pouvez référencer des variables d’environnement dans les fichiers projet de la même façon que les propriétés de build. Par exemple, pour utiliser la variable d’environnement PATH dans votre fichier projet, utilisez $(Path). Si le projet contient une définition de propriété portant le même nom qu’une variable d’environnement, la propriété du projet remplace la valeur de la variable d’environnement. Pour plus d’informations, consultez Comment utiliser des variables d'environnement dans une build.

Définir des propriétés à partir de la ligne de commande

Les propriétés peuvent être définies sur la ligne de commande à l’aide du commutateur de ligne de commande -property ou -p. Les valeurs de propriété reçues de la ligne de commande remplacent les valeurs de propriété définies dans le fichier projet et les variables d’environnement.

Pour définir une valeur de propriété à partir de la ligne de commande :

1. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld -p:Configuration=Release
   

2. Examinez le résultat. Vous devez voir cette ligne :

   Configuration is Release.
   

MSBuild crée la propriété Configuration et lui donne la valeur « Release ».

Caractères spéciaux

Certains caractères ont une signification particulière dans les fichiers projet MSBuild. Par exemple, ces caractères incluent des points-virgules (;) et des astérisques (*). Pour utiliser ces caractères spéciaux comme littéraux dans un fichier projet, ils doivent être spécifiés à l’aide de la syntaxe %<xx>, où <xx> représente la valeur hexadécimale ASCII du caractère.

Modifiez la tâche Message pour afficher la valeur de la propriété Configuration avec des caractères spéciaux pour le rendre plus lisible.

Pour utiliser des caractères spéciaux dans la tâche message :

1. À partir de l’éditeur de code, remplacez les deux tâches message par cette ligne :

   <Message Text="%24(Configuration) is %22$(Configuration)%22" />
   

2. Enregistrez le fichier projet.

3. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez le résultat. Vous devez voir cette ligne :

   $(Configuration) is "Debug"
   

Pour plus d'informations, consultez les caractères spéciaux MSBuild .

Générer des éléments

Un élément est une information, généralement un nom de fichier, utilisé comme entrée dans le système de génération. Par exemple, une collection d’éléments représentant des fichiers sources peut être passée à une tâche nommée Compile pour les compiler dans un assembly.

Tous les éléments sont des éléments enfants des éléments ItemGroup. Le nom de l’élément est le nom de l’élément enfant, et la valeur de l’élément est la valeur de l’attribut Include de l’élément enfant. Les valeurs des éléments qui ont le même nom sont regroupées en types d’éléments de ce nom. Par exemple

<ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>

définit un groupe d’éléments contenant deux éléments. Le type d’élément Compile a deux valeurs : Program.cs et Properties\AssemblyInfo.cs.

Le code suivant crée le même type d’élément en déclarant les deux fichiers dans un attribut Include, séparés par un point-virgule.

<ItemGroup>
    <Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>

Pour plus d’informations, consultez l’article Éléments.

Note

Les chemins d’accès aux fichiers sont relatifs au dossier contenant le fichier projet MSBuild, même si le fichier projet est un fichier projet importé. Il existe quelques exceptions à cela, par exemple lors de l’utilisation des éléments Import et UsingTask.

Examiner les valeurs de type d’élément

Pour obtenir les valeurs d’un type d’élément, utilisez la syntaxe suivante, où ItemType est le nom du type d’élément :

@(ItemType)

Utilisez cette syntaxe pour examiner le type d’élément Compile dans le fichier projet.

Pour examiner les valeurs de type d’élément :

1. À partir de l’éditeur de code, remplacez la tâche cible HelloWorld par ce code :

   <Target Name="HelloWorld">
     <Message Text="Compile item type contains @(Compile)" />
   </Target>
   

2. Enregistrez le fichier projet.

3. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez le résultat. Vous devez voir cette longue ligne :

   Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs
   

Les valeurs d’un type d’élément sont séparées par des points-virgules par défaut.

Pour modifier le séparateur d’un type d’élément, utilisez la syntaxe suivante, où ItemType est le type d’élément et séparateur est une chaîne d’un ou plusieurs caractères de séparation :

@(ItemType, Separator)

Modifiez la tâche Message pour utiliser les retours à la ligne et les sauts de ligne (%0A%0D) afin d'afficher un élément Compile par ligne.

Pour afficher les valeurs de type d’élément une par ligne

1. À partir de l’éditeur de code, remplacez la tâche Message par cette ligne :

   <Message Text="Compile item type contains @(Compile, '%0A%0D')" />
   

2. Enregistrez le fichier projet.

3. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez le résultat. Vous devez voir ces lignes :

   Compile item type contains Form1.cs
   Form1.Designer.cs
   Program.cs
   Properties\AssemblyInfo.cs
   Properties\Resources.Designer.cs
   Properties\Settings.Designer.cs
   

Inclure, Exclure et caractères génériques

Vous pouvez utiliser les caractères génériques « * », « ** » et « ? » avec l’attribut Include pour ajouter des éléments à un type d’élément. Par exemple

<Photos Include="images\*.jpeg" />

ajoute tous les fichiers avec l'extension de fichier .jpeg au dossier images pour le type d'élément Photos, tandis que

<Photos Include="images\**\*.jpeg" />

ajoute tous les fichiers avec l’extension de fichier .jpeg dans les images dossier, et tous ses sous-dossiers, au type d’élément Photos. Pour plus d’exemples, consultez Guide pratique pour sélectionner les fichiers à générer.

Notez que lorsque les éléments sont déclarés, ils sont ajoutés au type d’élément. Par exemple

<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />

crée un type d’élément nommé Photo qui contient tous les fichiers dans le dossier d'images ayant pour extension de fichier .jpeg ou .gif. Ces lignes sont équivalentes à la ligne suivante :

<Photos Include="images\*.jpeg;images\*.gif" />

Vous pouvez exclure un élément d’un type d’élément avec l’attribut Exclude. Par exemple

<Compile Include="*.cs" Exclude="*Designer*">

ajoute tous les fichiers avec l’extension de fichier .cs au type d’élément Compile, à l’exception des fichiers dont les noms contiennent la chaîne Designer. Pour plus d’exemples, consultez Guide pratique pour exclure des fichiers de la build.

L’attribut Exclude affecte uniquement les éléments ajoutés par l’attribut Include dans l’élément d’élément qui les contient les deux. 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 précédent.

Pour inclure et exclure des éléments

1. À partir de l’éditeur de code, remplacez la tâche Message par cette ligne :

   <Message Text="XFiles item type contains @(XFiles)" />
   

2. Ajoutez ce groupe d’éléments juste après l’élément Import :

   <ItemGroup>
      <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
   </ItemGroup>
   

3. Enregistrez le fichier projet.

4. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

5. Examinez le résultat. Vous devez voir cette ligne :

   XFiles item type contains Form1.cs;Program.cs;Properties/Resources.resx
   

Métadonnées de l’élément

Les éléments peuvent contenir des métadonnées en plus des informations collectées à partir des attributs Include et Exclude. Les tâches qui nécessitent plus d’informations sur les éléments que la valeur de l’élément peuvent utiliser ces métadonnées.

Les métadonnées d’élément 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 zéro ou plusieurs valeurs de métadonnées. Par exemple, l’élément CSFile suivant a des métadonnées culture avec la valeur « Fr » :

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

Pour obtenir la valeur des métadonnées d’un type d’élément, utilisez la syntaxe suivante, où ItemType est le nom du type d’élément et MetaDataName est le nom des métadonnées :

%(ItemType.MetaDataName)

Pour examiner les métadonnées d’élément :

1. À partir de l’éditeur de code, remplacez la tâche Message par cette ligne :

   <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />
   

2. Enregistrez le fichier projet.

3. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez le résultat. Vous devez voir ces lignes :

   Compile.DependentUpon:
   Compile.DependentUpon: Form1.cs
   Compile.DependentUpon: Resources.resx
   Compile.DependentUpon: Settings.settings
   

Notez que l’expression « Compile.DependentUpon » s’affiche plusieurs fois. L’utilisation de métadonnées avec cette syntaxe au sein d’une cible provoque le « traitement par lots ». Le traitement par lots signifie que les tâches au sein de la cible sont exécutées une fois pour chaque valeur de métadonnées unique. Le batching est l'équivalent dans les scripts MSBuild de la structure de programmation commune "boucle foreach". Pour plus d’informations, consultez l’article Traitement par lot.

Métadonnées connues

Chaque fois qu’un élément est ajouté à une liste d’éléments, cet élément reçoit des métadonnées connues. Par exemple, %(Filename) retourne le nom de fichier d’un élément. Pour obtenir la liste complète des métadonnées connues, consultez l’article Métadonnées d'éléments connus.

Pour examiner les métadonnées connues :

1. À partir de l’éditeur de code, remplacez la tâche Message par cette ligne :

   <Message Text="Compile Filename: %(Compile.Filename)" />
   

2. Enregistrez le fichier projet.

3. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez le résultat. Vous devez voir ces lignes :

   Compile Filename: Form1
   Compile Filename: Form1.Designer
   Compile Filename: Program
   Compile Filename: AssemblyInfo
   Compile Filename: Resources.Designer
   Compile Filename: Settings.Designer
   

En comparant les deux exemples précédents, vous pouvez constater que, bien que tous les éléments du type Compile n'aient pas de métadonnées DependentUpon, ils ont tous les métadonnées bien connues de nom de fichier.

Transformations de métadonnées

Les listes d’éléments peuvent être transformées en nouvelles listes d’éléments. Pour transformer une liste d’éléments, utilisez la syntaxe suivante, où <ItemType> est le nom du type d’élément et <MetadataName> est le nom des métadonnées :

@(ItemType -> '%(MetadataName)')

Par exemple, une liste d’éléments de fichiers sources peut être transformée en une collection de fichiers objet à l’aide d’une expression telle que @(SourceFiles -> '%(Filename).obj'). Pour plus d’informations, consultez Transforms.

Pour transformer des éléments à l’aide de métadonnées :

1. À partir de l’éditeur de code, remplacez la tâche Message par cette ligne :

   <Message Text="Backup files: @(Compile->'%(filename).bak')" />
   

2. Enregistrez le fichier projet.

3. À partir de la fenêtre de commande , entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez le résultat. Vous devez voir cette ligne :

   Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
   

Notez que les métadonnées exprimées dans cette syntaxe ne provoquent pas de traitement par lots.

Étapes suivantes

Pour savoir comment créer un fichier projet simple une étape à la fois, sur Windows, essayez Créer un fichier projet MSBuild à partir de zéro.

Si vous utilisez principalement le Kit de développement logiciel (SDK) .NET, veuillez poursuivre la lecture de la section Référence MSBuild pour les projets SDK .NET.

Contenu connexe

• Vue d’ensemble de MSBuild
• Informations de référence sur MSBuild