MSBuildStructuredLog for binlog inspection and MSBuild diagnostics

Why MSBuildStructuredLog captures more than build output

MSBuildStructuredLog targets developers and build engineers who need to determine what MSBuild actually did during a build. Conventional build output can show commands, warnings, and errors, but this project records a structured representation of executed targets and tasks, including property and item values. That record is written as a binary log, or `*.binlog`, which the README describes as a portable log interchange format. The result is aimed at build investigations where the useful question is not merely whether the build failed, but which target ran, which task contributed an item, where a value came from, and how imported project files affected the result.

The repository also provides a log viewer rather than limiting the project to a text logger. It can open logs saved by MSBuild, display their execution trees, search embedded content, expose double writes, and show target dependencies. That makes it useful for maintainers working with solution files whose evaluation and execution are difficult to infer from command-line output alone. It is also relevant to teams dealing with nondeterministic file writes, since a log can reveal when files from different sources reach the same destination.

The logger does not change the build product or replace MSBuild itself. Its role is diagnostic. A developer records the execution, saves the log, opens it in the viewer, and examines the structured evidence later. This separation is useful because the original build can be reproduced or inspected without repeatedly changing project files to add temporary messages.

How binlog recording becomes an interactive MSBuild tree

The documented recording path relies on the `/bl` switch supported by `msbuild.exe` and `dotnet build`. During the build, MSBuildStructuredLog captures the structured events that describe project evaluation and execution. The resulting `msbuild.binlog` is placed in the same folder as the project or solution being built. The logger therefore sits at the build process boundary rather than asking developers to reconstruct activity from ordinary console text.

When the viewer opens a log, it presents nodes corresponding to the recorded build structure. The README identifies executed targets and tasks as central records, while the viewer can display property and item values and dependencies between targets. This arrangement supports questions that are difficult to answer from a linear transcript. For example, a developer can locate a target, inspect its related task, and examine the items or properties recorded around it. The README also documents search constraints using `under()` and `project()` clauses, which narrow results to a parent or project.

Logs may contain the source project files and every imported file used during the build. In that case, the viewer can list those files, search their full text, and open source code from many nodes. The documented Preprocess command inlines imports into project content, while ordinary logging can retain the actual source files for inspection. These are related views of MSBuild project evaluation, but they are not described as identical. Embedded files provide traceability to the build inputs, while preprocessing provides a consolidated project view.

The viewer also recognizes a particular nondeterminism pattern called double writes. This is when different sources write to the same destination during a build. Surfacing those writes does not establish which source is correct or repair the conflict. It gives the investigator a concrete event to inspect before deciding whether the build logic or file layout must change.

Installing the viewer on Windows, macOS, and Linux

For the Windows application, the README directs users to install it from `https://msbuildlog.com`. It documents automatic updates through Squirrel: after launch, the application checks for updates in the background, and the next launch starts the newly downloaded version. The listed Windows requirements are .NET Framework 4.7.2, MSBuild 17.0, and Visual Studio 2022. Those entries describe requirements for the documented Windows setup; they should not be treated as a complete installation procedure for every distribution.

On an Apple Silicon Mac, the README links to an `arm64` disk image. Intel Macs use the `x64` disk image. The Homebrew route is shorter and is the best documented first installation for macOS:

brew install structuredlogviewer

After installation, the exact launch command is not documented in the README, so none should be inferred here. The Mac documentation lists a .NET SDK as a requirement. For contributors building the Avalonia viewer on macOS or Linux, the repository provides this sequence:

git clone https://github.com/KirillOsenkov/MSBuildStructuredLog
cd MSBuildStructuredLog
./run.sh

The clone command downloads the repository, the second command enters its directory, and `run.sh` is the documented entry point. The longer publication route first builds `MSBuildStructuredLog.Avalonia.sln` and then publishes it as self-contained output:

dotnet build MSBuildStructuredLog.Avalonia.sln
dotnet publish MSBuildStructuredLog.Avalonia.sln --self-contained -o <some_dir>

The README shows the first command as a numbered build instruction and the second as the publish command. An output directory must be supplied to `-o`; the placeholder shown there is explanatory, not a literal directory name.

Creating and opening your first msbuild.binlog

A first diagnostic run does not require a project-specific logger package name or environment variable. The README shows that the standard `/bl` switch can be passed to either MSBuild or the .NET build command. The existing project arguments should be retained, because `/bl` adds recording rather than describing the target to build. The documented outcome is a file named `msbuild.binlog` in the same directory as the project or solution.

After recording, open `msbuild.binlog` through the viewer application. From there, the useful first action depends on the question being investigated. A failed or surprising build can be searched by task, target, property, item, or source content. If the result is too broad, the documented `under()` and `project()` clauses reduce the visible set. The viewer can then show target dependencies and copy selected nodes or their entire subtrees as text with `Ctrl+C`.

