Solucionar problemas e criar logs para problemas do MSBuild

Os procedimentos a seguir podem ajudá-lo a diagnosticar problemas de compilação no projeto do Visual Studio e, se necessário, crie um log para enviar à Microsoft para investigação.

Um valor da propriedade é ignorado

Se uma propriedade de projeto parece estar definida como um valor específico, mas não tem nenhum efeito na compilação, siga estas etapas:

1. Abra o Prompt de Comando do Desenvolvedor do Visual Studio que corresponde à sua versão do Visual Studio.

2. Execute o comando a seguir, depois de substituir os valores com o caminho de solução, a configuração e o nome do projeto:

   MSBuild /p:SolutionDir="c:\MySolutionDir\";Configuration="MyConfiguration";Platform="Win32" /pp:out.xml MyProject.vcxproj
   

   Esse comando produz um arquivo de projeto MSBuild "pré-processado" (out.xml). Você pode pesquisar nesse arquivo uma propriedade específica para ver onde ela está definida.

A última definição de uma propriedade é o que é consumido na compilação. Se a propriedade estiver definida duas vezes, o segundo valor substitui o primeiro. Além disso, o MSBuild avalia o projeto em vários passos:

• PropertyGroups e importações
• ItemDefinitionGroups
• ItemGroups
• Destinos

Portanto, dada a seguinte ordem:

<PropertyGroup>
   <MyProperty>A</MyProperty>
</PropertyGroup>
<ItemGroup>
   <MyItems Include="MyFile.txt"/>
</ItemGroup>
<ItemDefinitionGroup>
  <MyItems>
      <MyMetadata>$(MyProperty)</MyMetadata>
  </MyItems>
</ItemDefinitionGroup>
<PropertyGroup>
   <MyProperty>B</MyProperty>
</PropertyGroup>

O valor do MyMetadata item MyFile.txt é avaliado Bdurante o build (não A e não está vazio).

A compilação incremental está compilando mais do que deveria

Se o MSBuild está recompilando desnecessariamente um projeto ou item de projeto, crie um log de compilação detalhado ou binário. Você pode pesquisar no log pelo arquivo que foi criado ou compilado desnecessariamente. A saída é parecida com esta:

  Task "CL"

  Using cached input dependency table built from:

  F:\test\Project1\Project1\Debug\Project1.tlog\CL.read.1.tlog

  Outputs for F:\TEST\PROJECT1\PROJECT1\PROJECT1.CPP:
  F:\TEST\PROJECT1\PROJECT1\DEBUG\PROJECT1.OBJ
  Project1.cpp will be compiled because F:\TEST\PROJECT1\PROJECT1\PROJECT1.H was modified at 6/5/2019 12:37:09 PM.

  Outputs for F:\TEST\PROJECT1\PROJECT1\PROJECT1.CPP:
  F:\TEST\PROJECT1\PROJECT1\DEBUG\PROJECT1.OBJ

  Write Tracking Logs:
  Debug\Project1.tlog\CL.write.1.tlog

Se você estiver compilando no IDE do Visual Studio (com detalhamento de janela de saída detalhada), a Janela de Saída exibe a razão pela qual cada projeto não está atualizado:

1>------ Up-To-Date check: Project: Project1, Configuration: Debug Win32 ------

1>Project is not up-to-date: build input 'f:\test\project1\project1\project1.h' was modified after the last build finished.

Criar um log detalhado

1. No menu principal do Visual Studio, acesse Ferramentas>Opções>Projetos e soluções>Compilar e executar.

2. Defina a verbosidade de build de projeto do MSBuild como Detalhada em ambas as caixas de combinação. A parte superior controla a verbosidade de build na Janela de Saída e a segunda controla a verbosidade de build no arquivo {projectname}.log que é criado no diretório intermediário de cada projeto durante o build.

3. Em um prompt de comando do desenvolvedor do Visual Studio, digite um desses comandos, substituindo o caminho real e os valores de configuração:

   MSBuild /p:Configuration="MyConfiguration";Platform="x86" /fl MySolution.sln
   

   ou

   MSBuild /p:/p:SolutionDir="c:\MySolutionDir\";Configuration="MyConfiguration";Platform="Win32" /fl MyProject.vcxproj
   

   Um arquivo MSBuild.log é criado no diretório do qual você executou o MSBuild.

