Performance Optimization Dotnet

Performance Optimization — .NET

Overview

Measure before optimizing. Performance work without measurement is guessing — and guessing leads to premature optimization that adds complexity without improving what matters. Profile first, identify the actual bottleneck, fix it, measure again. Optimize only what measurements prove matters.

.NET gives you two advantages no amount of guessing replaces:

• BenchmarkDotNet for deterministic micro-benchmarks (with statistical analysis built in — if you see a delta smaller than the tool's noise floor, it isn't a real change)
• dotnet-counters / dotnet-trace / PerfView for live process observation without redeploying

Use them. The rest of this skill assumes you will.

When to Use

• Performance requirements exist in the spec (latency SLAs, throughput targets, memory budgets)
• Users or monitoring (Application Insights, Prometheus, OpenTelemetry) report slow behavior
• p95 latency, Gen2 GC rate, thread-pool queue length, or allocated-bytes-per-request regresses
• You suspect a recent change introduced a regression
• Building features that handle large datasets or high traffic

When NOT to use: don't optimize before you have evidence of a problem. Premature optimization adds complexity that costs more than the performance it gains. Readable code beats 3% faster code.

.NET Performance Targets

Set targets as part of the spec, not as an afterthought. Representative targets for an ASP.NET Core service:

Desktop-specific (Avalonia, MAUI, WPF):

These are defaults; adjust to your actual product constraints and enforce with CI checks (BenchmarkDotNet gates, Application Insights alerts).

The Optimization Workflow

1. MEASURE   → Establish baseline with real data
2. IDENTIFY  → Find the actual bottleneck (not assumed)
3. FIX       → Address the specific bottleneck
4. VERIFY    → Measure again, confirm improvement
5. GUARD     → Add monitoring or tests to prevent regression

Step 1: Measure

Pick the tool that matches the symptom. You rarely need only one:

A representative BenchmarkDotNet smoke test:

[MemoryDiagnoser]                    // Tracks allocated bytes + GC collections
[SimpleJob(baseline: true)]           // Use multiple [SimpleJob] attributes to compare runtimes / args
public class TaskFormatBenchmarks
{
    private readonly TaskDto _task = new(/* ... */);

    [Benchmark(Baseline = true)]
    public string Interpolated() =>
        $"{_task.Title} ({_task.Status})";

    [Benchmark]
    public string Concatenated() =>
        _task.Title + " (" + _task.Status + ")";

    [Benchmark]
    public string StringBuilderBased()
    {
        var sb = new StringBuilder(_task.Title.Length + 16);
        sb.Append(_task.Title);
        sb.Append(" (");
        sb.Append(_task.Status);
        sb.Append(')');
        return sb.ToString();
    }
}

Run: dotnet run -c Release --project bench/MyApp.Bench. Never benchmark in Debug — the JIT is different, inlining is off, and [Conditional("DEBUG")] paths fire.

Step 2: Identify the Bottleneck

Use the symptom to narrow the search:

What is slow?
├── Cold start
│   ├── Too many assemblies loaded? --> dotnet-trace with runtime events,
│   │   check Ready-to-Run / ReadyToRun compilation coverage
│   ├── Static initializers? --> dotnet-trace CPU sampling on first 3 seconds
│   ├── Large configuration graph? --> IOptions bindings with ValidateOnStart firing on every key
│   └── Avalonia / WPF: UI thread doing I/O? --> dotnet-trace + dispatcher profiling
├── Request latency
│   ├── Slow SQL? --> Enable EF Core query logging, capture execution plan,
│   │   check .Include() chains (cartesian explosion)
│   ├── Sync-over-async? --> Search for .Result / .Wait() / .GetAwaiter().GetResult() in the request path
│   ├── Missing AsNoTracking on read paths? --> Check DbContext tracking behavior
│   ├── Missing output caching on a stable endpoint? --> AddOutputCache() in ASP.NET Core 7+
│   └── HttpClient misuse? --> Not using IHttpClientFactory; socket exhaustion at scale
├── Throughput
│   ├── Thread-pool starvation? --> dotnet-counters: System.Runtime.threadpool-queue-length > 0 sustained
│   ├── Lock contention? --> dotnet-trace with contention events; check Parallel.ForEach over shared dict
│   └── Kestrel limits? --> Check MaxConcurrentConnections, MaxConcurrentUpgradedConnections
├── Memory growth
│   ├── Static caches? --> dotnet-gcdump, look for types with unexpected instance counts
│   ├── Event handlers not unsubscribed? --> Especially in Avalonia/WPF view-models
│   ├── Strings cached indefinitely? --> Bounded MemoryCache with size limits, not Dictionary<string, T>
│   └── IDisposable not disposed? --> Analyzer CA2000 / CA1816 off? Turn them on
└── UI frame drops (Avalonia / MAUI / WPF)
    ├── Big lists not virtualized? --> ListBox with VirtualizingStackPanel (Avalonia default)
    ├── Binding on hot path? --> Compiled bindings (x:DataType + x:CompileBindings)
    ├── Heavy work on UI thread? --> Move to Task.Run; marshal results back via Dispatcher.UIThread.InvokeAsync
    └── Excessive DynamicResource subscriptions? --> Use StaticResource where the value won't change

