/microbenchmarking

name: microbenchmarking
description: >
  Activate this skill when BenchmarkDotNet (BDN) is involved in the task — creating,
  running, configuring, or reviewing BDN benchmarks. Also activate when
  microbenchmarking .NET code would be useful and BenchmarkDotNet is the likely
  tool. Consider activating when answering a .NET performance question requires
  measurement and BenchmarkDotNet may be needed.
  Covers microbenchmark design, BDN configuration and project setup, how to run
  BDN microbenchmarks efficiently and effectively, and using BDN for side-by-side
  performance comparisons.
  Do NOT use for profiling/tracing .NET code (dotnet-trace, PerfView), production
  telemetry, or load/stress testing (Crank, k6).
license: MIT

Benchmark Authoring Guidelines

BenchmarkDotNet (BDN) is a .NET library for writing and running microbenchmarks. Throughout this skill, "BDN" refers to BenchmarkDotNet.

> **Note:** Evaluations of LLMs writing BenchmarkDotNet benchmarks have revealed common failure patterns caused by outdated assumptions about BDN's behavior — particularly around runtime comparison, job configuration, and execution defaults that have changed in recent versions. The reference files in this skill contain verified, current information. **You MUST read the reference files relevant to the task before writing any code** — your training data likely contains outdated or incorrect BDN patterns.

Key concepts

• **Job** — describes how to run a benchmark: runtime, iteration counts, launch count, run strategy, and environment settings. Multiple jobs can be configured to run the same benchmarks under different conditions.
• **Benchmark case** — one method × one parameter combination × one job. The atomic unit BDN measures.
• **Operation** — the logical unit of work being measured. All BDN output columns (Mean, Error, etc.) report time per operation.
• **Invocation** — a single call to the benchmark method. By default, 1 invocation = 1 operation. With `OperationsPerInvoke=N`, each invocation counts as N operations.
• **Iteration** — a timed batch of invocations. BDN measures the total time for all invocations in an iteration, then divides by the total operation count to get per-operation time.

Benchmarks are comparative instruments

A single benchmark number has limited value — it can confirm the order of magnitude of a measurement, but the exact value changes across machines, operating systems, and runtime configurations. Benchmarks produce the most useful information when compared against something. Before writing benchmarks, identify the **comparison axis** for the current task:

• **Approaches (A vs B)**: comparing alternative implementations side-by-side in the same run.
• **Runtimes**: comparing the same code across .NET versions (e.g., net8.0 vs net9.0).
• **Package versions**: comparing different versions of a NuGet dependency.
• **Builds (before/after)**: comparing a saved DLL of the old code against the current source.
• **Runtime configuration (GC mode, JIT settings)**: understanding how runtime settings affect performance — compared via multiple jobs in a single run.
• **Scale (N=100 vs N=1000)**: understanding how performance changes as input size grows.
• **Hardware/OS**: comparing across different machines or operating systems — requires separate runs on each environment.
• **Historical measurements**: comparing against measurements recorded at a previous point in time.

BDN can compare the first six axes side-by-side in a single run, but each requires specific CLI flags or configuration that differ from what you might expect — read [references/comparison-strategies.md](references/comparison-strategies.md) for the correct approach for each strategy before configuring a comparison.

Use cases and benchmark lifecycle

There are four distinct reasons a developer writes a benchmark, and each one changes how the benchmark should be designed and where it should live:

1. **Coverage suite**: Write benchmarks to maximize coverage of real-world usage patterns so that regressions affecting most users are caught. These benchmarks are permanent — they belong in the project's benchmark suite, follow its conventions (directory structure, base classes, naming), and are checked in.

2. **Issue investigation**: Someone has reported a specific performance problem. Write benchmarks to reproduce and diagnose that specific issue. These benchmarks are task-scoped — they persist across the investigation (reproduce → isolate → verify fix) but are not part of the permanent suite.

3. **Change validation**: A developer has a PR or change and wants to understand its performance characteristics before merging. These benchmarks are task-scoped — they persist across the review cycle but are not checked in.

4. **Development feedback**: A developer is actively working on a task and wants to use benchmarks to evaluate approaches and get information early. These benchmarks are task-scoped and throwaway — they persist across the development session but are deleted when the decision is made.

For use case 1, add to the existing benchmark project following its conventions. For use cases 2–4, create a standalone project in a working directory that persists for the task but is clearly not part of the permanent codebase.

For **coverage suite** benchmarks, design from the perspective of real callers — what code patterns use this API, what inputs they pass, and what performance characteristics matter to them. Each permanent benchmark should justify its maintenance cost through real-world relevance. For **temporary benchmarks**, keep the case count intentional — each additional test case costs wall-clock time (read [Cost awareness](#cost-awareness)).

Cost awareness

Each benchmark case (one method × one parameter combination × one job) takes **15–25 seconds** with default settings. `[Params]` creates a Cartesian product: two `[Params]` with 3 and 4 values across 5 methods = 60 cases ≈ 20 minute