Build Perf Baseline

Build Performance Baseline & Optimization

Overview

Before optimizing a build, you need a baseline. Without measurements, optimization is guesswork. This skill covers how to establish baselines and apply systematic optimization techniques.

Related skills:

• build-perf-diagnostics — binlog-based bottleneck identification
• incremental-build — Inputs/Outputs and up-to-date checks
• build-parallelism — parallel and graph build tuning
• eval-performance — glob and import chain optimization

Step 1: Establish a Performance Baseline

Measure three scenarios to understand where time is spent. Keep the SDK, configuration, machine, environment variables, restore state, and build command consistent. Run each scenario at least three times, repeating its setup before every measured sample, and report the median plus the observed range; a single timing is not a baseline. Keep setup outside the timed interval. Save each sample's binlog under a unique name, outside generated output directories.

Cold Build (First Build)

No previous build output exists. Measures the full end-to-end time including restore, compilation, and all targets.

Before every cold sample, restore the same source state, run dotnet clean with the measured configuration, and remove only the confirmed, disposable output and intermediate directories for the measured projects. Include custom artifact paths, not just bin and obj, and obtain approval before deletion. Verify those outputs are absent before timing the next build.

This is an output-cold build, not necessarily a cold NuGet, OS, or compiler server cache. Choose and record a consistent cache/server policy for all samples; do not clear shared caches. If measuring uncached restore, use a separate, empty package cache for each sample.

# After repeating the cold setup; use a unique log name for each sample
dotnet build /bl:cold-build-1.binlog -m

Warm Build (Incremental Build)

Build output exists, some files have changed. Measures how well incremental build works.

Before every warm sample, restore the same baseline source contents and build successfully without timing it. Then apply the same small, build-relevant edit to the same source file and time the build. Keep the changed file set and edit identical across samples; do not let edits accumulate. Restore the baseline contents before the next sample and rebuild them outside the timed interval. Do not clean between that setup build and its measured build.

# Untimed setup after restoring baseline source contents
dotnet build -m

# Apply the same controlled source edit, then measure with a unique log name
dotnet build /bl:warm-build-1.binlog -m

No-Op Build (Nothing Changed)

Build output exists, nothing has changed. Compilation and correctly incremental targets should skip; compare timing with this build's other samples.

Before every no-op sample, restore the same baseline source contents and run an untimed setup build successfully. Then measure an identical build without edits, touching inputs, cleaning outputs, or changing properties. Keep restore and cache/server policy consistent with the other samples.

# Untimed setup after restoring baseline source contents
dotnet build -m

# Rebuild immediately without changes; use a unique log name for each sample
dotnet build /bl:noop-build-1.binlog -m

What Good Looks Like

Red flags:

• No-op time is repeatedly close to warm/cold time, or compilation targets rerun → investigate incrementality (see incremental-build)
• Warm build recompiles everything → project dependency chain forces full rebuild
• Restore dominates cold samples → measure dotnet restore and dotnet build --no-restore separately before changing project structure

Do not use universal duration or percentage thresholds to declare a bottleneck. Rank costs against the controlled samples and the build's own target/task timings.

Capture analyzer evidence

A binlog shows compiler/task timing, but granular analyzer timing requires an analyzer-reporting run. When supported by the SDK/compiler, capture:

dotnet build /bl:analyzers.binlog /p:ReportAnalyzer=true

Open the binlog in MSBuild Structured Log Viewer and inspect the analyzer summary under the compiler task. If granular timing is unavailable, compare otherwise identical samples with /p:RunAnalyzers=false as an attribution experiment; do not present disabling analyzers as the fix. Preserve analyzer enforcement in CI.

Recording Baselines

Record baselines in a structured way before and after optimization:

| Scenario    | Before  | After   | Improvement |
|-------------|---------|---------|-------------|
| Cold build  | 2m 15s  |         |             |
| Warm build  | 1m 40s  |         |             |
| No-op build | 45s     |         |             |

Step 2: Artifacts Output Layout

The UseArtifactsOutput feature (introduced in .NET 8) changes the output directory structure to avoid bin/obj clash issues and enable better caching.

Enabling Artifacts Output

<!-- Directory.Build.props -->
<PropertyGroup>
  <UseArtifactsOutput>true</UseArtifactsOutput>
</PropertyGroup>

Before vs After

# Traditional layout (before)
src/
  MyLib/
    bin/Debug/net8.0/MyLib.dll
    obj/Debug/net8.0/...
  MyApp/
    bin/Debug/net8.0/MyApp.dll

# Artifacts layout (after)
artifacts/
  bin/MyLib/debug/MyLib.dll
  bin/MyApp/debug/MyApp.dll
  obj/MyLib/debug/...
  obj/MyApp/debug/...

Benefits

• No bin/obj clash: Each project+configuration gets a unique path automatically
• Easier to cache: Single artifacts/ directory to cache/restore in CI
• Cleaner .gitignore: Just ignore artifacts/
• Multi-targeting safe: Each TFM gets its own subdirectory

Customizing

<!-- Change the artifacts root -->
<PropertyGroup>
  <ArtifactsPath>$(MSBuildThisFileDirectory)output</ArtifactsPath>
</PropertyGroup>

Step 3: Deterministic Builds

Deterministic builds produce byte-for-byte identical output given the same inputs. This is essential for build caching and reproducibility.

Enabling Deterministic Builds

<!-- Directory.Build.props -->
<PropertyGroup>
  <!-- Enabled by default in .NET SDK projects since SDK 2.0+ -->
  <Deterministic>true</Deterministic>

  <!-- For full reproducibility, also set: -->
  <ContinuousIntegrationBuild Condition="'$(CI)' == 'true'">true</ContinuousIntegrationBuild>
</PropertyGroup>

What Deterministic Affects

• Removes timestamps from PE headers
• Uses consistent file paths in PDBs
• Produces identical output for identical input