# dotnet/msbuild architecture

> Architecture diagram of the GitHub repository dotnet/msbuild, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dotnet/msbuild
- Repository: https://github.com/dotnet/msbuild

## Overview

##### Project type and purpose
- MSBuild is a standalone build engine and CLI tool (not a web or desktop app). It reads XML‐based project/solution files, constructs build graphs, schedules and executes tasks, and emits logs/telemetry.
- The README confirms it’s a modular build platform with several components: CLI (`msbuild.exe`), engine libraries, tasks, utilities, logging, telemetry, and extensibility (BuildCheck, SDK res­olvers).

##### High‐level file‐structure analysis
- Top‐level “src” contains all code, subdivided into folders:
- `Microsoft.Build.CommandLine` (the CLI entrypoint)
- `Microsoft.Build.Engine` (core parsing, evaluation, graph, backend execution)
- `Microsoft.Build.Framework` (interfaces/contracts for tasks, loggers)
- `Microsoft.Build.Tasks` (built-in task implementations)
- `Microsoft.Build.Utilities` (helper classes for custom tasks/loggers)
- `BuildCheck` plugin (static analysis checks)
- `Logging`, `TelemetryInfra` subfolders under the engine and framework for logging and telemetry components
- `Tasks` (detailed implementations), `Utilities`, and other cross-cutting libraries
- The “eng” folder holds CI/build pipeline definitions but is outside the runtime architecture.

##### Core architectural components
a. CLI Layer
- `Microsoft.Build.CommandLine` (msbuild.exe)
- Parses command-line options, instantiates `BuildParameters`, chooses engine configuration
b. Project Model & Parser
- Construction (`Build/Construction`): builds in-memory DOM of XML project files
- Definition (`Build/Definition`): transforms that DOM into semantic objects (Project, ProjectProperty, ProjectItem)
c. Evaluator & Expander
- `Build/Evaluation`: evaluates conditions, expands properties/items, populates ProjectInstance
d. Graph Builder
- `Build/Graph`: constructs a dependency graph of targets across projects
e. Back-end Execution
- `Build.BackEnd.Components`:
- Request Builder (`RequestBuilder`): turns graph nodes into build work units
- Scheduler (`Scheduler`): orders work units, resolves dependencies, allocates resources
- Communications (`NodeManager`, `NodeLauncher`): orchestrates in-proc vs out-of-proc nodes
- FileAccess Manager: tracks file reads/writes for incremental builds and caching
- Caching (`Components/Caching`): stores intermediate results (ConfigCache, ResultsCache)
f. Task Execution Hosts
- In-proc or out-of-proc task hosts (`TaskExecutionHost`, `MSBuildTaskHost`) load and run tasks
g. Task Libraries
- `Microsoft.Build.Tasks` & `Tasks`: predefined tasks (Compile, Copy, Exec, etc.)
- `Utilities`: helper classes for tasks and logging
h. Logging & Telemetry
- `Build.Logging` (ConsoleLogger, BinaryLogger, DistributedLogger, TerminalLogger)
- `TelemetryInfra`: forwards data to telemetry backends
i. Extensibility & Plugins
- `BuildCheck`: custom static analysis checks loaded via the engine’s plug-in points
- SDK resolvers: discover .NET SDKs, NuGet packages

##### Relationships and data-flow
- msbuild.exe
→ parses command line
→ loads project XML via ProjectParser
→ builds DOM (Construction) and semantic model (Definition)
→ evaluates conditions and expands items (Evaluation)
→ constructs dependency graph (Graph)
→ request builder transforms graph into work units
→ scheduler dispatches work to task hosts (in-proc / out-of-proc)
→ tasks execute against file system/processes, generate events
→ logging components listen for build events → emit console output, binary logs, telemetry
→ on completion, msbuild.exe returns exit code

##### Architectural patterns and principles
- Layered architecture (CLI → Parsing → Evaluation → Graph → Execution → Logging)
- Plugin/extension points (TaskHost, BuildCheck, SDK Resolver)
- Event‐driven logging (publish/subscribe of build events)
- Process isolation (in-proc vs out-of-proc task execution, node orchestration)
- Caching and incremental build support

