How a .NET Build Works

Source: MSBuild: How MSBuild builds projects, Startup, Evaluation phase, Execution phase.

dotnet on the PATH is the muxer: a native host that decides whether its first argument is a command (build, test) or an application (dotnet app.dll). For a command it needs an SDK. It looks for a global.json in the current directory and each parent; if one exists, its sdk.version and sdk.rollForward choose among the installed SDKs, otherwise the newest installed SDK is used. The chosen SDK decides everything else on this page: the MSBuild version, the NuGet client, the C# compiler, the project SDKs and the default target framework of new projects.

Ledgerline pins the SDK in global.json (the keys are explained on Installing and Selecting SDKs):

When the pinned SDK is not installed — the classic case is a global.json updated by a developer whose CI agent still has the older SDK — the host fails before MSBuild even starts. With only SDK 10.0.402 installed, a global.json that asks for 10.0.500 gives:

(The installed-SDK list is written to standard output after the standard-error text, which is why it appears at the end when both streams go to the same terminal.)

Source: .NET: global.json matching rules, .NET: Select the .NET version to use.

Compilation needs to know which assemblies every package contributes for the target framework, so a build starts with a restore. dotnet build, run, test, pack and publish all run it implicitly; the documentation describes dotnet build as equivalent to dotnet msbuild -restore. -restore makes MSBuild run the Restore target in a separate evaluation and build first and then re-evaluate the project for the requested targets, because restore generates files that the second evaluation imports.

For each project, NuGet:

Running the build with the obj/ folder deleted but --no-restore shows what happens without the assets file:

The opposite mistake is quieter: changing a package version and then building with --no-restore uses the old assets file, so the build succeeds against the previous version. Use --no-restore only right after an explicit dotnet restore in the same job, which is exactly what CI does (CI Builds and Caching).

Source: .NET CLI: dotnet build, Implicit restore, NuGet: What happens when a NuGet package is installed?.

MSBuild starts by processing its command line: the project or solution to build (when none is given, the single project or solution file in the current folder; MSB1011 if there are several), global properties from -p:, the targets from -t:, loggers, verbosity and the node count. It also reads response files: MSBuild.rsp next to MSBuild.exe and Directory.Build.rsp in the project folder or any parent. dotnet build adds its own switches before calling MSBuild in-process; a diagnostic log (-v:diag) shows the full command line it built. For dotnet build --no-restore -tl:off in Ledgerline.Report:

-maxcpucount without a number (parallel build on all cores), minimal verbosity, the summary at the end and the Terminal Logger defaults are the CLI’s additions; the later --verbosity:diag wins over the earlier --verbosity:m. Without --no-restore the same line contains -restore instead of -restore:false, plus -restoreProperty: switches (EnableDefaultCompileItems=false and the other default-item globs) that make the separate restore evaluation cheaper by skipping the file globs restore does not need.

Global properties are the first trap of a build: a property passed with -p: (or set by Visual Studio, or by a parent project through the MSBuild task) overrides every assignment to that property in every project file, silently, unless the project uses TreatAsLocalProperty. dotnet build -p:Version=9.9.9 therefore wins over the <Version> in Ledgerline.csproj.

Source: MSBuild: Startup, MSBuild: Directory.Build.rsp.

Evaluation reads the project and every file it imports and builds an in-memory model. Nothing is built yet. It runs in six passes, and the pass order — not the order of the XML — is what decides which value a property or an item sees:

A ten-line project shows the consequences of the order:

-getProperty and -getItem (MSBuild 17.8 and later) print evaluated values without running any target, which is the quickest way to see what evaluation produced:

EarlyCopy is empty because the property pass is strictly sequential. JournalCount shows a subtler rule: an item reference inside a property defined outside a target is stored as literal text (the evaluated value really is @(Journal->Count())), and it is expanded only later, wherever the property is used during execution — which is why the Message task still prints 2. Relying on this lazy expansion is fragile; compute item-derived values inside a target, as CountInTarget does.