Common bottlenecks by category:

ASP.NET Core / general server:

Avalonia / MAUI / WPF:

Step 3: Fix Common Anti-Patterns

EF Core N+1 Query

// BAD: N+1 — one query per order for its lines
var orders = await db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
foreach (var order in orders)
{
    order.Lines = await db.OrderLines.Where(l => l.OrderId == order.Id).ToListAsync();  // N queries
}

// GOOD: Single query with Include (watch for cartesian explosion when two .Include siblings both have many rows)
var orders = await db.Orders
    .Where(o => o.CustomerId == customerId)
    .Include(o => o.Lines)
    .ToListAsync();

// GOOD: Split query when two Include chains would Cartesian-explode
var ordersWithEverything = await db.Orders
    .Where(o => o.CustomerId == customerId)
    .Include(o => o.Lines)
    .Include(o => o.Shipments)
    .AsSplitQuery()          // Issues 1 + N queries — faster than Cartesian when both sides have many rows
    .ToListAsync();

// GOOD: Project to a DTO for read paths — fetches only the columns you need
var summaries = await db.Orders
    .Where(o => o.CustomerId == customerId)
    .Select(o => new OrderSummaryDto(o.Id, o.CreatedAt, o.Lines.Count))
    .AsNoTracking()
    .ToListAsync();

Sync-Over-Async

// BAD: blocks a thread-pool thread; under load → thread-pool starvation
public IActionResult Get(Guid id)
{
    var order = _service.GetByIdAsync(id).Result;   // BLOCK
    return Ok(order);
}

// GOOD
public async Task<IActionResult> Get(Guid id, CancellationToken cancellationToken)
{
    var order = await _service.GetByIdAsync(id, cancellationToken);
    return Ok(order);
}

.Result, .Wait(), .GetAwaiter().GetResult() in request-handling or UI paths are a red flag. The only acceptable uses are in composition-root startup synchronization and in documented adapter shims (see deprecation-and-migration).

Library code — add .ConfigureAwait(false). If the method lives in a class library that may be consumed from hosts that capture a SynchronizationContext (WPF, WinForms, MAUI UI thread, Avalonia dispatcher, older ASP.NET-on-.NET-Framework), append .ConfigureAwait(false) to every public await. Without it, the continuation marshals back to the caller's sync context, which (a) adds a thread-pool hop of overhead on each await and (b) sets up the classic deadlock when any upstream caller blocks on the returned Task (.Result / .Wait() / .GetAwaiter().GetResult()). In ASP.NET Core hosts this is a no-op — there is no SynchronizationContext since .NET Core 2.1 — but a library doesn't know which host will consume it, so default the posture to "ConfigureAwait(false) on every public-API await."

// Library method — targets unknown host
public async Task<OrderDto> GetAsync(Guid id, CancellationToken cancellationToken)
{
    var row = await _db.Orders
        .FindAsync([id], cancellationToken)
        .ConfigureAwait(false);                                           // ← don't capture sync context
    return row is null ? throw new OrderNotFoundException(id) : row.ToDto();
}

Unbounded Queries / Missing Pagination

// BAD: returns everything
app.MapGet("/api/tasks", async (AppDbContext db) =>
    await db.Tasks.ToListAsync());

// GOOD: cap at the boundary, even if the client asks for more
app.MapGet("/api/tasks", async (int page, int pageSize, AppDbContext db) =>
{
    var size = Math.Clamp(pageSize, 1, 100);   // Never trust clients on page size
    var skip = Math.Max(0, page - 1) * size;

    var items = await db.Tasks
        .OrderByDescending(t => t.CreatedAt)
        .Skip(skip)
        .Take(size)
        .AsNoTracking()
        .ToListAsync();

    return Results.Ok(items);
});

