Procédures pas à pas : utilisation de MSBuild
MSBuild est la plateforme de génération pour Microsoft et Visual Studio.Cette procédure pas à pas présente les blocs de constructions de MSBuild et indique comment écrire, manipuler et déboguer des projets MSBuild.Les sujets suivants seront abordés :
Création et manipulation d'un fichier projet
Utilisation des propriétés de génération
Utilisation des éléments de génération
Vous pouvez exécuter MSBuild à partir de Visual Studio ou de la fenêtre Commande.Dans cette procédure pas à pas, vous allez créer un fichier projet MSBuild à l'aide de Visual Studio.Vous modifierez le fichier projet dans Visual Studio et utiliserez la fenêtre Commande pour générer le projet et examiner les résultats.
Création d'un projet MSBuild
Le système de projet Visual Studio est basé sur MSBuild.Ainsi, il est facile de créer un fichier projet à l'aide de Visual Studio.Dans cette section, vous créez un fichier projet Visual C#.Vous pouvez choisir de créer à la place un fichier projet Visual Basic.Dans le contexte de cette procédure pas à pas, la différence entre les deux fichiers projet est mineure.
Pour créer un fichier projet
Ouvrez Visual Studio.
Dans le menu Fichier, pointez sur Nouveau, puis cliquez sur Projet.
Dans la boîte de dialogue Nouveau projet, sélectionnez le type de projet Visual C#, puis sélectionnez le modèle Application Windows Forms.Dans la zone Nom, tapez BuildApp.Entrez un Emplacement pour la solution, par exemple, D:\.Acceptez les valeurs par défaut pour Créer le répertoire pour la solution (option sélectionnée), Ajouter au contrôle de code source (option non sélectionnée) et Nom de solution (BuildApp).
Cliquez sur OK pour créer le fichier projet.
Examen du fichier projet
Dans la section précédente, vous avez utilisé Visual Studio pour créer un fichier projet Visual 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
Dans l'Explorateur de solutions, cliquez sur le nœud de projet BuildApp.
Dans l'Explorateur de propriétés, remarquez que la propriété Project File est BuildApp.csproj.Le nom des fichiers projet porte le suffixe « proj ».Si vous aviez créé un projet Visual Basic, le nom du fichier projet aurait été BuildApp.vbproj.
Cliquez avec le bouton droit sur le nœud de projet, puis cliquez sur Décharger le projet.
Cliquez avec le bouton droit sur le nœud de projet une nouvelle fois, puis cliquez sur Modifier BuildApp.csproj+.
Le fichier projet apparaît dans l'éditeur de code.
Cibles et tâches
Les fichiers projet sont des fichiers au format XML avec le nœud racine Projet.
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
Vous devez spécifier l'espace de noms xmlns dans l'élément Project.
Le travail pour générer une application est exécutée avec cible et des éléments de tâche .
Une tâche est la plus petite unité de travail, en d'autres termes, l'« atome » d'une build.Les tâches sont des composants exécutables indépendants qui peuvent avoir des entrées et des sorties.Actuellement, aucune tâche n'est référencée ou définie dans le fichier projet.Vous allez ajouter des tâches au fichier projet dans les sections ci-dessous.Pour plus d'informations, consultez la rubrique Tâches MSBuild.
Une cible est une séquence nommée de tâches.Actuellement, deux cibles à la fin du fichier projet sont comprises dans des commentaires HTML : BeforeBuild et AfterBuild.
<Target Name="BeforeBuild"> </Target> <Target Name="AfterBuild"> </Target>Pour plus d'informations, consultez la rubrique Cibles de MSBuild.
Le nœud Projet a un attribut DefaultTargets facultatif qui sélectionne la cible par défaut à générer, dans le cas présent, Build.
<Project ToolsVersion="4.0" DefaultTargets="Build" ...
La cible Build n'est pas définie dans le fichier projet.À la place, elle est importée à partir du fichier Microsoft.CSharp.targets à l'aide de l'élément Import.
<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.
MSBuild effectue le suivi des cibles d'une build et garantit que chaque cible n'est générée qu'une seule fois.
Ajout d'une cible et d'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
Ajoutez ces lignes au fichier projet, juste après l'instruction Import :
<Target Name="HelloWorld"> </Target>Cela crée une cible nommée HelloWorld.Remarquez que vous bénéficiez de la prise en charge Intellisense pendant la modification du fichier projet.
Ajoutez des lignes à la cible HelloWorld, afin que la section résultante ressemble à ce qui suit :
<Target Name="HelloWorld"> <Message Text="Hello"></Message> <Message Text="World"></Message> </Target>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 sur leur utilisation, consultez Référence des tâches MSBuild.
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.La cible HelloWorld exécute la tâche Message à deux reprises : d'abord pour afficher « Hello », ensuite pour afficher « World ».
Génération de la cible
Exécutez MSBuild à partir de l'Invite de commandes de 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]
Nous ferons référence à l'Invite de commandes de Visual Studio comme la fenêtre Commande dans les sections ci-dessous.
Pour générer la cible
Cliquez sur Démarrer, puis sur Tous les programmes.Recherchez l'Invite de commandes de Visual Studio dans le dossier Visual Studio Tools et cliquez dessus.
Dans la fenêtre Commande, naviguez jusqu'au dossier contenant le fichier projet, dans le cas présent, D:\BuildApp\BuildApp.
Exécutez msbuild avec le commutateur de commande /t:HelloWorld.Cela sélectionne et génère la cible HelloWorld :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie dans la fenêtre Commande.Vous devez normalement voir les deux lignes « Hello » et « World » :
Hello World
[!REMARQUE]
Si vous voyez à la place 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 Commande, vous pouvez modifier le fichier projet et consulter rapidement les résultats.
[!REMARQUE]
Si vous exécutez msbuild sans le commutateur de commande /t, msbuild génère la cible fournie par l'attribut DefaultTarget de l'élément Project, dans le cas présent, « Build ».Cela génère l'application Windows Forms BuildApp.exe.
Propriétés de la génération
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 au début 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 d'é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.0</TargetFrameworkVersion>
définit la propriété nommée TargetFrameworkVersion, en lui donnant la valeur de chaîne « v4.0 ».
Les propriétés de génération peuvent être redéfinies n'importe quand.If
<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>
s'affiche plus loin dans le fichier projet ou dans un fichier importé ultérieurement dans le fichier projet, TargetFrameworkVersion prend la nouvelle valeur « v3.5 ».
Examen d'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 quelques-unes des propriétés dans le fichier projet.
Pour examiner une valeur de propriété
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>Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie.Vous devez normalement voir ces deux lignes (votre version du .NET Framework peut différer) :
Configuration is Debug MSBuildToolsPath is C:\Windows\Microsoft.NET\Framework\v4.0.20317
[!REMARQUE]
Si vous ne voyez pas ces lignes, vous avez probablement oublié d'enregistrer le fichier projet dans l'éditeur de code.Enregistrez le fichier et réessayez.
.gif "Dd393573.collapse_all(fr-fr,VS.110).gif")
Propriétés conditionnelles
De nombreuses propriétés telles que 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 ».Notez que la valeur par défaut affectée aux propriétés non définies est 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 affectez-lui la valeur 'Debug' ».
Presque tous les éléments MSBuild peuvent avoir un attribut Condition.Pour plus d'informations sur l'utilisation de l'attribut Condition, consultez 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 fichiers binaires MSBuild.MSBuildToolsPath est un exemple de propriété réservée (nouveau dans MSBuild 3.5).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 Comment : référencer le nom ou l'emplacement du fichier projet et MSBuild, propriétés réservées.
Variables d'environnement
Vous pouvez référencer les 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 a le même nom qu'une variable d'environnement, la propriété du projet substitue la valeur de la variable d'environnement.Pour plus d’informations, consultez Comment : utiliser des variables d'environnement dans une génération.
Définition 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
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorld /p:Configuration=ReleaseExaminez la sortie.Vous devriez voir cette ligne :
Configuration is Release.
MSBuild crée la propriété Configuration et lui affecte la valeur « Release ».
Caractères spéciaux
Certains caractères ont une signification spéciale dans les fichiers projet MSBuild.Parmi ces caractères, on trouve le point-virgule (;) et l'astérisque (*).Pour utiliser ces caractères spéciaux comme valeurs littérales dans un fichier projet, ils doivent être spécifiés en utilisant la syntaxe %xx, où xx représente la valeur hexadécimale ASCII du caractère.
Modifiez la tâche Message afin d'inclure des caractères spéciaux dans la valeur de la propriété Configuration pour la rendre plus lisible.
Pour utiliser des caractères spéciaux dans la tâche Message
Dans l'éditeur de code, remplacez les deux tâches Message par cette ligne :
<Message Text="%24(Configuration) is %22$(Configuration)%22" />Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie.Vous devriez voir cette ligne :
$(Configuration) is "Debug"
Pour plus d’informations, consultez Caractères spéciaux MSBuild.
Éléments de génération
Un élément est un renseignement, en général 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 que ces éléments soient compilés dans un assembly.
Tous les éléments sont des éléments enfants d'é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 portant le même nom sont collectées dans les 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 qui contient 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éments MSBuild.
[!REMARQUE]
Les chemins d'accès aux fichiers sont relatifs au dossier contenant le fichier projet MSBuild.
Examen de 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 type d'élément
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>Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie.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
Par défaut, les valeurs d'un type d'élément sont séparées par des points-virgules.
Pour modifier le séparateur d'un type d'élément, utilisez la syntaxe suivante, où ItemType est le type d'élément et Separator est une chaîne contenant un ou plusieurs caractères séparateurs :
@(ItemType, Separator)
Modifiez la tâche Message de sorte qu'elle utilise 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
À partir de l'éditeur de code, remplacez la tâche Message par cette ligne :
<Message Text="Compile item type contains @(Compile, '%0A%0D')" />Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorld
Examinez la sortie.Vous devriez 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
Attributs Include et Exclude, 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 » contenus dans le dossier des images au type d'élément Photos, alors que
<Photos Include="images\**.jpeg" />
ajoute tous les fichiers avec l'extension de fichier « .jpeg », contenus dans le dossier des images et dans tous ses sous-dossiers, au type d'élément Photos.Pour plus d'exemples, consultez Comment : sélectionner des fichiers pour la build.
À mesure que 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 du dossier des images ayant l'extension « .jpeg » ou « .gif ».Cela équivaut à la ligne suivante :
<Photos Include="images\*.jpeg;images\*.gif" />
Vous pouvez exclure un élément d'un type d'élément à l'aide de 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 le nom contient la chaîne « Designer ».Pour plus d'exemples, consultez Comment : exclure des fichiers de la build.
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 inclure et exclure des éléments
À partir de l'éditeur de code, remplacez la tâche Message par cette ligne :
<Message Text="Compile item type contains @(XFiles)" />Ajoutez ce groupe d'éléments juste après l'élément Import :
<ItemGroup> <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" /> </ItemGroup>Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie.Vous devriez voir cette ligne :
Compile item type contains Form1.cs;Program.cs;Properties/Resources.resx
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 des tâches qui nécessitent davantage d'informations sur les éléments que la valeur d'élément seule.
Les métadonnées d'éléments 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 plusieurs valeurs de métadonnées ou n'en avoir aucune.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 de 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
À partir de l'éditeur de code, remplacez la tâche Message par cette ligne :
<Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie.Vous devriez 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 ».Le traitement par lot signifie que les tâches dans la cible sont exécutées une fois pour chaque valeur de métadonnées unique.Il s'agit du script MSBuild équivalent à la construction de programmation « boucle for » commune.Pour plus d’informations, consultez Traitement par lots de MSBuild.
Métadonnées connues
Chaque fois qu'un élément est ajouté à une liste d'éléments, des métadonnées connues lui sont assignées.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 Métadonnées d'éléments connus MSBuild.
Pour examiner des métadonnées connues
À partir de l'éditeur de code, remplacez la tâche Message par cette ligne :
<Message Text="Compile Filename: %(Compile.Filename)" />Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie.Vous devriez 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 ci-dessus, vous constatez que si tous les éléments du type Compile n'ont pas les métadonnées DependentUpon, tous ont les métadonnées Filename connues.
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 désigne le nom du type d'élément et MetadataName désigne le nom des métadonnées :
@(ItemType -> '%(MetadataName)')
Par exemple, une liste de fichiers sources peut être transformée en une collection de fichiers objets à l'aide d'une expression telle que @(SourceFiles -> '%(Filename).obj').Pour plus d’informations, consultez Transformations MSBuild.
Pour transformer des éléments à l'aide de métadonnées
À partir de l'éditeur de code, remplacez la tâche Message par cette ligne :
<Message Text="Backup files: @(Compile->'%(filename).bak')" />Enregistrez le fichier projet.
À partir de la Fenêtre Commande, entrez et exécutez cette ligne :
msbuild buildapp.csproj /t:HelloWorldExaminez la sortie.Vous devriez voir cette ligne :
Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
Remarquez que les métadonnées exprimées dans cette syntaxe ne provoquent pas le traitement par lot.
Quoi d'autre ?
Pour savoir comment créer pas à pas un fichier projet simple, consultez Procédure pas à pas : création d'un fichier projet MSBuild en partant de zéro.