Fornecer logs binários do MSBuild para investigação

O MSBuild tem a capacidade de capturar um arquivo de log binário detalhado. Se você estiver tendo um problema de build e puder fornecer um log binário, o log poderá ser útil para investigar o problema.

No entanto, você deve estar ciente de que tipo de informação é capturada no log binário para garantir que você não está compartilhando inadvertidamente mais do que você pretende. O log binário captura quase tudo o que seu build faz, incluindo o conteúdo de seus arquivos de projeto e quaisquer arquivos (como .props e .targets) que eles importam, todas as tarefas que são executadas durante o build, bem como a entrada e a saída, bem como variáveis de ambiente que foram acessadas nessa sessão do MSBuild. Geralmente, ele não inclui o conteúdo dos arquivos de origem compilados, mas captura seus nomes e caminhos completos.

Observação

Alguns ambientes de build disponibilizam segredos usando variáveis de ambiente. Antes de compartilhar um log binário, verifique se ele não expõe tokens de API ou outros segredos importantes.

Capturar logs binários para builds de linha de comando

Você pode criar um log binário passando o parâmetro -bl para o MSBuild (MSBuild.exe ou dotnet build). Você pode explorar o conteúdo do arquivo gerado .binlog usando o Visualizador de Log Estruturado do MSBuild ou em seu navegador usando o Visualizador de Log Estruturado Ao Vivo. O MSBuild não captura dados de logs binários exibidos no navegador.

Exemplos

dotnet build -bl
dotnet build -bl:SpecificStep.binlog
MSBuild.exe -bl:ServiceRelease.binlog -p:Configuration=Release

Veja também Mais detalhes sobre logs binários.

Capturar logs binários por meio do Visual Studio

Para capturar logs para todas as invocações do MSBuild:

Defina a variável de ambiente MSBUILDDEBUGENGINE como '1' e (opcionalmente) definida MSBUILDDEBUGPATH como uma pasta de destino existente para armazenar os logs capturados. Em seguida, inicie o Visual Studio do mesmo shell para herdar o ambiente:

SET MSBUILDDEBUGENGINE=1
SET MSBUILDDEBUGPATH=C:\MSBuildReproLogs
devenv.exe MySolution.sln

$env:MSBUILDDEBUGENGINE = 1
$env:MSBUILDDEBUGPATH="C:\MSBuildReproLogs"
& "devenv.exe" MySolution.sln

Os logs binários do MSBuild são capturados em um local especificado por meio de variável de ambiente MSBUILDDEBUGPATH (ou padrões para subpasta MSBuild_Logs de uma pasta atual ou %temp%, com base em direitos de acesso).

Observação

Os logs são registrados para cada invocação do MSBuild (incluindo builds de tempo de design) e mantidos na pasta sem remover os mais antigos, de modo que o número de arquivos de log pode crescer rapidamente. É recomendável definir a variável de ambiente de aceitação apenas para a curta duração da reprodução do problema a ser investigado (embora seja compreensível que alguns problemas não determinísticos possam precisar de várias tentativas de reprodução).

Criar um log binário do MSBuild usando a extensão Ferramentas do Sistema de Projetos

Consulte este guia no repositório ferramentas do sistema de projeto para capturar binlogs por meio do Visual Studio.

1. Baixe e instale a extensão Ferramentas do Sistema de Projetos.

2. Após a extensão ser instalada, alguns novos itens aparecem no menu Exibir>Outras Janelas.

   

3. Selecione Exibir>Outras Janelas>Log de Build para mostrar a janela Log de Build no Visual Studio. Escolha o primeiro ícone da barra de ferramentas para iniciar a gravação de builds regulares e de tempo de design no sistema de projeto.

   

4. Depois que um build é gravado, ele aparece na janela Log de Build. Clique com o botão direito do mouse no item e selecione Salvar Logs no menu de contexto para salvar o arquivo .binlog.

   

Você pode exibir e pesquisar arquivos .binlog usando o Visualizador de Log Estruturado de MSBuild.

Conteúdo relacionado

• Solucionar problemas do Visual Studio