Diagnostiquez les échecs de tâches MSBuild

MSB6006 est émis lorsqu’une classe dérivée ToolTask exécute un processus d’outil qui renvoie un code de sortie non nul si la tâche n’a pas journalisé une erreur plus spécifique.

Identifiez la tâche défaillante

Lorsque vous rencontrez une erreur de tâche, la première étape consiste à identifier la tâche qui échoue.

Le texte de l’erreur spécifie le nom de l’outil (soit un nom convivial fourni par l’implémentation de la tâche ToolName, soit le nom de l’exécutable) et le code de sortie numérique. Par exemple, dans error MSB6006: "custom tool" exited with code 1. le nom de l’outil est custom toolet le code de sortie est 1.

Pour trouver la tâche MSBuild ayant échoué :

• Dans les builds de ligne de commande : si la build a été configurée pour inclure un résumé (valeur par défaut), le résumé se présente comme suit :

  Build FAILED.
  
  "S:\MSB6006_demo\MSB6006_demo.csproj" (default target) (1) ->
  (InvokeToolTask target) ->
    S:\MSB6006_demo\MSB6006_demo.csproj(19,5): error MSB6006: "custom tool" exited with code 1.
  

  Ce résultat indique que l’erreur s’est produite dans une tâche définie à la ligne 19 du fichier S:\MSB6006_demo\MSB6006_demo.csproj, dans une cible nommée InvokeToolTask, dans le projet S:\MSB6006_demo\MSB6006_demo.csproj.

• Dans l’interface utilisateur de Visual Studio : les mêmes informations sont disponibles dans la liste d’erreurs Visual Studio dans les colonnes Project, Fileet Line.

Trouvez plus d’informations sur l’échec

L'erreur MSB6006 est émise lorsque la tâche n'a pas journalisé une erreur spécifique. L'absence d'enregistrement d'une erreur est souvent due au fait que la tâche n'est pas configurée pour comprendre le format d'erreur émis par l'outil qu'elle appelle.

Les outils qui fonctionnent bien émettent généralement certaines informations contextuelles ou d’erreur vers leur sortie standard ou leur flux d’erreur, et les tâches capturent et journalisent ces informations par défaut. Recherchez des informations supplémentaires dans les entrées du journal avant que l’erreur ne se produise. La réexécution de la build avec un niveau de journalisation plus élevé peut être nécessaire pour conserver ces informations. Espérons que le contexte ou les erreurs supplémentaires identifiés dans la journalisation révèlent la cause profonde du problème. Si ce n’est pas le cas, vous devrez peut-être limiter les causes potentielles en examinant les propriétés et les éléments qui sont des entrées dans la tâche défaillante.

Déboguer une tâche

Lorsque vous déboguez des tâches MSBuild, voici quelques conseils généraux.

• Réduisez autant que possible la portée de l'incident (par exemple, en définissant /p:BuildProjectReferences=false et en démarrant MSBuild avec un projet spécifique ou une cible spécifique) afin d'avoir moins de code à traiter.
• Utilisez l'option de ligne de commande MSBuild /m:1 pour avoir un seul processus MSBuild à déboguer.
• Définissez la variable d'environnement MSBUILDDEBUGONSTART à 1 pour obtenir un débogueur attaché à MSBuild au lancement.
• Placez un point d'arrêt sur la méthode Execute de la tâche à parcourir.

Déboguer une tâche personnalisée

Si vous écrivez du code pour une tâche personnalisée, vous pouvez faciliter le débogage en ajoutant un appel au débogueur dans la méthode Execute de la tâche. Vous pouvez clôturer ce code avec une vérification de variable d'environnement, afin que lorsqu'un utilisateur définit cette variable d'environnement, la tâche s'arrête et donne à l'utilisateur la possibilité de déboguer. Vous pouvez utiliser System.Diagnostics.Debugger.Launch ou System.Diagnostics.Debugger.Break pour lancer ou interrompre le débogueur.

Vous devez vous assurer d'ajouter autant de journalisation que possible dans une tâche personnalisée afin de faciliter le débogage de la tâche par les utilisateurs. Ceci est important lorsque vous identifiez finalement l'origine d'un incident ; ajoutez suffisamment de code de journalisation pour détecter et signaler ce mode d'échec à l'avenir.

Envisagez de mettre en place un environnement de test pour une tâche à l'aide de xUnit. Consultez Effectuer des tests unitaires de C# dans .NET Core à l’aide de dotnet test et de xUnit. Vous pouvez configurer le test xUnit pour utiliser l'API MSBuild afin d'invoquer MSBuild de manière programmatique avec un fichier de projet fictif qui inclut les propriétés, les éléments et les cibles dont vous avez besoin pour exécuter la tâche en question. Dans certains incidents, il peut être judicieux de créer un moteur de construction fictif. Vous pouvez voir un exemple sur Test unitaire d'une tâche MSBuild personnalisée avec Visual Studio.

Dans les projets SDK .NET, vous pouvez également modifier launchSettings.json pour ajouter un profil de débogage spécial qui exécute MSBuild.exe avec les arguments de ligne de commande et les variables d'environnement mentionnés plus haut dans cet article.

"profiles": {
  "Debug Build": {
    "commandName": "Executable",
    "executablePath": "$(MSBuildBinPath)\\MSBuild.exe",
    "commandLineArgs": "/p:Configuration=$(Configuration) $(ProjectFileName) /m:1",
    "workingDirectory": "$(ProjectDir)"
  }
}

Si vous souhaitez être invité à attacher votre propre débogueur au moment de l'exécution, définissez la variable d'environnement MSBUILDDEBUGONSTART sur 2. Cela peut s'avérer utile lorsque vous utilisez un débogueur différent, par exemple sur macOS lorsque Visual Studio n'est pas disponible.