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 MSBuild et vous indique comment écrire, manipuler et déboguer des projets MSBuild. Vous en apprendrez davantage sur les points suivants :

• créer et manipuler un fichier projet ;

• Utiliser des propriétés de génération.

• utiliser des éléments de génération.

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

Installer MSBuild

Si Visual Studio est installé, msBuild est également déjà installé. Avec Visual Studio 2022, il est installé dans le dossier d’installation de Visual Studio. Pour une installation par défaut standard 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 pour MSBuild. Il est automatiquement sélectionné lorsque vous choisissez l’une des autres charges de travail à installer.

Pour installer MSBuild sur un système sans Visual Studio, accédez à Build Tools pour Visual Studio 2022 dans la page des téléchargements. Vous pouvez également obtenir MSBuild en installant le kit SDK .NET.

Création d’un projet MSBuild

Le système de projet Visual Studio est basé sur MSBuild. La création d’un fichier projet à l’aide de Visual Studio n’a rien de compliqué. Dans cette section, vous créez un fichier projet C#. Vous pouvez choisir de créer un fichier projet Visual Basic à la place. Dans le contexte de ce tutoriel, 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 apparaît, 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 examiner le fichier projet dans l’éditeur de code Visual Studio.

Pour examiner le fichier projet

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

2. Dans l’Explorateur de 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 aurait été BuildApp.vbproj.

3. Cliquez avec le bouton droit sur le nœud de projet une nouvelle fois, puis cliquez sur Modifier BuildApp.csproj.

   Le fichier projet s’affiche dans l’éditeur de code.

Notes

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 XML avec le nœud racine Projet.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0"  xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

La plupart des projets .NET ont un attribut Sdk. Ces projets sont appelés projets de style SDK.

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

Il existe de nombreuses variantes de kits SDK .NET utilisées à des fins spécifiques ; elles sont décrites dans la section consacrée aux SDK de projet .NET.

Le processus de création d’une application est effectué avec les éléments Target et Task.

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

• Une cible est une séquence de tâches nommée. Il peut s’agir d’une séquence nommée de tâches, mais de manière critique, elle représente une tâche à créer ou à faire, de sorte qu’elle doit être définie de manière orientée objectif. Pour plus d’informations, consultez l’article Targets (Cibles MSBuild).

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 dans le fichier projet partout où ils sont 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 génération et garantit que chaque cible est générée 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.

Pour 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 d’ouverture.

   <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 obtenue 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 les informations sur leur utilisation, consultez l’article Informations de référence sur les tâches MSBuild.

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

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. En effet, 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.

Remarque

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 Commande.

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

   Si vous avez besoin de le trouver manuellement, le fichier est LaunchDevCmd.bat et se trouve dans le {dossier d’installation de Visual Studio}\Common7\Tools.

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

3. Exécutez msbuild avec le commutateur de commande -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
   

Notes

Si vous voyez The target "HelloWorld" does not exist in the project à la place, 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 Commande, vous pouvez modifier le fichier projet et observer rapidement les résultats.

Propriétés de la build

Les propriétés de génération sont des paires nom-valeur qui guident la génération. Plusieurs propriétés de génération 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>v4.5</TargetFrameworkVersion>

définit la propriété nommée TargetFrameworkVersion, en lui attribuant la valeur de chaîne « v4.5 ».

Les propriétés de build peuvent être redéfinies à tout moment. If

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

apparaît plus loin dans le fichier projet ou dans un fichier importé ultérieurement dans le fichier projet, puis TargetFrameworkVersion prend la nouvelle valeur « v3.5 ».

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 propriétés du fichier projet.

Pour examiner une valeur de propriété

1. Dans 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. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie. Vous devriez voir ces deux lignes (votre sortie peut varier) :

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

Propriétés conditionnelles

Plusieurs propriétés, comme la propriété Configuration, sont définies de manière conditionnelle, autrement dit, l’attribut Condition s’affiche dans l’élément de propriété. Les propriétés conditionnelles sont définies ou redéfinies uniquement si la condition a la valeur « true ». Les propriétés non définies ont 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 attribuez-lui la valeur "Debug" ».

Pratiquement tous les éléments MSBuild peuvent posséder un attribut Condition. Pour en savoir plus sur l’utilisation de l’attribut Condition, consultez l’article Conditions MSBuild.

Propriétés réservées

MSBuild réserve certains noms de propriété pour stocker des informations sur le fichier projet et les binaires de 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 toute 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 génération. 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é qui porte 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 Guide pratique pour utiliser des variables d’environnement dans une build.

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

