Устранение неполадок и создание журналов по проблемам MSBuild

Статья
09/22/2023

С помощью следующих процедур вы сможете диагностировать проблемы сборки в проекте Visual Studio и, при необходимости, создать журнал для отправки в корпорацию Майкрософт на изучение.

Значение свойства игнорируется

Если свойству проекта задано определенное значение, но это не отражается в сборке, сделайте следующее:

Откройте Командную строку разработчика Visual Studio, соответствующую вашей версии Visual Studio.
Заменив значения для пути решения, конфигурации и имени проекта, выполните следующую команду:
```
MSBuild /p:SolutionDir="c:\MySolutionDir\";Configuration="MyConfiguration";Platform="Win32" /pp:out.xml MyProject.vcxproj
```
Эта команда создает файл проекта MSBuild с предварительной обработкой (out.xml). Этот файл можно найти для определенного свойства, чтобы узнать, где он определен.

Последнее определение этого свойства и будет использоваться в сборке. Если свойство задано дважды, второе значение переопределяет первое. Кроме того, MSBuild оценивает проект в несколько этапов:

элементы PropertyGroup и Import;
элементы ItemDefinitionGroups;
элементы ItemGroup;
Целевые объекты

Следовательно, этапы выполняются в таком порядке:

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

Значение MyMetadata элемента вычисляется B во время сборки (не A и MyFile.txt не пустое).

При добавочной сборке выполняются ненужные операции сборки

Если MSBuild без необходимости перестраивает проект или элемент проекта, создайте подробный или двоичный журнал сборки. В журнале можно выполнить поиск по файлу, который был создан или скомпилирован без необходимости. Выходные данные выглядят примерно так:

  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

Если вы выполняете сборку в среде IDE Visual Studio (с детализацией окна вывода), в окне вывода для каждого проекта отображается причина, по которой он неактуален:

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.

Создание подробного журнала

В главном меню Visual Studio последовательно выберите пункты Средства>Параметры>Проекты и решения>Сборка и запуск.
Задайте для проекта MSBuild подробные сведения о детализации в обоих полях со списком. Верхняя часть элементов управления детализацией сборки в окне вывода, а вторая — подробность сборки в {projectname}.log файле, созданном в промежуточном каталоге каждого проекта во время сборки.
В командной строке разработчика Visual Studio введите одну из этих команд, указав фактические значения для пути и конфигурации:
```
MSBuild /p:Configuration="MyConfiguration";Platform="x86" /fl MySolution.sln
```
or
```
MSBuild /p:/p:SolutionDir="c:\MySolutionDir\";Configuration="MyConfiguration";Platform="Win32" /fl MyProject.vcxproj
```
Файл MSBuild.log создается в каталоге, из который вы запустили MSBuild.

Предоставление двоичных журналов MSBuild для исследования

MSBuild имеет возможность записывать подробный двоичный файл журнала. Если у вас возникла проблема со сборкой и вы можете предоставить двоичный журнал, журнал может оказаться полезным для изучения проблемы.

Однако следует знать, какой тип информации фиксируется в двоичном журнале, чтобы убедиться, что вы не случайно предоставляете общий доступ больше, чем вы планируете. Двоичный журнал захватывает практически все действия сборки, включая содержимое файлов проекта и всех файлов (например .props .targets, и) их импорта, все задачи, выполняемые во время сборки, а также входные и выходные данные, а также переменные среды, к которым был доступ в этом сеансе MSBuild. Обычно он не включает содержимое исходных файлов, скомпилированных, но записывает их полные имена и пути.

Примечание.

Некоторые среды сборки предоставляют секреты с помощью переменных среды. Перед предоставлением общего доступа к двоичному журналу убедитесь, что он не предоставляет маркеры API или другие важные секреты.

Запись двоичных журналов для сборок командной строки

Вы можете создать двоичный журнал, передав -bl параметр в MSBuild (MSBuild.exe или dotnet build). Содержимое созданного .binlog файла можно просмотреть с помощью средства просмотра структурированных журналов MSBuild или в браузере с помощью средства просмотра структурированных журналов в режиме реального времени. MSBuild не записывает данные из двоичных журналов, просмотренных в браузере.

Примеры

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

Дополнительные сведения о двоичных журналах см. в разделе "Дополнительные сведения".

Запись двоичных журналов с помощью Visual Studio

Чтобы записать журналы для всех вызовов MSBuild:

Задайте MSBUILDDEBUGENGINE для переменной '1' среды значение и (необязательно) установите MSBUILDDEBUGPATH в существующую папку назначения для хранения захваченных журналов. Затем запустите Visual Studio из той же оболочки, чтобы наследовать среду:

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

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

Затем двоичные журналы MSBuild записываются в расположение, указанное с помощью MSBUILDDEBUGPATH переменной среды (или по умолчанию для MSBuild_Logs вложенной папки текущей папки или %temp%на основе прав доступа).

Примечание.

Журналы записываются для каждого вызова MSBuild (включая сборки времени разработки) и хранятся в папке без удаления старых файлов, поэтому количество файлов журналов может быстро увеличиваться. Рекомендуется задать переменную среды согласия только на короткий срок воспроизведения проблемы, которую следует исследовать (хотя понятно, что некоторые недетерминированные проблемы могут потребовать нескольких попыток воспроизведения).

Создание двоичного журнала MSBuild с помощью расширения Project System Tools

Ознакомьтесь с этим руководством в репозитории Project System Tools для записи двоичных журналов с помощью Visual Studio.

Скачайте и установите расширение Project System Tools.
После установки расширения в меню Вид>Другие окна появятся некоторые новые элементы.
Выберите Вид>Другие окна>Журнал сборки, чтобы открыть окно Журнал сборки в Visual Studio. Выберите первый значок панели инструментов, чтобы начать запись обычных сборок или сборок времени разработки в системе проекта.
После записи сборка отобразится в окне "Журнал сборки". Щелкните элемент правой кнопкой мыши и выберите "Сохранить журналы " в контекстном меню, чтобы сохранить .binlog файл.