##### Detail
- Layers and major subcomponents (e.g., caching, communication, file access manager) without drawing every class.
- How the BuildCheck and SDK Resolver integrate into the pipeline (hook points in evaluation or execution).
- Build pipeline (CI folder under “eng”) is shown separately as it’s for development/CI, not runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["msbuild.exe (CLI)"]:::core
    end

    %% Parsing & Model
    subgraph "Parsing & Model"
        Parser["ProjectParser & DOM"]:::core
        Definition["Semantic Model"]:::core
    end

    %% Evaluation & Graph
    subgraph "Evaluation & Graph"
        Evaluator["Evaluator/Expander"]:::core
        GraphBuilder["Graph Builder"]:::core
    end

    %% Back-end Execution
    subgraph "Back-end Execution"
        subgraph Components
            RequestBuilder["Request Builder"]:::core
            Scheduler["Scheduler"]:::core
            Communications["Communications"]:::core
            FileAccessManager["File Access Manager"]:::core
            Caching["Caching"]:::core
        end
    end

    %% Task Execution Hosts
    subgraph "Task Execution Hosts"
        InProcHost["In-proc Host"]:::core
        OutOfProcHost["Out-of-proc Host"]:::core
    end

    %% Libraries & Utilities
    subgraph "Libraries & Utilities"
        TaskLibrary["Task Library"]:::plugin
        Utilities["Utilities"]:::plugin
    end

    %% Logging & Telemetry
    subgraph "Logging & Telemetry"
        Logging["Logging"]:::logging
        Telemetry["Telemetry"]:::logging
    end

    %% Extensibility & Plugins
    subgraph "Extensibility & Plugins"
        BuildCheck["BuildCheck Plugin"]:::plugin
        SDKResolvers["SDK Resolvers"]:::plugin
    end

    %% External Systems
    subgraph "External Systems"
        FileSystem["File System"]:::external
        Environment["Environment"]:::external
        NuGet["NuGet"]:::external
        EditorConfig["EditorConfig"]:::external
    end

    %% CI Pipeline
    subgraph "CI Pipeline"
        eng["eng (CI definitions)"]:::external
    end

    %% Data Flow
    CLI -->|"parses options"| Parser
    Parser -->|"builds DOM"| Definition
    Definition -->|"semantic model"| Evaluator
    Evaluator -->|"expanded instance"| GraphBuilder
    GraphBuilder -->|"graph nodes"| RequestBuilder
    RequestBuilder -->|"work units"| Scheduler
    Scheduler -->|"dispatch"| InProcHost
    Scheduler -->|"dispatch"| OutOfProcHost
    InProcHost -->|"execute tasks"| TaskLibrary
    OutOfProcHost -->|"execute tasks"| TaskLibrary
    TaskLibrary -->|"reads/writes"| FileSystem
    TaskLibrary -->|"uses"| Environment
    TaskLibrary -->|"restores packages"| NuGet
    Parser -->|"resolve SDKs"| SDKResolvers
    Evaluator -->|"hook checks"| BuildCheck
    InProcHost -->|"emit events"| Logging
    InProcHost -->|"emit telemetry"| Telemetry
    OutOfProcHost -->|"emit events"| Logging
    OutOfProcHost -->|"emit telemetry"| Telemetry
    Logging -->|"output to"| Environment
    Telemetry -->|"send to"| Environment

    %% Click Events
    click CLI "https://github.com/dotnet/msbuild/tree/main/src/MSBuild"
    click Parser "https://github.com/dotnet/msbuild/tree/main/src/Build/Construction"
    click Definition "https://github.com/dotnet/msbuild/tree/main/src/Build/Definition"
    click Evaluator "https://github.com/dotnet/msbuild/tree/main/src/Build/Evaluation"
    click GraphBuilder "https://github.com/dotnet/msbuild/tree/main/src/Build/Graph"
    click RequestBuilder "https://github.com/dotnet/msbuild/tree/main/src/Build/BackEnd/Components/RequestBuilder"
    click Scheduler "https://github.com/dotnet/msbuild/tree/main/src/Build/BackEnd/Components/Scheduler"
    click Communications "https://github.com/dotnet/msbuild/tree/main/src/Build/BackEnd/Components/Communications"
    click FileAccessManager "https://github.com/dotnet/msbuild/tree/main/src/Build/BackEnd/Components/FileAccesses"
    click Caching "https://github.com/dotnet/msbuild/tree/main/src/Build/BackEnd/Components/Caching"
    click InProcHost "https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/TaskExecutionHost/TaskExecutionHost.cs"
    click OutOfProcHost "https://github.com/dotnet/msbuild/tree/main/src/MSBuildTaskHost"
    click TaskLibrary "https://github.com/dotnet/msbuild/tree/main/src/Tasks"
    click Utilities "https://github.com/dotnet/msbuild/tree/main/src/Utilities"
    click Logging "https://github.com/dotnet/msbuild/tree/main/src/Build/Logging"
    click Telemetry "https://github.com/dotnet/msbuild/tree/main/src/Build/TelemetryInfra"
    click BuildCheck "https://github.com/dotnet/msbuild/tree/main/src/Build/BuildCheck"
    click SDKResolvers "https://github.com/dotnet/msbuild/tree/main/src/MSBuild/SdkResolvers"

    %% Styles
    classDef core fill:#aee,stroke:#000,stroke-width:1px
    classDef plugin fill:#afa,stroke:#000,stroke-width:1px
    classDef logging fill:#fea,stroke:#000,stroke-width:1px
    classDef external fill:#ccc,stroke:#000,stroke-width:1px
```
