Diagnóstico de errores de tareas de MSBuild

  • Artículo

MSB6006 se genera cuando una clase derivada de ToolTask ejecuta un proceso de herramienta que devuelve un código de salida distinto de cero si la tarea no ha registrado un error más específico.

Identificación de la tarea con errores

Cuando se produce un error de tarea, el primer paso es identificar la tarea que tiene errores.

El texto del error especifica el nombre de la herramienta (un nombre descriptivo proporcionado por la implementación de la tarea de ToolName o el nombre del ejecutable) y el código de salida numérico. Por ejemplo, en error MSB6006: "custom tool" exited with code 1. El nombre de la herramienta es custom tool y el código de salida es 1.

Para buscar la tarea de MSBuild con errores:

  • En las compilaciones de la línea de comandos: si la compilación se configura para incluir un resumen (el valor predeterminado), el resumen se verá así:

    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.

    Este resultado indica que el error se produjo en una tarea definida en la línea 19 del archivo S:\MSB6006_demo\MSB6006_demo.csproj, en un destino denominado InvokeToolTask, en el proyecto S:\MSB6006_demo\MSB6006_demo.csproj.

  • En la UI de Visual Studio: La misma información está disponible en la lista de errores de Visual Studio en las columnas Project, File y Line.

Búsqueda de más información sobre el error

El error MSB6006 se genera cuando la tarea no registra un error específico. El hecho de no poder registrar un error suele deberse a que la tarea no está configurada para comprender el formato de error generado por la herramienta a la que llama.

En general, las herramientas que se comportan correctamente emiten información contextual o de error a su salida estándar o flujo de error, y las tareas capturan y registran esta información de forma predeterminada. Para más información, examine las entradas de registro anteriores a la aparición del error. Puede que sea necesario volver a ejecutar la compilación con un nivel de registro superior para conservar esta información. Afortunadamente, el contexto o los errores adicionales identificados en el registro revelan la causa principal del problema. Si no es así, puede que deba examinar las propiedades y los elementos que son entradas a la tarea con error para delimitar las causas posibles.

Nota

MSBuild reconoce un formato de salida de diagnóstico específico. Los detalles de este formato se documentan en formato MSBuild y Visual Studio para los mensajes de diagnóstico.

Depurar una tarea

Consulte los siguientes consejos generales a la hora de depurar tareas de MSBuild.

  • Limite el ámbito del caso de reproducción tanto como sea posible (por ejemplo, mediante la configuración de /p:BuildProjectReferences=false e iniciando MSBuild con un proyecto específico o un destino específico) para tener menos código con el que trabajar.
  • Use la opción de línea de comandos de MSBuild /m:1 para tener un único proceso de MSBuild que depurar.
  • Cambie la variable de entorno MSBUILDDEBUGONSTART a 1 para que haya un depurador asociado a MSBuild al iniciarse.
  • Fije un punto de interrupción en el método Execute de la tarea para que vaya paso a paso.

Depurar una tarea personalizada

Si va a escribir código para una tarea personalizada, puede hace más sencilla la depuración agregando una llamada para invocar al depurador en el método Execute de la tarea. Puede cercar ese código con una variable de entorno, de modo que, cuando el usuario use esa variable de entorno, la tarea se detendrá y dará al usuario la oportunidad de realizar la depuración. Puede usar System.Diagnostics.Debugger.Launch o System.Diagnostics.Debugger.Break para iniciar o interrumpir el depurador.

Debe asegurarse de agregar tantos registros como sea posible en una tarea personalizada para que a los usuarios les resulta más fácil depurarla. Esto es importante cuando se termina identificando el caso raíz de un error; agregue suficiente código de registro para detectar y notificar ese tipo de error en el futuro.

Baraje la posibilidad de configurar un entorno de prueba para una tarea mediante xUnit. Consulte Prueba unitaria de C# en .NET Core mediante pruebas de dotnet y xUnit. Puede configurar la prueba de xUnit para usar la API de MSBuild e invocar MSBuild mediante código de programación con un archivo de proyecto simulado que incluya las propiedades, los elementos y los destinos que necesita para ejecutar la tarea en cuestión. En algunos casos, podría tener sentido crear un motor de compilación simulado. Puede ver un ejemplo en Prueba unitaria de una tarea personalizada de MSBuild con Visual Studio.

En los proyectos del SDK de .NET, también puede modificar launchSettings.json para agregar un perfil de depuración especial que ejecute MSBuild.exe con los argumentos de la línea de comandos y las variables de entorno mencionados anteriormente en este artículo.

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

Si desea que se le pida que adjunte su propio depurador en tiempo de ejecución, cambie la variable de entorno a MSBUILDDEBUGONSTART2. Esto puede resultar útil cuando se usa un depurador diferente, como en macOS, cuando Visual Studio no está disponible.