The log is not limited to display. The application can open and save log files, including saving a log to `.xml`. That option may be useful when a reviewer needs a representation outside the desktop viewer, although the README does not specify which viewer features remain available after converting or resaving a log. It also does not document a command-line batch analysis workflow, automated assertions, or rollback behavior. The documented path is primarily record, open, inspect, search, copy, and save.

For a first investigation involving source files, check whether the build actually embedded them. The README says logs can include project files and imported files, but it does not say that every existing log contains them. A log without embedded files can still represent execution, yet the file browser, full-text source search, and source-opening features have no embedded content to act on.

Viewer features that shorten MSBuild investigations

The most distinctive viewer feature is the combination of an execution tree with source inspection. When files are embedded, users can search across them rather than reconstructing imports one by one. Pressing Space or double-clicking most nodes opens source code, according to the README. This creates a direct path from a build event to the project text that may explain it.

The tree also supports targeted cleanup and extraction. The Delete key hides uninteresting nodes, which is useful when a solution build contains large amounts of unrelated activity. Conversely, `Ctrl+C` copies an item and its subtree to the clipboard as text. These controls make the viewer useful for moving evidence into an issue or discussion, although the README does not specify a machine-readable export workflow for copying subtrees.

Project preprocessing is available by right-clicking a project and selecting Preprocess. This creates a view with imports inlined, which can help when tracing effective project content. It should not be confused with opening an embedded import from the log. The former is an explicit preprocessing operation; the latter depends on source files having been captured.

Search scoping is more than a convenience in large builds. The README describes `under()` and `project()` clauses that filter displayed results. A search across every project may produce too many matches for a symptom such as a generated file or repeated property assignment. Scoping lets the investigator state the relevant boundary before comparing results. The README does not document the exact search syntax beyond those clause names, so the full syntax reference is linked separately at `https://msbuildlog.com/syntax`.

Automatic update behavior is also concrete on Windows. Squirrel performs a background check after launch, with the downloaded version starting on the next launch. That model has an operational consequence: an update is not described as an in-place hot replacement of the currently running process.

Platform limits, logger failures, and project upkeep

The main limitation is diagnostic scope. MSBuildStructuredLog explains what MSBuild recorded, but it does not determine the intended result of a build or automatically fix conflicting writes. Double-write detection can identify a nondeterministic destination, yet resolving it still requires deciding which producer should own that output. Similarly, source search depends on source files being embedded in the log.

Platform support also differs by distribution path. The README gives explicit Windows requirements and downloadable macOS disk images for `arm64` and `x64`. It provides source build instructions for the Avalonia viewer on macOS and Linux. It does not give a standalone Linux installation command, so a Linux user should not treat the macOS Homebrew command as documented Linux support. The exact Linux prerequisites for running a published build are also not specified.

If the logger itself crashes during a build, the documentation says it attempts to write the exception call stack to:

%localappdata%\Microsoft\MSBuildStructuredLog\LoggerExceptions.txt

That is a failure-reporting path, not a documented recovery mechanism. The README does not explain how the build continues after that write, whether recording is disabled, or whether a corrupt or incomplete `msbuild.binlog` can result. An automated build should therefore distinguish an ordinary MSBuild failure from a logger failure when diagnosing missing diagnostic data.

The project is not archived. Its last push was on 2026-10-08. Recent releases include v2.3.246 on 2026-08-20, v2.3.244 on 2026-08-13, and v2.3.240 on 2026-08-08. The README does not define a long-term support window or an upgrade compatibility policy for existing logs. Teams should verify whether an older log opens correctly before standardizing on a particular viewer version.

The repository uses the MIT license. Its acceptance and redistribution terms must be checked against the actual `LICENSE` file. The repository also contains `ThirdPartyNotices`, so teams that redistribute a packaged build should inspect that file for third-party notices. This is a licensing review step, not legal advice. Upgrade costs appear limited in the README, which documents viewer self-update behavior on Windows and a source-build workflow for the Avalonia application, but it gives no formal upgrade procedure for existing binlogs.

Editorial conclusion

Developers troubleshooting MSBuild execution should adopt the logger when they need a saved build record and interactive inspection. Projects that only need console output, or teams unable to manage generated logs and desktop tooling, should keep their current workflow. Verify first that every relevant build invocation can produce a binlog and that the selected viewer platform matches the development environment. On the documented Mac path, start with `brew install structuredlogviewer`, then confirm that `dotnet build /bl` creates `msbuild.binlog` where the solution or project is built.

Frequently asked questions

Official sources

1. Issues
2. KirillOsenkov/MSBuildStructuredLog on GitHub
3. License: MIT
4. README
5. Releases