Il est possible de définir des propriétés sur la ligne de commande à l’aide du commutateur de ligne de commande -property ou -p. Les valeurs de propriété reçues à partir de la ligne de commande remplacent celles qui sont définies dans les variables d’environnement et le fichier projet.

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

1. Dans la fenêtre Commande, entrez et exécutez cette ligne :

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

2. Examinez la sortie. Vous devez normalement voir cette ligne :

   Configuration is Release.
   

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

Caractères spéciaux

Certains caractères ont une signification spéciale dans les fichiers projet MSBuild. Il s’agit par exemple des points-virgules (;) et des astérisques (*). Pour utiliser ces caractères spéciaux en tant que littéraux dans un fichier projet, vous devez les spécifier à 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 afin de la rendre plus lisible.

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

1. Dans 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. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie. Vous devez normalement voir cette ligne :

   $(Configuration) is "Debug"
   

Pour plus d’informations, consultez l’article Caractères spéciaux MSBuild.

Générer des éléments

Un élément est une information, généralement un nom de fichier, qui est utilisée 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 transmise à 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 du même nom sont collectées dans les types d’élément de ce nom. Par exemple,

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

définit un groupe de deux éléments. Le type d’élément Compile possède 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 MSBuild.

Notes

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 à cette règle, par exemple lors de l’utilisation d’éléments Import et UsingTask.

Examiner des 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 des valeurs de types d’élément :

1. Dans 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. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie. Vous devez normalement observer 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
   

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

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

@(ItemType, Separator)

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

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

1. Dans 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. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie. Vous devez normalement 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
   

Caractères génériques et attributs Include et Exclude

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 pourvus de l’extension de fichier .jpeg du dossier images au type d’élément Photos, alors que

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

ajoute tous les fichiers pourvus de l’extension de fichier .jpeg du dossier images et de l’ensemble de ses sous-dossiers, au type d’élément Photos. Pour plus d’informations, consultez Guide pratique pour sélectionner des fichiers dans une build.

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

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

crée un type d’élément nommé Photo qui contient tous les fichiers du dossier images avec une 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 portant 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 Item qui les contient. Par exemple,

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

n’exclut pas le fichier Form1.cs, qui a été ajouté dans l’élément Item précédent.

Pour inclure et exclure des éléments

1. Dans 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. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

5. Examinez la sortie. Vous devez normalement voir cette ligne :

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

Métadonnées d’élément

Outre les informations collectées à partir des attributs Include et Exclude, les éléments peuvent contenir des métadonnées. 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 avec le nom des métadonnées comme élément enfant de l’élément. Un élément peut comporter zéro ou plusieurs valeurs de métadonnées. Par exemple, l’élément CSFile suivant contient les métadonnées Culture de 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 le nom des métadonnées :

%(ItemType.MetaDataName)

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

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

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

2. Enregistrez le fichier projet.

3. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie. Vous devez normalement voir ces lignes :

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

Notez que l’expression « Compile.DependentUpon » apparaît plusieurs fois. L’utilisation de métadonnées avec cette syntaxe dans une cible provoque le « traitement par lot ». Cela signifie que les tâches de la cible sont exécutées une fois pour chaque valeur de métadonnée unique. Le traitement par lot est l’équivalent du script MSBuild de la construction de programmation « boucle foreach » courante. Pour plus d’informations, consultez l’article Batching (Traitement par lot MSBuild).

Métadonnées connues

Chaque fois qu’un élément est ajouté à une liste d’éléments, il reçoit des métadonnées connues. Par exemple, %(Filename) retourne le nom de fichier de n’importe quel é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 des métadonnées connues :

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

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

2. Enregistrez le fichier projet.

3. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie. Vous devez normalement 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 si tous les éléments du type d’élément Compile ne disposent pas de la métadonnée DependentUpon, tous possèdent la métadonnée Filename connue.

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> 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 objets à l’aide d’une expression comme @(SourceFiles -> '%(Filename).obj'). Pour plus d’informations, consultez l’article Transforms (Transformations MSBuild).

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

1. Dans 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. Dans la fenêtre Commande, entrez et exécutez cette ligne :

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examinez la sortie. Vous devez normalement 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 le traitement par lot.

Étapes suivantes

Pour découvrir comment créer pas à pas un fichier projet simple sur Windows, consultez Créer un fichier projet MSBuild à partir de zéro.

Si vous utilisez principalement le kit de développement logiciel (SDK) .NET, consultez l’article Référence MSBuild pour les projets SDK .NET.

Contenu connexe

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