Spécifier des événements de build (C#)

Utilisez des événements de build pour spécifier des commandes à exécuter avant que la génération commence ou après qu’elle se termine.

Spécifier un événement de build

1. Dans l’Explorateur de solutions, sélectionnez le projet pour lequel vous voulez spécifier l’événement de build.

2. Dans le menu Projet, cliquez sur Propriétés de {NomProjet} (ou dans l’Explorateur de solutions, appuyez sur Alt+Entrée).

3. Sélectionnez Build > Événements.

   

4. Dans la section Événement pré-build, spécifiez la syntaxe de l’événement de build.

   Notes

   Les événements pré-build ne fonctionnent pas si le projet est à jour et qu’aucune build n’est déclenchée.

5. Dans la section Événement post-build, spécifiez la syntaxe de l’événement de build.

   Notes

   Ajoutez une instruction call avant toutes les commandes postbuild qui exécutent des fichiers .bat. Par exemple, call MyFile.bat ou call MyFile.bat call MyFile2.bat. Les chemins peuvent être absolus ou relatifs au dossier de projet.

6. Dans la section Quand exécuter l’événement post-build, spécifiez sous quelles conditions exécuter l’événement post-build.

Créer les commandes d’événement de build

Les commandes d’événement de build peuvent inclure n’importe quelle commande valide à une invite de commandes ou dans un fichier .bat. Les commandes disponibles sont documentées dans la référence des commandes Windows. Le nom d’un fichier de commandes doit être précédé par call pour vous assurer que toutes les commandes suivantes sont exécutées. Le fichier de commandes proprement dit s’exécute à partir du dossier de sortie, par exemple bin/Debug. Si vous avez besoin du même fichier de commandes pour toutes les configurations, vous pouvez le placer dans le même dossier que le fichier projet et utiliser un chemin relatif à celui-ci, par exemple call ../../prebuild.bat.

Vous pouvez exécuter des scripts PowerShell en entrant une commande telle que PowerShell MyPowerShellScript.ps1. Le chemin du script PowerShell peut être absolu ou relatif au répertoire du projet. Vous devez vérifier que la stratégie d’exécution des scripts PowerShell sur votre système d’exploitation est définie de manière appropriée pour exécuter le script. Consultez À propos des stratégies d’exécution.

Si vous souhaitez utiliser un autre interpréteur de commandes, par exemple Bash, vous devez généralement utiliser la même syntaxe de commande que celle que vous utilisez pour lancer un script d’interpréteur de commandes à partir de l’invite de commandes Windows. L’utilisation d’interpréteurs de commandes tiers dépasse le cadre de cette documentation. Toutefois, vous pourrez trouver des informations utiles sur des sites tels que Stack Overflow.

Dans le fichier projet

Quand vous suivez les étapes précédentes, Visual Studio modifie votre fichier projet en ajoutant la cible PreBuild ou PostBuild ainsi que le code MSBuild nécessaire à l’exécution des étapes que vous avez fournies. Vous pouvez ouvrir le fichier projet, et voir les étapes. La modification des étapes dans le fichier projet ne pose pas de problème. Vous verrez vos changements dans la section Build > Événements des propriétés du projet, une fois que vous aurez enregistré ces changements.

<Target Name="PreBuild" BeforeTargets="PreBuildEvent">
  <Exec Command="call prebuild.bat" />
</Target>

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
  <Exec Command="call postbuild.bat" />
</Target>

L'élément Exec fait référence à la tâche MSBuild Exec. Consultez la tâche Exec pour plus d'informations sur les autres paramètres que vous pouvez utiliser pour personnaliser l'exécution. Par exemple, vous pouvez utiliser WorkingDirectory pour définir le dossier à partir duquel l'exécutable est exécuté. La valeur par défaut est l'annuaire qui contient le fichier projet.

<Exec Command="call prebuild.bat" WorkingDirectory="$(OutDir)">

Vous pouvez utiliser des propriétés MSBuild (macros), comme OutDir dans l'exemple précédent, tel que discuté plus loin dans cet article sur Macros.

Erreurs et autres sorties

La sortie de vos événements de build est écrite dans la section Build de la Fenêtre Sortie. Pour l’ouvrir, choisissez Affichage>Autres fenêtres, Fenêtre Sortie, ou appuyez sur Ctrl+Alt+O. Dans la liste déroulante en regard de Afficher la sortie à partir de, choisissez Build.

Si votre événement de prébuild ou de postbuild ne s’effectue pas correctement, vous pouvez mettre fin à la build en faisant en sorte que votre action d’événement s’arrête avec un code autre que zéro (0). Un code de sortie ayant la valeur zéro indique une action réussie. Tout autre code de sortie est considéré comme une erreur.

En cas d’échec de votre événement prébuild, vous pouvez voir une erreur semblable à celle-ci dans la fenêtre Liste d’erreurs :

MSB3073    The command "call c:\source\repos\prebuild.bat" exited with code 1.

Si vous ne disposez pas de suffisamment d’informations dans la fenêtre Liste d’erreurs, vous pouvez essayer d’utiliser la Fenêtre Sortie pour voir la sortie complète de la build ainsi que les sorties des fichiers de commandes.

Conseil

La fenêtre Liste d’erreurs est limitée à une seule ligne de sortie, la première ligne que vous avez entrée pour l’événement. Si la sortie de la fenêtre Liste d’erreurs est importante pour vous, évitez de placer plusieurs lignes dans l’événement. Créez un fichier de commandes à partir de l’invite de commandes Windows ou dans le système d’exploitation, puis utilisez simplement call mybatchfile.bat pour l’événement. Incluez les commandes dans le fichier de commandes proprement dit.

Pour obtenir des conseils d’aide sur les commandes que vous pouvez utiliser dans les fichiers de commandes, consultez Commandes Windows.

Macros

Les « macros » couramment disponibles (en fait, les propriétés MSBuild) sont listées dans Propriétés courantes MSBuild. Pour les projets SDK .NET (.NET Core ou .NET 5 et versions ultérieures), les propriétés supplémentaires sont listées dans Propriétés MSBuild pour Microsoft.NET.Sdk.

Dans vos scripts pour les événements de build, vous pouvez référencer les valeurs de certaines variables au niveau du projet, comme le nom du projet ou l’emplacement du dossier de sortie. Dans les versions antérieures de Visual Studio, elles étaient appelées macros. L’équivalent des macros dans les versions récentes de Visual Studio sont les propriétés MSBuild. MSBuild est le moteur de génération que Visual Studio utilise pour traiter votre fichier projet quand il effectue une génération. Un événement de build dans l’IDE génère une cible MSBuild dans le fichier projet. Vous pouvez utiliser n’importe quelle propriété MSBuild disponible dans la cible de votre fichier projet (par exemple, $(OutDir) ou $(Configuration)). Les propriétés MSBuild disponibles dans ces événements dépendent des fichiers implicitement ou explicitement importés dans un fichier projet, par exemple, les fichiers .props et .targets, et des propriétés définies dans votre fichier projet, comme dans les éléments PropertyGroup. Veillez à utiliser l’orthographe exacte de chaque propriété. Aucune erreur n’est signalée si vous avez mal orthographié une propriété, mais la propriété non définie prend la valeur d’une chaîne vide.

Par exemple, supposons que vous spécifiez un événement pré-build de la façon suivante :

Cet événement pré-build entraîne l’entrée suivante, appelée Target dans votre fichier projet :

  <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="echo Configuration: $(Configuration)&#xD;&#xA;echo DevEnvDir: $(DevEnvDir)&#xD;&#xA;echo OutDir: $(OutDir)&#xD;&#xA;echo ProjectDir: $(ProjectDir)&#xD;&#xA;echo VisualStudioVersion: $(VisualStudioVersion)&#xD;&#xA;echo AssemblySearchPaths: $(AssemblySearchPaths)&#xD;&#xA;echo AssemblyName: $(AssemblyName)&#xD;&#xA;echo BaseIntermediateOutputPath: $(BaseIntermediateOutputPath)&#xD;&#xA;echo CscToolPath: $(CscToolPath)" />
  </Target>

L’événement de build s’affiche comme cible qui ajoute la tâche Exec avec l’entrée que vous avez spécifiée comme Command. Les nouvelles lignes sont encodées dans le code XML.

Quand vous générez le projet dans cet exemple, l’événement pré-build imprime les valeurs de certaines propriétés. Dans cet exemple, $(CscToolPath) ne produit aucune sortie, car elle n’est pas définie. C’est une propriété facultative que vous pouvez définir dans votre fichier projet pour indiquer le chemin d’une instance personnalisée du compilateur C# (par exemple si vous testez une autre version de csc.exe ou un compilateur expérimental).

La sortie de vos événements de build est écrite dans la sortie de build, qui se trouve dans la fenêtre Sortie. Dans la liste déroulante Afficher la sortie à partir de, choisissez Build.

Build started...
1>------ Build started: Project: ConsoleApp4, Configuration: Debug Any CPU ------
1>You are using a preview version of .NET. See: https://aka.ms/dotnet-core-preview
1>Configuration: Debug
1>DevEnvDir: C:\Program Files\Microsoft Visual Studio\2022\Preview\Common7\IDE\
1>OutDir: bin\Debug\net6.0\
1>ProjectDir: C:\source\repos\ConsoleApp4\ConsoleApp4\
1>VisualStudioVersion: 17.0
1>ALToolsPath:
1>AssemblySearchPaths: {CandidateAssemblyFiles};{HintPathFromItem};{TargetFrameworkDirectory};{RawFileName}
1>AssemblyName: ConsoleApp4
1>BaseIntermediateOutputPath: obj\
1>CscToolsPath:
1>Skipping analyzers to speed up the build. You can execute 'Build' or 'Rebuild' command to run analyzers.
1>ConsoleApp4 -> C:\source\repos\ConsoleApp4\ConsoleApp4\bin\Debug\net6.0\ConsoleApp4.dll

Notes

Certains scénarios nécessitent des actions de build plus complexes que celles des événements de build. Par exemple, pour de nombreux scénarios courants de génération de code, vous devez gérer des opérations de nettoyage et de regénération, et vous pouvez activer la génération incrémentielle pour les étapes de génération de code, de sorte que l’étape s’exécute seulement si la sortie est obsolète par rapport aux entrées. MSBuild est conçu pour gérer intelligemment tous ces scénarios. Créez une cible personnalisée qui spécifie l’exécution de AfterTargets ou BeforeTargets à un moment spécifique du processus de génération. Pour obtenir un contrôle supplémentaire dans les scénarios avancés, créez une tâche personnalisée, ou passez en revue les différentes façons dont vous pouvez personnaliser votre build.

Exemple

1. Créez un fichier de commandes nommé postbuild.bat dans le dossier du projet, avec le contenu suivant :

   echo Copying output file %1 to %1.copy
   copy %1 %1.copy
   

   Rappelez-vous que dans un fichier de commandes, %1 fait référence au premier argument passé.

2. Appelez le fichier de commandes dans la section Événement postbuild des propriétés du projet, puis passez un argument à l’aide de la propriété MSBuild $(TargetPath).

   call postbuild.bat $(TargetPath)
   

3. Générez votre projet, puis vérifiez le dossier de sortie. Vous devez voir le fichier copié près de l’assembly généré. Dans la Fenêtre Sortie, dans la section Buidl, vous devez voir la sortie du fichier de commandes :

   1>Output file is C:\source\repos\ConsoleApp-BuildEvents\ConsoleApp-BuildEvents\bin\Debug\net6.0\ConsoleApp-BuildEvents.dll
   1>        1 file(s) copied.
   ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
   ========== Build started at 12:00 PM and took 00.723 seconds ==========
   

Contenu connexe

• Événements de build, page du Concepteur de projets (C#)
• Ligne de commande de l’événement prébuild/postbuild, boîte de dialogue
• Guide pratique pour spécifier des événements de build (Visual Basic)
• Compiler et générer