-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathindex.html
250 lines (216 loc) · 16.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>MSBuild Log Viewer</title>
<link href="styles.css" rel="stylesheet" />
<script src="scripts.js"></script>
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-115404565-4"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-115404565-4');
</script>
</head>
<body>
<div id="header">
<h1>MSBuild Binary and Structured Log Viewer</h1>
</div>
<div id="toc" class="tocRoot">
<h3>Contents:</h3>
<ul>
<li><a href="#usingdotnet">dotnet build -bl</a></li>
<li><a href="#usingbl">msbuild /bl</a></li>
<li><a href="#replay">Replaying a .binlog</a></li>
<li><a href="#MSBUILDDEBUGENGINE">Binlogs from Visual Studio</a></li>
<li><a href="#advantages">Binary log advantages</a></li>
<li><a href="#features">Viewer features</a></li>
<li><a href="#redaction">Sensitive data redaction</a></li>
<li><a href="#commandline">Command-line help for /bl</a></li>
<li><a href="#olderVersions">Recording a binary log with old MSBuild</a></li>
<li><a href="#ide">Investigating design-time builds</a></li>
<li><a href="#security">Security concerns</a></li>
<li><a href="#api">Reading MSBuild .binlogs programmatically</a></li>
<li><a href="#sourcecode">Source code on GitHub</a></li>
</ul>
</div>
<div class="buttonHost">
<a download href="https://github.com/KirillOsenkov/MSBuildStructuredLog/releases/latest/download/MSBuildStructuredLogSetup.exe" class="bigButton">Download MSBuild Structured Log Viewer</a>
<!--<a href="https://live.msbuildlog.com" class="bigButton">Open Online Structured Log Viewer</a>-->
</div>
<div>
<p>or, <a href="https://winget.run/pkg/KirillOsenkov/MSBuildStructuredLogViewer" target="_blank">install from WinGet</a>:</p>
<div class="nuget-badge">
<p><code><span>C:\> </span>winget install KirillOsenkov.MSBuildStructuredLogViewer</code></p>
</div>
</div>
<div>
<p>or, <a href="https://chocolatey.org/packages/msbuild-structured-log-viewer" target="_blank">install from Chocolatey</a>:</p>
<div class="nuget-badge">
<p><code><span>C:\> </span>choco install msbuild-structured-log-viewer</code></p>
</div>
</div>
<div>
<p><a href="https://github.com/KirillOsenkov/MSBuildStructuredLog/blob/main/README.md#installing-the-avalonia-version-on-mac" target="_blank">Instructions for Mac</a></p>
</div>
<h2 id="usingdotnet">dotnet build -bl</h2>
<p>You can produce binary logs from the <span class="inlineCode">dotnet build</span> command by passing the <span class="inlineCode">-bl</span> argument:</p>
<div class="code">dotnet build -bl</div>
<h2 id="usingbl">msbuild /bl</h2>
<p>Pass <span class="inlineCode">/bl</span> to record all build events to a binary log file:</p>
<img src="BinLogFromCommandLine.png" width="70%" />
<p>Double-click the <span class="inlineCode">.binlog</span> file to open it in MSBuild Structured Log Viewer:</p>
<img src="Screenshot1.png" width="100%" />
<h2 id="MSBUILDDEBUGENGINE">Binlogs from Visual Studio</h2>
<p>Before starting VS set the following environment variable as described <a href="https://github.com/dotnet/project-system/blob/main/docs/design-time-builds.md#visual-studio-2022-or-later" target="_blank">here</a>:</p>
<pre>
SET MSBuildDebugEngine=1
SET MSBUILDDEBUGPATH=c:\some\path
</pre>
<p>See more information about design-time builds here:<br /><a href="https://github.com/dotnet/project-system/blob/master/docs/design-time-builds.md">https://github.com/dotnet/project-system/blob/master/docs/design-time-builds.md</a></p>
<p>⚠️ There are known limitations in binlogs obtained via the Project System Tools, so the use of Project System Tools is discouraged.</p>
<h2 id="replay">Replaying a .binlog to reconstruct text logs</h2>
<p>You can pass a <span class="inlineCode">.binlog</span> file to MSBuild instead of a project/solution to replay it to other loggers, as if a real build was happening. This allows you to reconstruct a text log of any verbosity given the <span class="inlineCode">.binlog</span> file. Read more at: <a href="https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md#replaying-a-binary-log">https://github.com/Microsoft/msbuild/wiki/Binary-Log#replaying-a-binary-log</a></p>
<h2 id="advantages">Binary log advantages</h2>
<p>
<ul>
<li><span class="accent">Completeness</span> - records the exact events in order they happened during the build. You can replay a binary log into other loggers to reconstruct full text logs. Pass the <span class="inlineCode">.binlog</span> file to MSBuild.exe instead of a project/solution to replay the log as if the original build was happening.</li>
<li><span class="accent">Verbosity</span> - binary logs capture more information than even the most diagnostic-level text logs. The binary logger turns on various MSBuild switches to output more information, such as task inputs and target outputs.</li>
<li><span class="accent">Faster builds</span> - less overhead than a text log, can make builds significantly faster if other logs are disabled. They can be reconstructed later anyway if needed.</li>
<li><span class="accent">Smaller disk size</span> - a binary log is much smaller in size than a corresponding diagnostic-level text log (10-20x or more). This can result in significant storage savings on CI servers.</li>
<li><span class="accent">Easier to read/analyze</span> - text logs (especially from multi-processor builds) can become unwieldy, intertwined and hard to read. The viewer allows to collapse unneeded sections, as well as intelligent search.</li>
<li><span class="accent">Programmatic access</span> - All information is easily accessible programmatically for tools such as analyzers (whereas you need to parse text logs yourself and it's hard without a clearly defined structure) A <a href="#api">.NET API</a> is available to load and query binary logs.</li>
<li><span class="accent">Embedded source files</span> - optionally embed the source text of all project files and imported targets files used during the build, so it is possible to correlate log events with the source code. Preprocessed view (with all imports inlined) is available for each file (like <span class="inlineCode">/pp</span>).</li>
</ul>
</p>
<a href="https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md" target="_blank">Read more about the new MSBuild binary log format (*.binlog)</a>
<h2 id="features">Viewer Features</h2>
<p>The MSBuild Structured Log Viewer can build projects and solutions or open existing log files:</p>
<img src="Screenshot2.png" width="70%" />
<p>Leverage the source code of projects and targets embedded in the log file:</p>
<img src="ViewerOverview3.gif" width="100%" />
<p>The viewer supports two file formats:</p>
<ol>
<li><span class="inlineCode">*.binlog</span> (official MSBuild binary log format, produced by <span class="inlineCode">msbuild.exe /bl</span></li>
<li><span class="inlineCode">*.xml</span> (for large human-readable XML logs)</li>
</ol>
<p>The viewer can read all formats and can save to <span class="inlineCode">*.xml</span>.</p>
<a href="https://github.com/KirillOsenkov/MSBuildStructuredLog/blob/master/README.md#features" target="_blank">See here for the list of viewer features</a>
<h2 id="redaction">Sensitive data redaction</h2>
<p>
Binlog is containing rich troubleshooting information, which can as well include some of the data, that users might not want to share with others (environment variables, local paths, secrets passed to tasks etc.)
To allow sharing of such binlogs Viewer offers option to redact data from binlog under File -> Redact menu:
</p>
<img src="Screenshot-redact.png" width="100%" />
<p>
Note that the autodetection option is currently supporting only a very limited number of patterns (and even after future extensions it can only be considered best-efforts redaction - not an exhaustive one). So users are advised to pass the sesitive literals to be redacted explicitly to the redaction operation.
</p>
<h2 id="commandline">Command-line help for the /bl switch</h2>
<p>See MSBuild command-line help <span class="inlineCode">msbuild /?</span> for more information on the <span class="inlineCode">/bl</span> switch. The switch is available starting with MSBuild 15.3 (Visual Studio 2017 Update 3 or newer).</p>
<div class="code">
/binaryLogger[:[LogFile=]output.binlog[;ProjectImports={None,Embed,ZipFile}]]
Serializes all build events to a compressed binary file.
By default the file is in the current directory and named
"msbuild.binlog". The binary log is a detailed description
of the build process that can later be used to reconstruct
text logs and used by other analysis tools. A binary log
is usually 10-20x smaller than the most detailed text
diagnostic-level log, but it contains more information.
(Short form: /bl)
The binary logger by default collects the source text of
project files, including all imported projects and target
files encountered during the build. The optional
ProjectImports switch controls this behavior:
ProjectImports=None - Don't collect the project
imports.
ProjectImports=Embed - Embed project imports in the
log file.
ProjectImports=ZipFile - Save project files to
output.projectimports.zip
where output is the same name
as the binary log file name.
The default setting for ProjectImports is Embed.
Note: the logger does not collect non-MSBuild source files
such as .cs, .cpp etc.
A .binlog file can be "played back" by passing it to
msbuild.exe as an argument instead of a project/solution.
Other loggers will receive the information contained
in the log file as if the original build was happening.
You can read more about the binary log and its usages at:
https://aka.ms/msbuild/binlog
Examples:
/bl
/bl:output.binlog
/bl:output.binlog;ProjectImports=None
/bl:output.binlog;ProjectImports=ZipFile
/bl:..\..\custom.binlog
/binaryLogger
</div>
<h2 id="olderVersions">Recording a binary log with older versions of MSBuild</h2>
<p>The built-in <span class="inlineCode">/bl</span> switch was only introduced in MSBuild 15.3 (Visual Studio 2017 Update 3). However there is a way to record a binary log with previous versions of MSBuild as well. You can attach the logger to any MSBuild-based build using the logger library targeting MSBuild 14: <span class="inlineCode">StructuredLogger.dll</span>. It is available in a NuGet package:</p>
<a href="https://www.nuget.org/packages/MSBuild.StructuredLogger.net45" target="_blank">MSBuild.StructuredLogger.net45</a>
<p>Or you could download it directly here: <a download href="https://msbuildlog.com/net45/StructuredLogger.dll">https://msbuildlog.com/net45/StructuredLogger.dll</a></p>
<p>Use a command-line such as this to pass the <span class="inlineCode">BinaryLogger</span> to MSBuild:</p>
<div class="code">msbuild solution.sln /t:Rebuild /v:diag /noconlog /logger:BinaryLogger,StructuredLogger.dll;1.binlog</div>
<h2 id="security">Security Warning</h2>
<p>The binary log contains and exposes all environment variables from the machine that the build ran on. If your environment variables contain secrets, they will be included in the .binlog file in plaintext.</p>
<p>Additionally, the source code of all project (.csproj) and targets files (.props, .targets, etc) is embedded in the .binlog file as well.</p>
<p>Some details from the file system (such as the name of the users folder) are visible as well.</p>
<p>However other source code (such as C# files) and files not related to the build are not included.</p>
<p>Before sharing binary log files please review the binary log file using the viewer to make sure there are no environment variables that should be kept private. Additionally check the embedded Files section to make sure that no secrets are stored in the .csproj files.</p>
<p>It is extremely important to be aware of these risks and it is recommended to treat the .binlog files like you treat your source code.</p>
<h2 id="api">Reading MSBuild .binlogs programmatically</h2>
<p>Reference the <a href="https://www.nuget.org/packages/MSBuild.StructuredLogger" target="_blank">MSBuild.StructuredLogger</a> NuGet package. All you need is to reference StructuredLogger.dll from that package.</p>
<p>You may also need to reference MSBuild <a href="https://www.nuget.org/packages/Microsoft.Build.Framework" target="_blank">Microsoft.Build.Framework</a>.</p>
<p>There are various APIs for various scenarios. A high-level API to read a .binlog file into a tree structure that you normally see in the viewer is:</p>
<div class="code">
using System;
using Microsoft.Build.Logging.StructuredLogger;
class BinaryLogReadBuild
{
static void Main(string[] args)
{
string binLogFilePath = @"C:\temp\test.binlog";
var buildRoot = BinaryLog.ReadBuild(binLogFilePath);
buildRoot.VisitAllChildren<CscTask>(c => Console.WriteLine(c.CommandLineArguments));
}
}
</div>
<p>There is a more formal API to read the C# compiler invocations from a binlog, read more here:</p>
<a href="https://github.com/KirillOsenkov/MSBuildStructuredLog/wiki/Reading-Compiler-invocations" target="_blank">https://github.com/KirillOsenkov/MSBuildStructuredLog/wiki/Reading-Compiler-invocations</a>
<p>If you need a lower-level API to read the raw .binlog records yourself you can use <span class="inlineCode">BinLogReader.ReadRecords(string binLogFilePath)</span>:</p>
<div class="code">
using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Logging;
using Microsoft.Build.Logging.StructuredLogger;
class BinLogReader
{
static void Main(string[] args)
{
string binLogFilePath = @"C:\temp\test.binlog";
var binLogReader = new BinLogReader();
foreach (var record in binLogReader.ReadRecords(binLogFilePath))
{
var buildEventArgs = record.Args;
// print command lines of all tool tasks such as Csc
if (buildEventArgs is TaskCommandLineEventArgs taskCommandLine)
{
Console.WriteLine(taskCommandLine.CommandLine);
}
}
}
}
</div>
<p>Another example of using the API is reading start/end times and durations of targets:</p>
<a href="https://github.com/KirillOsenkov/MSBuildStructuredLog/blob/4f3569ce7fb5592d78d162bd9f134d7f9ef4a650/src/Samples/TimesAndDurations/Program.cs#L23" target="_blank">https://github.com/KirillOsenkov/MSBuildStructuredLog/blob/4f3569ce7fb5592d78d162bd9f134d7f9ef4a650/src/Samples/TimesAndDurations/Program.cs#L23</a>
<h2 id="sourcecode">Source code on GitHub</h2>
<p>The MSBuild Structured Log Viewer project is open-source on GitHub at:<br /><a href="https://github.com/KirillOsenkov/MSBuildStructuredLog" target="_blank">https://github.com/KirillOsenkov/MSBuildStructuredLog</a></p>
<p>The Online Structured Log Viewer is open-source on GitHub at:<br /><a href="https://github.com/laurenprinn/MSBuildStructuredLog" target="_blank">https://github.com/laurenprinn/MSBuildStructuredLog</a></p>
<p>This webpage is also open-source at:<br /><a href="https://github.com/KirillOsenkov/MSBuildLog" target="_blank">https://github.com/KirillOsenkov/MSBuildLog</a></p>
</body>
</html>