The same order explains two classic bugs:

Source: MSBuild: Evaluate environment variables, Evaluate imports and properties, Evaluate item definitions, Evaluate items, Evaluate UsingTask elements, Evaluate targets.

In the execution phase MSBuild first evaluates the properties and items that are inside targets, in the order they run, then orders and runs the requested targets. Build itself is empty; it depends on $(BuildDependsOn) = BeforeBuild;CoreBuild;AfterBuild, and CoreBuild depends on a long list that ends in Compile (which calls the C# compiler in CoreCompile), the copy to the output folder and IncrementalClean. Within one project targets run one at a time; MSBuild orders them with DependsOnTargets, BeforeTargets and AfterTargets (Targets and Build Order). With -m (on by default for dotnet build), separate projects build in parallel on worker nodes.

A detailed log (-v:d) names every target as it starts. For Ledgerline.Report, the 148 targets run by the main build include, in this order (abridged):

LedgerlineValidateJournals — a target from the Ledgerline.Build package with BeforeTargets="CoreCompile" — runs right before the compiler, which is how package build logic hooks itself into everyone else’s build without editing their project files. ResolvePackageAssets is where the assets file from step 2 is read.

A second build of an unchanged project skips the expensive targets, because their Inputs are not newer than their Outputs:

A target without Inputs and Outputs runs on every build — the most common reason why a "nothing changed" build is slow (Incremental Builds and Batching).

Source: MSBuild: Execution phase, MSBuild: Incremental builds.

obj/ holds everything intermediate: the restore files, then per configuration and TFM (obj/Debug/net10.0/) the generated sources (*.AssemblyInfo.cs, *.GlobalUsings.g.cs), the generated .editorconfig that analyzers read, the compiled assembly before it is copied, the reference assembly (ref/*.dll, metadata-only; the SDK produces it by default, controlled by ProduceReferenceAssembly), its internal twin (refint/) and the cache files that make the next build incremental. bin/Debug/net10.0/ holds what runs:

For an executable, the build output is directly runnable: since .NET Core 3.0 the package dependencies (Ledgerline.dll here) are copied next to the app, a native launcher (Ledgerline.Report, the apphost; .exe on Windows) is created from the SDK’s apphost template, and two JSON files tell the runtime what to load:

Ledgerline.Report.runtimeconfig.json (above) names the shared framework and its minimum version; the host rolls forward to the newest installed patch. Ledgerline.Report.deps.json lists every dependency and the path of each assembly inside its package ("lib/net10.0/Ledgerline.dll"), so the host can load them from the output folder. A library gets a .deps.json but no .runtimeconfig.json and no apphost. dotnet publish produces the same files for deployment (Publish and Deployment Models).

The output folders can be moved out of the project with the artifacts output layout (ArtifactsPath or UseArtifactsOutput, .NET 8 and later): all projects then write to artifacts/bin/<project>/<pivot>/ and artifacts/obj/<project>/.

Source: .NET CLI: Executable or library output, .NET: Artifacts output layout.

Visual Studio, Rider and VS Code with the C# Dev Kit all build with MSBuild and the selected SDK, so a project that builds with dotnet build builds in the IDE and vice versa. The documented differences are in how they call it: Visual Studio manages the project build order itself, builds each project with its own MSBuild invocation, does not create the metaproject that MSBuild generates for a command-line solution build, and runs frequent design-time builds (evaluations plus a few targets, with DesignTimeBuild=true) to populate IntelliSense. Conditions on $(BuildingInsideVisualStudio) or $(DesignTimeBuild) are therefore the only legitimate way for a project to behave differently in the IDE.

Source: MSBuild: Visual Studio builds vs. MSBuild.exe builds.

Each error has its own page in the MSBuild, SDK and NuGet troubleshooting pages.

The release-by-release lists are on the MSBuild and .NET SDK history pages.