DOCSEARCHbyAlgolia
Submit Docs

MSBuildStructuredLog

repository·main·Indexed 23 days ago

https://github.com/kirillosenkov/msbuildstructuredlog

A logger for MSBuild that records a structured representation of executed targets, tasks, property, and item values into a portable binary log format (*.binlog). It includes an interactive log viewer app for build investigations and the Binlog MCP server, which allows LLMs to navigate and query .binlog files using a specialized Domain Specific Language (DSL) and the Model Context Protocol.

Tokens
4.7K
Snippets
10
Records
27
Agent score
82%

What's inside MSBuildStructuredLog

  1. Key features of MSBuildStructuredLog

    main

    The MSBuildStructuredLog viewer provides several advanced investigation capabilities:

    • Preprocess Project Files: Inlines all imports for a clearer view of the project structure.
    • Embedded File Support: View lists of embedded files, perform full-text searches across all files, and use the Space key (or double-click) to view source code.
    • Double-write Detection: Identifies when files from different sources are written to the same destination, which can cause non-determinism.
    • Target Dependencies: Displays the dependency graph for each target.
    • Advanced Filtering: Use under() or project() clauses to narrow search results to specific parents or projects.
    • Tree Navigation: Use Delete to hide uninteresting nodes and Ctrl+C to copy a node and its entire subtree to the clipboard as text.
    • Log Export: Open and save log files, with an option to save them in .xml format.

  2. Understand the MSBuild binlog structure in BinlogMcp

    main

    A binlog is a recorded execution tree of an MSBuild build. When navigating via the MCP, you will encounter several major node kinds:

    • Build: The root node.
    • Project: Represents a project execution. Note that the same project can appear multiple times (e.g., once per target framework or target list).
    • Target: A specific target within a project.
    • Task: An individual task executed within a target.
    • Message / Error / Warning: Output generated by tasks.
    • ProjectEvaluation: A separate node from execution that holds evaluated Property and Item folders.
    • Folder: Groups related nodes (e.g., Properties, Items, Imports, Errors, Warnings).
    • Import / NoImport: Shows every <Import> resolved during the evaluation phase.
    • AddItem / RemoveItem: Logs mutations to item-groups during target execution.
    • CopyTask: Produces virtual file-copy results surfaced through the $copy token.

  3. Understand the MSBuildStructuredLog Object Model hierarchy

    main

    The MSBuildStructuredLog data is organized into a hierarchical tree structure starting from an ObservableObject. The model represents the relationships between MSBuild entities like Projects, Targets, Tasks, and Messages.

    Key structural components include:

    • TreeNode: The fundamental building block of the tree.
    • NamedNode: Represents specific MSBuild entities such as Project, Target, Task, Folder, Package, and Parameter.
    • TextNode: Contains diagnostic information, including Error, Warning, Message, Note, and Import nodes.
    • TimedNode: Wraps nodes that have timing information, such as Build, Project, Target, or specific Task executions.
    • Property & NameValueNode: Capture MSBuild properties and metadata.

    Understanding this hierarchy is essential for navigating the structured log data, as nodes are nested according to the MSBuild execution flow (e.g., a Project contains Targets, which contain Tasks, which may contain Messages or Properties).

  4. Correlate Project executions with Evaluations using evaluation id

    main

    ProjectEvaluation nodes include an id:N suffix. Project execution nodes reference this ID in their messages. You can correlate them by searching for the literal id:N string.

    Examples:

    • id:29: Finds both the ProjectEvaluation node with that ID and any Project execution nodes referencing it.
    • $projectevaluation id:29: Filters specifically to the ProjectEvaluation node for that ID.
    id:29
$projectevaluation id:29

  5. Compare `search` and `count` for result retrieval

    main

    When querying the binlog, choose between search and count based on your goal:

    • search <query>: Use this to see actual results. It is capped (default 200, max 5000). If the header says matched=N+, the cap was hit.
    • count <query>: Use this to get the exact total number of matches without the overhead of result formatting or pagination limits.

    Decision Rule:

    • "Show me a few examples" $\rightarrow$ search
    • "Is there 5 or 5,000 of these?" $\rightarrow$ count

  6. Identify binlog nodes using IDs

    main

    Nodes in the binlog are identified by specific ID formats:

    • [123]: Refers to a TimedNode where Index == 123.
    • [42/3.7]: A hierarchical path representing child 7 of child 3 of node 42.

    Note: On Project lines, the output may show → <name> to indicate the entry target, but the [id] still refers to the Project node itself, not the target.

  11. Regenerate Strings.json for localized MSBuild resources

    main

    The Strings.json file contains localized resource strings extracted from MSBuild. If you need to add new resource string IDs to the application, follow these steps:

    1. Open the ResourcesGenerator project.
    2. Add the required resource string IDs to the ResourceCreator.ResourceNames collection.
    3. Run the ResourcesGenerator tool to rebuild the Strings.json file.

  12. Basic search query syntax in MSBuild Structured Log Viewer

    main

    Queries consist of space-separated terms that are combined using an implicit AND logic. By default, matching is case-insensitive and performs a substring search.

    Matching Modes:

    • Substring match: Copying file matches any node containing both 'copying' and 'file'.
    • Literal/Phrase match: Use double quotes for exact phrases: "Copying file".
    • Exact (whole-string) match: Wrap a single word in double quotes to disable substring matching: "Copy".

    Tips:

    • The parser is whitespace-tolerant (e.g., under ( and under( are equivalent).
    • Use $kind filters first to narrow scope before adding broad text terms.
    • Use under() or notunder() for scoping instead of relying on free text.