.NET is reshaping the CLI toolchain and full-stack build workflow through VMR (Virtual Monorepo). Its core value is to aggregate distributed repositories into an engineering system that supports unified compilation, bidirectional synchronization, and source-level auditability—solving consistency lag, version conflicts, and the difficulty of cross-repository refactoring. Keywords: VMR, Unified Build, Maestro.
Technical specification snapshot
| Parameter | Description |
|---|---|
| Primary languages | C#, F#, PowerShell, Bash, MSBuild XML |
| Core protocols/mechanisms | Git, Pull Requests, Source Build, NuGet dependency flow |
| Code organization | Hybrid Multi-Repo + Virtual Monorepo model |
| Synchronization components | Maestro, Darc, source-manifest.json |
| Build target | Build the complete .NET SDK from a single commit |
| Core dependencies | Arcade, MSBuild, Roslyn, Runtime, ASP.NET Core |
| Applicable scenarios | CLI toolchain evolution, cross-repository refactoring, supply chain auditing |
.NET’s move from multiple repositories to unified builds is an engineering system upgrade
Early .NET Core adopted a multi-repository strategy, allowing teams behind Runtime, SDK, ASP.NET Core, Roslyn, and other components to iterate independently. This model improved local agility, but it exposed systemic issues at product delivery time.
The most typical problem was not simply “too many repositories,” but an overly deep dependency graph. Once an upstream component changed, downstream components could only absorb it hop by hop along the chain. As a result, a .NET SDK at any given point in time was often assembled from dependencies captured at different moments, making global consistency difficult to maintain.
The multi-repository model slows down .NET CLI toolchain evolution
The CLI toolchain naturally depends on coordinated updates across Runtime, SDK, the packaging system, and installers. A single low-level API change often requires synchronized modifications across multiple repositories. If teams still rely on staged commits, the validation cycle becomes longer and the risk of version mismatch grows.
# View dependency subscription relationships in the current repository
# This command identifies how upstream repositories flow into the target repository
darc get-subscriptionsThe value of this kind of command is that it makes change propagation between repositories explicit, reducing the cost of manually tracing the dependency graph.
VMR provides full-stack consistency through a virtual monolithic view
VMR (dotnet/dotnet) is not a traditional monorepo. It is a unified view designed for the build system. Developers can still work in product repositories such as runtime or sdk, while the build system sees the complete product landscape inside the VMR.
This design balances two goals. First, it preserves compatibility with standard Git workflows used across the open-source ecosystem. Second, it allows .NET to build the entire SDK from a single source snapshot. That is the core prerequisite of Unified Build.
The VMR directory structure directly serves unified compilation
VMR typically maps upstream repositories under src/, such as src/runtime, src/sdk, and src/aspnetcore. The eng/ directory stores shared engineering infrastructure, while source-manifest.json records the commit hash associated with each subcomponent.
{
"sources": {
"runtime": {
"repositoryUrl": "https://github.com/dotnet/runtime",
"commit": "abc123"
},
"sdk": {
"repositoryUrl": "https://github.com/dotnet/sdk",
"commit": "def456"
}
}
}This manifest establishes the mapping from upstream commits to the unified snapshot in VMR. It is the metadata foundation for both forward flow and reverse flow.
The synchronization mechanism relies on Maestro and Darc for automated orchestration
Maestro acts as the control plane. It maintains subscription relationships, detects new builds, and automatically creates synchronization pull requests. Darc is the command-line entry point that developers use to inspect or adjust dependency flow rules.
Together, they effectively form a change scheduling bus for the .NET engineering system. They synchronize not only source code, but also dependency versions and build context, which makes them far more powerful than a simple Git mirror.
Forward flow brings product repository changes into the VMR
When a new commit is merged into dotnet/runtime, Maestro generates a patch based on the last synchronized hash, rewrites paths into the src/runtime/... form, applies the patch to the VMR, and updates source-manifest.json.
# Add a new subscription relationship
# Automatically flow build outputs from the upstream repository to the target repository
darc add-subscription \
--source-repo https://github.com/dotnet/runtime \
--target-repo https://github.com/dotnet/dotnetThis step institutionalizes repository relationships, so dependency updates do not rely on human memory or manual pull requests.
Reverse flow writes cross-repository changes back to product repositories
With Writable VMR, developers can complete cross-component refactoring directly inside the VMR. The system identifies which subdirectories a change belongs to, then automatically opens write-back pull requests against the corresponding product repositories, including updated dependency versions.
This makes “introduce a new API in Runtime and consume it immediately in SDK” an atomic operation. Teams no longer need to wait for multiple rounds of build propagation. This capability is especially important for improving .NET CLI tools.
Unified Build improves both auditability and supply chain security
The key benefit of Unified Build is not just build convenience. It binds the output of the .NET SDK to a single commit. That makes build inputs, toolchain versions, and dependency versions all traceable, which simplifies auditing and reproducibility.
This matters greatly for Linux distributions. They require software to be fully buildable from source and cannot depend on unauditable precompiled binaries. By materializing source code and standardizing scripts, VMR satisfies the compliance requirements of Source Build.
Reproducible builds are the core security value of VMR
Reproducible builds require the same source code to generate consistent binaries across different environments. VMR achieves this by locking inputs to a single commit, locking the toolchain through eng/common, and reducing environmental noise through path normalization.
# Prepare the Source Build environment
# This script is typically used for distribution or offline build scenarios
./prep-source-build.shThe value of scripts like this is that they bring environment preparation under version control, reducing contamination from external system state.
The developer workflow is evolving into a dual-loop model
Day-to-day small changes still fit best in individual product repositories, where repositories are lighter, IDEs respond faster, and local builds take less time. Only cross-stack refactoring or breaking upgrades need the outer loop of the VMR.
This dual-loop model avoids forcing every developer into an oversized repository, while still preserving atomic commit capability for complex changes. It is a more practical compromise than a pure monorepo.
VMR still has costs and boundaries
Its main trade-offs include large repository size, heavier full builds, potential conflicts in bidirectional synchronization, and more complex permission governance. Release branch transitions and conflict resolution in particular still require strong automation combined with human oversight.
AI Visual Insight: This image is ad creative from a page ad slot. It does not show architecture, code flow, or build system details, and it adds no direct technical information about VMR, the CLI toolchain, or synchronization mechanisms.
The foundation behind .NET CLI improvements is actually a repository and build model upgrade
Many developers interpret .NET CLI enhancements as command-level feature expansion. In reality, the deeper driver is an engineering infrastructure upgrade enabled by VMR, dependency flow, and Unified Build.
When the CLI must support new platforms, absorb Runtime features, preserve SDK consistency, and satisfy Source Build compliance at the same time, loose collaboration across scattered repositories is no longer enough. What VMR provides is not a new command, but a new delivery model.
FAQ
What is the fundamental difference between VMR and a traditional monorepo?
VMR is a “virtual monorepo”: unified for builds, distributed for development. A traditional monorepo usually expects all development to happen directly in a single repository. VMR is better suited to the open-source ecosystem and standard Git toolchains.
Why doesn’t .NET use Git submodules directly?
Submodules only preserve pointers. They cannot meet the needs of offline source builds, file filtering, or stable patch synchronization. VMR materializes code into repository history, which makes it better suited to Source Build and unified auditing.
How does VMR relate to improvements in the .NET CLI toolchain?
Many CLI upgrades depend on coordinated evolution across Runtime, SDK, installers, and dependency packages. VMR allows these changes to be validated together on a single commit, reducing version drift and improving delivery reliability.
Core summary: This article systematically explains the design motivation behind the .NET Virtual Monorepo (VMR), its directory model, the synchronization mechanism powered by Maestro and Darc, and how it supports Unified Build, Source Build, and supply chain security—helping developers understand the engineering upgrade behind the .NET CLI toolchain.