MSBuild Performance Guidelines

MSBuild evaluates and builds thousands of projects in enterprise solutions. Performance is an architectural concern, not an afterthought.

Guiding Principle

Profile before optimizing; measure, do not guess. Use BenchmarkDotNet, the evaluation profiler (/profileevaluation), or ETW traces to identify actual bottlenecks before optimizing.

See evaluation-profiling.md and General_perf_onepager.md for profiling tools.

Allocation Awareness on Hot Paths

The evaluation and execution engines process millions of operations per build. Unnecessary allocations cause GC pressure that compounds across large solutions.

Rules

1. Avoid LINQ in hot paths. Where, Select, Any, First all allocate enumerator objects and delegate closures. Use foreach loops instead.

csharp // BAD — allocates iterator + delegate var match = items.FirstOrDefault(i => i.Name == name);

// GOOD — zero allocations foreach (var item in items) { if (item.Name == name) { / found / break; } }

1. Avoid string allocations in formatting. Use string.Concat, interpolation with Span<T>, or StringBuilder reuse — not string.Format on hot paths.

1. Prefer Span<T> and stackalloc for short-lived buffers when parsing or slicing strings. Avoid Substring when you only need to compare or inspect a portion.

1. Cache computed values. If a value is computed in a loop but doesn't change, hoist it out. If it's expensive and reused across calls, use a field or Lazy<T>.

String Comparison Rules

MSBuild property, item, and target names are case-insensitive. Getting this wrong causes subtle bugs and perf issues.

| Scenario | Use | |----------|-----| | Property/item/target names | MSBuildNameIgnoreCaseComparer | | General MSBuild identifiers | StringComparison.OrdinalIgnoreCase | | Dictionary keys for MSBuild names | MSBuildNameIgnoreCaseComparer as comparer | | File paths on Windows | StringComparison.OrdinalIgnoreCase | | File paths on Linux | StringComparison.Ordinal |

Never use ToLower()/ToUpper() for comparisons — they allocate a new string every time. Never use CurrentCulture for MSBuild identifiers — build behavior must not vary by locale.

Collection Type Selection

| Access Pattern | Recommended Type | |---------------|-----------------| | Small fixed set (< ~8 items) | Array or ReadOnlySpan<T> | | Build-once, read-many | ImmutableArray<T> (not ImmutableList<T>) | | Keyed lookup, many items | Dictionary<TKey, TValue> with appropriate comparer | | Keyed lookup, few items (< 5) | Linear scan over array (cache-friendly, avoids dict overhead) | | Concurrent reads, rare writes | ImmutableDictionary or snapshot pattern | | Ordered iteration needed | List<T> or array; avoid HashSet<T> if order matters |

ImmutableList<T> is almost never the right choice — it has O(log n) access vs O(1) for ImmutableArray<T>.

Hot Path Identification

These areas are performance-critical and require extra scrutiny:

• Expander.cs — property/item/metadata expansion during evaluation
• Evaluator.cs — project evaluation orchestration
• ItemSpec.cs / LazyItemEvaluator.cs — item evaluation and globbing
• TaskExecutionHost.cs — task parameter marshaling
• File I/O paths — FileMatcher.cs, glob operations, project loading

Inlining Considerations

For extremely hot methods, consider:

• [MethodImpl(MethodImplOptions.AggressiveInlining)] for small methods called millions of times
• Avoiding virtual dispatch in inner loops
• Using struct enumerators to avoid heap allocation

Evaluation Performance Specifics

• Import chain depth affects evaluation time linearly. Minimize unnecessary imports.
• Glob patterns are evaluated per-project. Overly broad globs (**/*) are expensive.
• Condition evaluation should use short-circuit logic — put cheap checks first.
• Property functions ($([System.IO.Path]::...)) are interpreted and slower than built-in operations.

Anti-Patterns

| Anti-Pattern | Why It's Bad | Fix | |-------------|-------------|-----| | items.Count() > 0 | Enumerates entire collection | items.Any() or check .Count property | | string.Format in log messages at Low importance | Allocates even if message is filtered | Use structured logging or guard with verbosity check | | new List<T>(enumerable).ToArray() | Double allocation | enumerable.ToArray() directly | | dict.ContainsKey(k) then dict[k] | Double lookup | dict.TryGetValue(k, out var v) | | Regex in a loop without RegexOptions.Compiled | Reinterprets pattern each time | Compile or use static Regex field |