| name | microbenchmarking |
| description | Activate when BenchmarkDotNet is involved or when a .NET performance question requires controlled microbenchmark measurement. Covers benchmark design, BDN configuration, project setup, cost-aware execution, side-by-side comparisons, diagnostics, and interpretation. Do not use for profiling/tracing, production telemetry, or load/stress testing.
|
| license | MIT |
Benchmark Authoring Guidelines
BenchmarkDotNet (BDN) is the default tool for controlled .NET microbenchmarks in this skill.
Dapper-FluentMap integration: prefer the existing benchmarks/Dapper.FluentMap.Benchmarks project. Preserve repository dependency/versioning conventions as they actually exist; this repository currently uses explicit PackageReference versions rather than Central Package Management. Do not introduce CPM as incidental benchmark work. Benchmark changes must not alter public behavior merely to improve measurements.
Benchmarks are comparative instruments
A single number has limited value. Identify the comparison axis first:
- mapping approaches;
- current vs candidate implementation;
- runtime/package versions;
- reflection/runtime mapping vs generated paths;
- input scale;
- allocation behavior;
- historical measurements.
See references/comparison-strategies.md before configuring non-trivial comparisons.
Benchmark lifecycle
Choose the use case before creating code:
- Coverage suite — permanent representative benchmarks.
- Issue investigation — task-scoped reproduction of a performance problem.
- Change validation — before/after validation for a PR.
- Development feedback — temporary experiment.
Only permanent coverage-suite benchmarks should automatically become repository code. Temporary experiments should remain isolated unless explicitly requested.
Cost awareness
Each BDN case has real wall-clock cost. [Params] creates Cartesian products and multiple jobs multiply the case count.
| Preset | Typical purpose |
|---|
--job Dry | correctness/compilation validation |
--job Short | quick development measurements |
| default | final normal measurements |
--job Medium | higher confidence |
--job Long | exceptional high-confidence runs |
Always estimate method × parameter × job case count before a large run.
Running benchmarks
Inspect the current benchmark entry point before assuming CLI forwarding. Use a narrow filter and redirect verbose output:
dotnet run --project ./benchmarks/Dapper.FluentMap.Benchmarks/Dapper.FluentMap.Benchmarks.csproj -c Release -- --filter "*MethodName" --noOverwrite > benchmark.log 2>&1
Run a dry representative case before longer measurements.
Writing new benchmarks
Determine the real caller scenario, comparison axis, input shape, setup/reset needs, parameter count, and whether allocation diagnostics matter.
Key invariants:
- return results when needed to prevent dead-code elimination;
- move initialization to
[GlobalSetup];
- do not add manual loops merely to increase measurement work;
- mark an explicit baseline;
- store inputs in fields/params rather than foldable constants;
- use seeded randomness for reproducibility;
- materialize deferred execution when execution is what should be measured;
- isolate global FluentMap/Dapper configuration so one case does not contaminate another.
See references/writing-benchmarks.md.
Dependency/setup rule
BenchmarkDotNet is already present in the repository benchmark project. Do not add another benchmark project or change dependency-management strategy unless the task demonstrates a need. If dependency versions change, follow the repository's existing package-version conventions and validate the benchmark project explicitly.
Diagnostics
Use references/diagnosers-and-exporters.md when timing alone is insufficient. Allocation data can be especially relevant for a mapping library.
Validation
- Build the benchmark project in Release.
- Run a dry representative case.
- Run a narrow real measurement.
- Confirm baseline and input set.
- Read generated Markdown/CSV results.
- Report runtime, hardware/OS and statistical limitations.
- Do not treat tiny differences inside measurement noise as meaningful regressions/improvements.
