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

Utilisez des événements de génération pour spécifier des commandes qui s’exécutent avant le démarrage de la build ou une fois la build terminée.

Spécifier un événement de build

1. Dans Explorateur de solutions, sélectionnez le projet pour lequel vous souhaitez spécifier l’événement de génération.

2. Dans le menu Project, cliquez sur {ProjectName} Properties (ou à partir de 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.

   Remarque

   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.

   Remarque

   Ajoutez une instruction call avant toutes les commandes post-build qui exécutent des fichiers .bat. Par exemple, call MyFile.bat ou call MyFile.bat call MyFile2.bat. Les chemins d’accès peuvent être absolus ou relatifs au dossier du 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 à l’invite de commandes ou dans un fichier .bat. Les commandes disponibles sont documentées dans la référence de commande windows . Le nom d’un fichier de commandes doit être précédé de call pour vous assurer que toutes les commandes suivantes sont exécutées. Le fichier batch lui-même s’exécute à partir du dossier de sortie, par exemple, bin/Debug. Si vous avez besoin du même fichier batch pour toutes les configurations, vous pouvez le placer dans le même dossier que le fichier projet et utiliser un chemin relatif vers 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 d’accès au script PowerShell peut être absolu ou être relatif au répertoire du projet. Vous devez vous assurer que la stratégie d’exécution pour les 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, tel que bash, vous utilisez généralement la même syntaxe de commande que celle utilisée pour lancer un script d’interpréteur de commandes à partir de l’invite de commandes Windows. L’utilisation de shells tiers dépasse la portée de cette documentation, mais les sites tels que Stack Overflow peuvent être utiles.

Dans le fichier projet

Lorsque vous effectuez les étapes précédentes, Visual Studio modifie votre fichier projet en ajoutant la cible PreBuild ou PostBuild et le code MSBuild nécessaire pour exécuter les étapes que vous avez fournies. Vous pouvez ouvrir le fichier projet et voir les étapes. La modification des étapes du fichier projet est acceptable. Vous verrez vos modifications dans la section Build > Events des propriétés du projet après avoir enregistré les modifications.

<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 Exec MSBuild. Consultez 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 le répertoire qui contient le fichier projet.

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

Vous pouvez utiliser des propriétés MSBuild (macros), telles que OutDir dans l’exemple précédent, comme décrit plus loin dans cet article à 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 Afficher>AutresWindows, Fenêtre de 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écompilation ou de postcompilation ne s'achève pas correctement, vous pouvez interrompre la compilation en faisant quitter votre action d'événement avec un code autre que zéro (0). Un code de sortie zéro indique une action réussie ; tout autre code de sortie est considéré comme une erreur.

Si votre événement de pré-compilation échoue, une erreur semblable à celle-ci peut s’afficher dans la fenêtre liste d’erreurs :

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

S’il n’y a pas suffisamment d’informations dans la fenêtre liste d’erreurs, vous pouvez essayer d’utiliser la fenêtre de sortie pour afficher la sortie complète de la build, y compris toute sortie à partir de fichiers batch.

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 par lots à 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 batch lui-même.

Pour obtenir des conseils sur les commandes que vous pouvez utiliser dans les fichiers batch, consultez commandes Windows.

Macros

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

Dans vos scripts pour les événements de génération, vous pouvez référencer les valeurs de certaines variables au niveau du projet, telles que le nom du projet ou l’emplacement du dossier de sortie. Dans les versions antérieures de Visual Studio, celles-ci ont été appelées macros . L’équivalent des macros dans les versions récentes de Visual Studio est des propriétés MSBuild. MSBuild est le moteur de build que Visual Studio utilise pour traiter votre fichier projet lorsqu’il effectue une build. 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 dans votre fichier projet (par exemple, $(OutDir) ou $(Configuration)) . Les propriétés MSBuild qui sont disponibles dans ces événements dépendent des fichiers implicitement ou explicitement importés dans un fichier projet, tels que les fichiers .props et .targets, ainsi que les propriétés définies dans votre fichier projet, comme dans PropertyGroup éléments. Veillez à utiliser l’orthographe exacte de chaque propriété. Aucune erreur n’est signalée si vous mal orthographié une propriété ; Au lieu de cela, une propriété non définie prend la valeur d’une chaîne vide.

Par exemple, supposons que vous spécifiez un événement de pré-build comme suit :

Cet événement de 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.

Lorsque vous générez le projet dans cet exemple, l’événement de pré-construction affiche les valeurs de certaines propriétés. Dans cet exemple, $(CscToolPath) ne produit aucune sortie, car elle n’est pas définie. Il s’agit d’une propriété facultative que vous pouvez définir dans votre fichier projet pour donner le chemin d’accès à une instance personnalisée du compilateur C# (par exemple, si vous testiez une autre version de csc.exeou 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

Remarque

Certains scénarios nécessitent des actions de génération plus complexes que ce que permettent les événements de génération. Par exemple, pour de nombreux scénarios courants de génération de code, vous devez gérer les opérations de nettoyage et de reconstruction, et vous pouvez activer la génération incrémentielle pour les étapes de génération de code, afin que l’étape s’exécute uniquement 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 batch, %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 et vérifiez le dossier de sortie. Vous devriez voir le fichier copié à côté de l'assemblage généré. Dans la fenêtre de sortie , dans la section Générer, vous devez voir la sortie du fichier batch :

   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
• Comment spécifier les événements de build (Visual Basic)
• Compiler et générer