Global Tool: dotnet benchmark

The dotnet benchmark global tool wraps BenchmarkHarness into a single command. Install it once, then run benchmarks against any .NET assembly without creating a dedicated host project.

dotnet tool install -g NBenchmark.Tool
dotnet benchmark

When to use the tool

The tool replaces Harness mode when you want to benchmark an existing project without adding a Program.cs, Main, and NuGet references. It is the fastest path from "I have a project with [Benchmark] methods" to "I have results."

You want to...	Use
Benchmark a project you already built	dotnet benchmark in the output directory
Build and benchmark in one step	dotnet benchmark --project ./MyBenchmarks
Benchmark a specific assembly	dotnet benchmark --assembly ./bin/Release/net10.0/MyLib.dll
Filter, configure output, set thresholds	All --filter, --reporter, --output, --threshold-pct flags work

Installation

dotnet tool install -g NBenchmark.Tool

Verify it works:

dotnet benchmark --help

To update:

dotnet tool update -g NBenchmark.Tool

Discovery modes

The tool finds benchmarks using one of three strategies.

Default: scan the current directory

Run dotnet benchmark in a directory containing compiled .dll files. The tool loads each .dll, checks for [Benchmark] methods, and runs any it finds.

cd ./MyApp/bin/Release/net10.0
dotnet benchmark

Assemblies without [Benchmark] methods are skipped silently.

--project: build and benchmark

Pass a .csproj path (or a directory containing one). The tool runs dotnet build -c Release, finds the output assembly, and benchmarks it.

dotnet benchmark --project ./MyApp.Benchmarks/MyApp.Benchmarks.csproj
dotnet benchmark --project ./MyApp.Benchmarks   # same, if only one .csproj

--assembly: explicit assembly path

Pass one or more .dll paths directly. Repeatable.

dotnet benchmark --assembly ./Lib1.dll --assembly ./Lib2.dll

All host flags pass through

Every flag supported by BenchmarkHarness works unchanged:

dotnet benchmark --filter "*Sort*"
dotnet benchmark --reporter json --output ./results
dotnet benchmark --iterations 500 --warmup 50
dotnet benchmark --detail advanced
dotnet benchmark --threshold-pct 20
dotnet benchmark --list
dotnet benchmark --dry-run
dotnet benchmark --in-process

See the CLI reference for the full flag list.

Default reporter

When no --reporter flag is given, the tool adds the console reporter automatically so you see results in the terminal. Pass any --reporter flag to override this default.

dotnet benchmark                              # console output
dotnet benchmark --reporter json              # JSON file only
dotnet benchmark --reporter json --reporter markdown  # both files

Process isolation

The tool inherits Harness mode's isolated-by-default execution. Each benchmark class runs in a clean child process unless you pass --in-process.

dotnet benchmark                              # isolated (default)
dotnet benchmark --in-process                 # all in-process

When using --project, the tool forwards the built benchmark assembly paths to child processes automatically, so isolated runs work from any working directory.

Examples

Quick check on a library

cd ./MyApp/bin/Release/net10.0
dotnet benchmark --filter "*Parse*"

Full CI gate

dotnet benchmark --project ./MyApp.Benchmarks \
  --reporter json --output ./bench-results \
  --threshold-pct 10

Compare two builds

# Before
dotnet benchmark --assembly ./old/MyApp.dll --reporter json --output ./before

# After
dotnet benchmark --assembly ./new/MyApp.dll --reporter json --output ./after

See also

• Harness mode - the project-based alternative
• CLI reference - all available flags
• Reporters - output formats
• Configuration - measurement options