Diagnosticar falhas de tarefas do MSBuild

MSB6006 é emitido quando uma tarefa MSBuild, uma classe derivada de ToolTask, executa um processo de uma ferramenta que retorna um código de saída diferente de zero se a tarefa não registar um erro mais específico.

Identificar a tarefa falhada

Quando você encontrar um erro de tarefa, a primeira etapa é identificar a tarefa que está falhando.

O texto do erro especifica o nome da ferramenta (um nome amigável fornecido pela implementação da ToolName tarefa ou o nome do executável) e o código de saída numérico. Por exemplo, no error MSB6006: "custom tool" exited with code 1. nome da ferramenta é custom tool e o código de saída é 1.

Para localizar a tarefa MSBuild com falha:

• Nas compilações de linha de comando: Se a compilação estiver configurada para incluir um resumo (o padrão), o resumo terá esta aparência:

  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 o erro ocorreu em uma tarefa definida na linha 19 do arquivo S:\MSB6006_demo\MSB6006_demo.csproj, em um destino chamado InvokeToolTask, no projeto S:\MSB6006_demo\MSB6006_demo.csproj.

• Na interface do usuário do Visual Studio: As mesmas informações estão disponíveis na lista de erros do Visual Studio nas colunas Project, Filee Line.

Encontre mais informações sobre falhas

O MSB6006 de erro é emitido quando a tarefa não registrou um erro específico. A falha ao registrar um erro geralmente ocorre porque a tarefa não está configurada para entender o formato de erro emitido pela ferramenta que chama.

Ferramentas bem comportadas geralmente emitem algumas informações contextuais ou de erro para sua saída padrão ou fluxo de erros, e as tarefas capturam e registram essas informações por padrão. Procure nas entradas de log antes que o erro ocorresse para obter informações adicionais. Pode ser necessário executar novamente a compilação com um nível de log mais alto para preservar essas informações. Com esperança, o contexto adicional ou os erros identificados no registo revelam a causa principal do problema. Caso contrário, talvez seja necessário restringir as causas potenciais examinando as propriedades e os itens que são entradas para a tarefa com falha.

Depurar uma tarefa

Ao depurar tarefas do MSBuild, aqui ficam algumas dicas gerais.

• Restrinja o escopo do caso de reprodução tanto quanto possível (por exemplo, definindo /p:BuildProjectReferences=false e iniciando o MSBuild com um projeto específico ou um alvo específico) para ter menos código para trabalhar.
• Use a opção /m:1 de linha de comando MSBuild para ter um único processo MSBuild para depurar.
• Defina a variável MSBUILDDEBUGONSTART de ambiente como 1 para obter um depurador anexado ao MSBuild na inicialização.
• Defina um ponto de interrupção no Execute método da tarefa a ser executada.

Depurar uma tarefa personalizada

Se você estiver escrevendo código para uma tarefa personalizada, poderá facilitar a depuração adicionando uma chamada para invocar o depurador no método da Execute tarefa. Você pode proteger esse código com uma verificação de variável de ambiente, de modo que, quando um utilizador define essa variável de ambiente, a tarefa para e oferece ao utilizador a oportunidade de depurar. Você pode usar System.Diagnostics.Debugger.Launch ou System.Diagnostics.Debugger.Break para iniciar ou parar no depurador.

Você deve assegurar-se de adicionar o máximo de registos possível em uma tarefa personalizada para facilitar aos usuários a depuração da tarefa. Isso é importante quando você finalmente identifica o caso raiz de uma falha; Adicione código de registro suficiente para detetar e relatar esse modo de falha no futuro.

Considere configurar um ambiente de teste para uma tarefa usando xUnit. Consulte Testes de unidade C# no .NET Core usando dotnet test e xUnit. Você pode configurar o teste xUnit para usar a API do MSBuild para invocar o MSBuild programaticamente com um arquivo de projeto fictício que inclui as propriedades, itens e destinos necessários para executar a tarefa em questão. Em alguns casos, pode fazer sentido criar um mecanismo de compilação simulado. Você pode ver um exemplo em Teste de unidade de uma tarefa personalizada do MSBuild com o Visual Studio.

Em projetos SDK do .NET, você também pode modificar launchSettings.json para adicionar um perfil de depuração especial que executa MSBuild.exe com os argumentos de linha de comando e variáveis de ambiente mencionados anteriormente neste artigo.

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

Se você quiser ser solicitado a anexar seu próprio depurador em tempo de execução, defina a variável MSBUILDDEBUGONSTART de ambiente como 2. Isso pode ser útil quando você estiver usando um depurador diferente, como no macOS quando o Visual Studio não está disponível.