Behandeln von MSBuild-Problemen und Erstellen von Protokollen

Mit den folgenden Verfahren können Sie Buildprobleme in Ihrem Visual Studio-Projekt diagnostizieren und ggf. ein Protokoll erstellen, das zur Untersuchung an Microsoft gesendet wird.

Ein Eigenschaftswert wird ignoriert

Wenn eine Projekteigenschaft offenbar auf einen bestimmten Wert festgelegt ist, aber keine Auswirkungen auf den Build zeigt, gehen Sie wie folgt vor:

1. Öffnen Sie die Visual Studio Developer-Eingabeaufforderung, die Ihrer Version von Visual Studio entspricht.

2. Führen Sie den folgenden Befehl aus, nachdem Sie die Werte für den Projektmappenpfad, die Konfiguration und den Projektnamen eingesetzt haben:

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

   Dieser Befehl generiert eine „vorverarbeitete“ MSBuild-Projektdatei (out.xml). Sie können diese Datei nach einer bestimmten Eigenschaft suchen, um zu sehen, wo diese definiert ist.

Der Build verwendet immer die letzte Definition einer Eigenschaft. Wenn die Eigenschaft zweimal festgelegt ist, wird der erste Wert durch den zweiten überschrieben. Darüber hinaus wertet MSBuild das Projekt in mehreren Durchläufen aus:

• PropertyGroups und Imports
• ItemDefinitionGroups
• ItemGroups
• Ziele

Bei der folgenden Reihenfolge gilt daher Folgendes:

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

Der Wert von MyMetadata für das MyFile.txt-Element wird während des Builds auf B gewertet (nicht auf A und nicht leer).

Beim inkrementellen Build wird mehr erstellt als erwartet

Wenn MSBuild ein Projekt oder ein Projektelement unnötigerweise neu generiert, erstellen Sie ein detailliertes oder ein binäres Buildprotokoll. Sie können das Protokoll nach der Datei durchsuchen, die unnötigerweise erstellt oder kompiliert wurde. Die Ausgabe sieht in etwa folgendermaßen aus:

  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

Wenn Sie den Build in der Visual Studio-IDE (mit detaillierter Ausführlichkeit im Ausgabefenster) erstellen, wird die Ursache dafür, dass die einzelnen Projekte nicht aktuell sind, im Ausgabefenster angezeigt:

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.

Erstellen eines detaillierten Protokolls

1. Wechseln Sie im Visual Studio-Hauptmenü zu Extras>Optionen>Projekte und Projektmappen>Erstellen und ausführen.

2. Legen Sie Ausführlichkeit der Protokolldatei des MSBuild-Projektbuilds in beiden Kombinationsfeldern auf Detailliert fest. Das erste steuert die Buildausführlichkeit im Ausgabefenster, und das zweite steuert die Buildausführlichkeit in der {projectname}.log-Datei, die während des Buildvorgangs im Zwischenverzeichnis der einzelnen Projekte erstellt wird.

3. Geben Sie an einer Visual Studio Developer-Eingabeaufforderung einen der folgenden Befehle ein, und setzen Sie dabei die tatsächlichen Werte für Pfad und Konfiguration ein:

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

   oder

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

   Eine MSBuild.log-Datei wird im Verzeichnis erstellt, aus dem Sie MSBuild ausgeführt haben.

Bereitstellen von MSBuild-Binärprotokollen zur Untersuchung

MSBuild verfügt über die Möglichkeit, eine detaillierte binäre Protokolldatei zu erfassen. Wenn Sie ein Buildproblem haben und ein binäres Protokoll bereitstellen können, kann das Protokoll hilfreich sein, um das Problem zu untersuchen.