Allocation Discipline in Hot Paths

// BAD: repeated string concatenation in a loop allocates each step
string name = "";
foreach (var part in parts)
{
    name += part + " ";  // O(n^2) allocations
}

// GOOD: StringBuilder when the size is unknown
var sb = new StringBuilder(capacity: parts.Count * 8);
foreach (var part in parts)
{
    sb.Append(part);
    sb.Append(' ');
}
var name = sb.ToString();

// BETTER (when input types are known): interpolation + defined capacity
var name = string.Create(CultureInfo.InvariantCulture, stackalloc char[64],
    $"{first} {middle} {last}");

// Parsing: use Span<T> / ReadOnlySpan<char> to avoid substring allocations
ReadOnlySpan<char> input = s.AsSpan();
var commaIndex = input.IndexOf(',');
if (commaIndex < 0) return;
ReadOnlySpan<char> head = input[..commaIndex];
ReadOnlySpan<char> tail = input[(commaIndex + 1)..];

// Buffers that live beyond a stack frame: ArrayPool<T>.Shared
byte[] buffer = ArrayPool<byte>.Shared.Rent(4096);
try
{
    // use buffer
}
finally
{
    ArrayPool<byte>.Shared.Return(buffer);
}

Turn on [MemoryDiagnoser] on your BenchmarkDotNet runs so every change visibly moves the "Allocated" column. A "3% faster" change that allocates twice as many bytes is not a win.

HttpClient Misuse

// BAD: creates a fresh socket pool every call → socket exhaustion under load
public async Task<UserDto> GetAsync(Guid id, CancellationToken cancellationToken)
{
    using var client = new HttpClient { BaseAddress = new Uri("https://api.example.com/") };
    return await client.GetFromJsonAsync<UserDto>($"/users/{id}", cancellationToken);
}

// GOOD: register once in the composition root
// Program.cs
builder.Services.AddHttpClient<IUserClient, UserClient>(c =>
    c.BaseAddress = new Uri("https://api.example.com/"));

public sealed class UserClient(HttpClient http) : IUserClient
{
    public Task<UserDto?> GetAsync(Guid id, CancellationToken cancellationToken) =>
        http.GetFromJsonAsync<UserDto>($"/users/{id}", cancellationToken);
}

Output Caching (ASP.NET Core 7+)

// Program.cs
builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromSeconds(30)));
});

app.UseOutputCache();

app.MapGet("/api/catalog", async (ICatalogService svc, CancellationToken ct) =>
    await svc.ListAsync(ct))
   .CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(1)).SetVaryByQuery("category"));

Use output caching for endpoints whose response is safe to serve stale for a short window; use response caching + [ResponseCache] attributes for CDN-friendly caching.

Regex

// BAD: compiled-at-runtime on every call
if (Regex.IsMatch(input, @"\b[A-Z]{2,}\b")) { … }

// GOOD (.NET 7+): source-generated regex — zero startup cost, typed
[GeneratedRegex(@"\b[A-Z]{2,}\b")]
private static partial Regex AllCapsToken();

if (AllCapsToken().IsMatch(input)) { … }

Avalonia-Specific

• Keep VirtualizingStackPanel as the items panel for lists of >50 items (Avalonia's ListBox default — don't replace with StackPanel)
• Turn on x:CompileBindings="True" with x:DataType="..." — makes bindings type-checked and faster
• Prefer StaticResource for values that don't change at runtime (spacing, icon geometry); reserve DynamicResource for theme-sensitive brushes
• Avoid deep visual trees — DockPanel / Grid usually replaces nested StackPanel stacks

Kestrel & Hosting

builder.WebHost.ConfigureKestrel(options =>
{
    options.Limits.MaxRequestBodySize = 10 * 1024 * 1024;  // 10 MB — don't let random uploads dictate memory
    options.Limits.MaxConcurrentConnections = 10_000;       // Tune to container memory
    options.AddServerHeader = false;                         // Reduce fingerprinting
});

Set <ServerGarbageCollection>true</ServerGarbageCollection> in the host's .csproj (on by default for ASP.NET Core, but re-check for worker services).

Step 4: Verify

Re-run the same measurement you started with. Record the delta — specific numbers, not "feels faster":

BEFORE                           AFTER
p95 request latency   420 ms  →  95 ms
Allocations/request   180 KB  →  22 KB
Gen2/min              3       →  0
BenchmarkDotNet       Mean    2450 µs ± 140 µs  →  310 µs ± 18 µs

