# Microbenchmarking

Activate this skill when BenchmarkDotNet (BDN) is involved in the task, creating...

- Repository: https://github.com/dotnet/skills (5787 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dotnet/skills --skill microbenchmarking -g -a claude-code -y`
Codex: `npx skills add dotnet/skills --skill microbenchmarking -g -a codex -y`
Cursor: `npx skills add dotnet/skills --skill microbenchmarking -g -a cursor -y`
Gemini CLI: `npx skills add dotnet/skills --skill microbenchmarking -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add dotnet/skills`

## 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).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

The rest: https://github.com/dotnet/skills/blob/HEAD/plugins/dotnet-diag/skills/microbenchmarking/SKILL.md