Sie sollten jedoch wissen, welche Arten von Informationen im binären Protokoll erfasst werden, um sicherzustellen, dass Sie nicht versehentlich mehr freigeben, als Sie beabsichtigen. Das binär Protokoll erfasst fast alles, was Ihr Build tut, einschließlich der Inhalte Ihrer Projektdateien und aller Dateien (wie .props und .targets), die importiert werden, alle Aufgaben, die während des Builds ausgeführt werden, und die Eingabe- und Ausgabevariablen sowie Umgebungsvariablen, auf die in der MSBuild-Sitzung zugegriffen wurde. Es enthält in der Regel nicht den Inhalt der Quelldateien, die kompiliert werden, aber ihre vollständigen Namen und Pfade werden erfasst.

Hinweis

Einige Buildumgebungen stellen geheime Schlüssel mithilfe von Umgebungsvariablen zur Verfügung. Stellen Sie vor der Freigabe eines Binärprotokolls sicher, dass keine API-Token oder andere wichtige Geheimschlüssel verfügbar gemacht werden.

Erfassen von Binärprotokollen für Befehlszeilenbuilds

Sie können ein Binärprotokoll erstellen, indem Sie den -bl-Parameter an MSBuild (MSBuild.exe oder dotnet build) übergeben. Sie können den Inhalt der generierten .binlog-Datei mithilfe von MSBuild Structured Log Viewer oder in Ihrem Browser mithilfe von Live Structured Log Viewererkunden. MSBuild erfasst keine Daten aus binären Protokollen, die in Ihrem Browser angezeigt werden.

Beispiele

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

Hier finden Sie weitere Informationen zu binären Protokollen.

Erfassen von binären Protokollen über Visual Studio

So erfassen Sie Protokolle für alle MSBuild-Aufrufe:

Legen Sie die Umgebungsvariable MSBUILDDEBUGENGINE auf '1' fest und legen Sie MSBUILDDEBUGPATH (optional) auf einen vorhandenen Zielordner fest, um die erfassten Protokolle zu speichern. Starten Sie Dann Visual Studio aus derselben Shell, um die Umgebung zu erben:

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

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

MSBuild-Binärprotokolle werden dann an einem Speicherort erfasst, der über die Umgebungsvariable MSBUILDDEBUGPATH (oder standardmäßig auf den MSBuild_Logs-Unterordner eines aktuellen Ordners oder auf %temp%, basierend auf Zugriffsrechten) festgelegt ist.

Hinweis

Protokolle werden für jeden MSBuild-Aufruf (einschließlich Entwurfszeitbuilds) aufgezeichnet und im Ordner gespeichert, ohne ältere zu entfernen – sodass die Anzahl der Protokolldateien schnell wachsen kann. Es wird empfohlen, die Opt-In-Umgebungsvariable nur für die kurze Dauer der Wiedergabe des zu untersuchenden Problems festzulegen (obwohl es verständlich ist, dass einige nicht deterministische Probleme möglicherweise mehrere Reproduktionsversuche erfordern).

Erstellen eines binären MSBuild-Protokolls mit der Project System Tools-Erweiterung

In diesem Leitfaden finden Sie weitere Informationen zum Project System Tools-Repository zum Erfassen von Binlogs über Visual Studio.

1. Laden Sie die Project System Tools-Erweiterung herunter und installieren Sie sie.

2. Nachdem die Erweiterung installiert wurde, werden einige neue Elemente im Menü Ansicht>Weitere Fenster angezeigt.

   

3. Wählen Sie Ansicht>Weitere Fenster>Buildprotokollierung aus, um das Fenster Buildprotokollierung in Visual Studio anzuzeigen. Wählen Sie das erste Symbolleistensymbol aus, um die Aufzeichnung von regulären und Entwurfszeitbuilds im Projektsystem zu starten.

   

4. Nachdem ein Build aufgezeichnet wurde, wird er im Fenster „Buildprotokollierung“ angezeigt. Klicken Sie mit der rechten Maustaste auf das Element, und wählen Sie im Kontextmenü Protokolle speichern aus, um die .binlog-Datei zu speichern.

   

In der strukturierten MSBuild-Protokollanzeige können Sie Ihre .binlog-Dateien anzeigen und durchsuchen.

Zugehöriger Inhalt

• Problembehandlung für Visual Studio