If the delta is inside the tool's noise floor, the change isn't real.

Step 5: Guard

Prevent regression:

• Commit the BenchmarkDotNet project to the repo; run it in CI on tag/release with a threshold check
• Add Application Insights / OpenTelemetry alerts on the metrics you care about (p95 latency, Gen2 rate, thread-pool queue)
• Add an analyzer rule if the fix was structural (e.g. Roslyn analyzer for .Result in a code path that must stay async)
• Document the fix in an ADR if the reasoning was non-obvious

Performance Budget

Set budgets and enforce them in CI:

p95 request latency   ≤ 100 ms        (per endpoint tag)
Allocated bytes/req   ≤ 10 KB          (measured via BenchmarkDotNet on the hot path)
Gen2/min              0 sustained      (alert fires on > 0 over 10 min)
Cold start (desktop)  ≤ 1.5 s
Startup memory        ≤ 150 MB working set
Throughput            ≥ 2 000 RPS single instance

A CI step for the allocation budget:

- name: BenchmarkDotNet — hot path allocation budget
  run: dotnet run -c Release --project bench/MyApp.Bench -- --filter *HotPath* --exporters json
- name: Enforce budget
  run: pwsh scripts/check-benchmark-budget.ps1 -Path BenchmarkDotNet.Artifacts/results -MaxBytesPerOp 10240

The script (a few lines of PowerShell) parses the JSON and fails the build when any benchmark exceeds the budget. Tune the numbers to your actual SLAs.

See Also

• Upstream performance-checklist reference (generic, pre-dates this adaptation): https://github.com/addyosmani/agent-skills/blob/44dac80216da709913fb410f632a65547866346f/references/performance-checklist.md
• integration-testing-dotnet — the testing harness you'll layer performance assertions into
• shipping-and-launch — the rollout thresholds table that consumes these metrics
• .NET performance docs: https://learn.microsoft.com/dotnet/core/diagnostics/
• BenchmarkDotNet: https://benchmarkdotnet.org/
• EF Core performance: https://learn.microsoft.com/ef/core/performance/
• Kestrel tuning: https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/options

Common Rationalizations

Red Flags

• Optimization without before/after measurements
• .Result / .Wait() / .GetAwaiter().GetResult() in request-handling or UI paths
• EF Core N+1 patterns (loops that call DbSet inside)
• Include chains where both sides have many rows (cartesian explosion) without AsSplitQuery()
• List endpoints without pagination or without a server-enforced PageSize cap
• new HttpClient() per-request
• Benchmarks run in Debug (invalid) or missing [MemoryDiagnoser]
• BenchmarkDotNet results without confidence intervals (single-run numbers)
• No monitoring on p95 latency, Gen2 rate, thread-pool queue length
• Manual string concatenation in loops; missing StringBuilder / Span<T> / ArrayPool<T> in hot paths
• Non-virtualized lists in Avalonia / WPF / MAUI
• Regex with runtime-compiled patterns in hot paths on .NET 7+ (use [GeneratedRegex])

Verification

After any performance-related change:

• Before and after measurements exist (specific numbers with tool-reported variance)
• The specific bottleneck was identified from a profile, not guessed
• The fix addresses the identified bottleneck, not a symptom elsewhere
• No N+1 patterns in new data-access code; all list endpoints paginate with a PageSize cap
• No .Result / .Wait() introduced in request-handling or UI paths
• BenchmarkDotNet run was in Release mode with [MemoryDiagnoser]
• Confidence intervals in BenchmarkDotNet output show the delta is outside the noise floor
• Monitoring dashboards reflect the new baseline (p95 latency, allocation rate, GC rate)
• Existing tests still pass (dotnet test) — optimization didn't break behavior
• Performance budget in CI still passes

Source & Modifications

• Upstream: https://github.com/addyosmani/agent-skills/blob/44dac80216da709913fb410f632a65547866346f/skills/performance-optimization/SKILL.md
• Pinned commit: 44dac80216da709913fb410f632a65547866346f (synced 2026-04-19)
• Status: rewritten
• Rationale: upstream's concrete tooling is JS/web-specific (Lighthouse, web-vitals RUM library, Core Web Vitals, <picture> responsive images, React useMemo/memo, bundle size, webpack/Vite tree-shaking). The equivalent .NET surface is entirely different (BenchmarkDotNet, dotnet-counters, dotnet-trace, PerfView, GC generations, EF Core, Kestrel, Span<T>/ArrayPool<T>). The five-step workflow and the "measure before optimizing" principle are preserved; everything else is retargeted.
• What changed (almost everything):
  • New skill name (performance-optimization-dotnet)
  • "Core Web Vitals Targets" table replaced with ".NET Performance Targets" — two tables (ASP.NET Core server + desktop UI) covering p95/p99 latency, throughput, allocations/request, Gen2 rate, thread-pool queue, working set, cold start, frame time, session memory growth
  • Step 1 "Measure" rewritten as a tool-matrix table (BenchmarkDotNet, dotnet-counters, dotnet-trace, dotnet-gcdump, PerfView, EventPipe, Application Insights/OpenTelemetry, EF Core logging / MiniProfiler); added a representative BenchmarkDotNet smoke test with [MemoryDiagnoser] + [SimpleJob(baseline: true)]; added the "never benchmark in Debug" warning
  • "Where to Start Measuring" decision tree fully rewritten for .NET symptoms (cold start → dotnet-trace StartupPerformance, request latency → EF Core logging / sync-over-async search, throughput → thread-pool counters / Kestrel limits, memory growth → dotnet-gcdump / event-handler leaks, UI frame drops → virtualization / compiled bindings)
  • Step 2 bottleneck tables split into ASP.NET Core / Avalonia-MAUI-WPF
  • Step 3 anti-pattern examples fully rewritten:
    • N+1 → EF Core Include / AsSplitQuery / projection to DTO + AsNoTracking
    • Sync-over-async (upstream had no equivalent)
    • Unbounded query → Math.Clamp(pageSize, 1, 100) + Skip/Take + AsNoTracking
    • Allocation discipline → StringBuilder, string.Create + stackalloc, ReadOnlySpan<char>, ArrayPool<T>.Shared
    • HttpClient misuse → IHttpClientFactory + typed client
    • Output Caching (ASP.NET Core 7+ AddOutputCache) — no upstream analog
    • Regex → [GeneratedRegex] (source-generated, .NET 7+)
    • Avalonia-specific → virtualization, compiled bindings, StaticResource vs DynamicResource, visual-tree depth
    • Kestrel / hosting → ConfigureKestrel, <ServerGarbageCollection>
  • Removed entirely: upstream's <picture> / srcset / AVIF/WebP image-optimization section, React re-render / memo / useMemo section, bundle-size / code-splitting / Suspense section, Lighthouse/Web Vitals measurement examples — none apply to .NET
  • Step 4 "Verify" adds an explicit before/after table format and a "noise floor" warning
  • New Step 5 "Guard" — BenchmarkDotNet in CI, Application Insights alerts, Roslyn analyzer rules, ADRs — expands upstream's one-line "add monitoring or tests"
  • "Performance Budget" fully rewritten with .NET-representative numbers and a PowerShell CI step parsing BenchmarkDotNet JSON
  • "See Also" adds links to Microsoft Learn diagnostics, BenchmarkDotNet docs, EF Core perf, Kestrel tuning
  • Common Rationalizations table adds: noise-vs-real improvements, Task.Run abuse, Gen2 pause costs, cold-start measurability
  • Red Flags list rewritten around .NET smells (.Result/.Wait(), cartesian Include, Debug-mode benchmarks, per-request HttpClient, runtime-compiled Regex, non-virtualized lists, missing [MemoryDiagnoser])
  • Verification checklist adds noise-floor check, [MemoryDiagnoser] requirement, monitoring dashboard reflection, CI budget pass
• What was preserved conceptually (principles, not content): "measure before optimizing" framing, the MEASURE → IDENTIFY → FIX → VERIFY → GUARD 5-step workflow (added GUARD as a proper step where upstream had it as a sub-bullet), the anti-pattern-fix-example structure, the "Performance Budget + CI enforcement" closing section, Common Rationalizations and Red Flags table shape
• Downstream patches (applied after the initial sync; not tracked against upstream):
  • 2026-04-19 (plugin v1.0.4) — Sync-Over-Async anti-pattern section now covers ConfigureAwait(false) in library code, with an explicit "no-op under ASP.NET Core since .NET Core 2.1" caveat and the deadlock-avoidance rationale. Keeps the skill set internally consistent with code-review-and-quality and incremental-implementation, which already carry the same guidance.
• License: MIT © 2025 Addy Osmani — see ../../LICENSES/agent-skills-MIT.txt