Table of Contents

Filters

Sometimes you don't want to run all of your benchmarks. In this case, you can filter some of them with the help of filters.

Predefined filters:

Filter Type Filters benchmarks by Console argument Console example
GlobFilter Provided glob pattern filter --filter Serializer.ToStream
AttributesFilter Provided attribute names attribute --attribute STAThread
AllCategoriesFilter All Provided category names categories --allCategories Priority1 CoreFX
AnyCategoriesFilter Any provided category names anycategories --anyCategories Json Xml
SimpleFilter Provided lambda predicate -
NameFilter Provided lambda predicate -
UnionFilter Logical AND -
DisjunctionFilter Logical OR -

Sample: IntroFilters

You can either use one of the predefined Filter types or create a custom type which implements IFilter interface.

Source code

using System.Threading;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Configs;
using BenchmarkDotNet.Filters;

namespace BenchmarkDotNet.Samples
{
    [DryJob]
    [Config(typeof(Config))]
    public class IntroFilters
    {
        private class Config : ManualConfig
        {
            // We will benchmark ONLY method with
            // names (which contains "A" OR "1") AND (have length < 3)
            public Config()
            {
                // benchmark with names which contains "A" OR "1"
                AddFilter(new DisjunctionFilter(
                    new NameFilter(name => name.Contains("A")),
                    new NameFilter(name => name.Contains("1"))
                ));

                // benchmark with names with length < 3
                AddFilter(new NameFilter(name => name.Length < 3));
            }
        }

        [Benchmark] public void A1() => Thread.Sleep(10); // Will be benchmarked
        [Benchmark] public void A2() => Thread.Sleep(10); // Will be benchmarked
        [Benchmark] public void A3() => Thread.Sleep(10); // Will be benchmarked
        [Benchmark] public void B1() => Thread.Sleep(10); // Will be benchmarked
        [Benchmark] public void B2() => Thread.Sleep(10);
        [Benchmark] public void B3() => Thread.Sleep(10);
        [Benchmark] public void C1() => Thread.Sleep(10); // Will be benchmarked
        [Benchmark] public void C2() => Thread.Sleep(10);
        [Benchmark] public void C3() => Thread.Sleep(10);
        [Benchmark] public void Aaa() => Thread.Sleep(10);
    }
}

Sample: IntroCategories

Combined together with [BenchmarkCategory] attribute, you can group the benchmarks into categories and filter them by categories.

Source code

using System.Threading;
using BenchmarkDotNet.Attributes;

namespace BenchmarkDotNet.Samples
{
    [DryJob]
    [CategoriesColumn]
    [BenchmarkCategory("Awesome")]
    [AnyCategoriesFilter("A", "1")]
    public class IntroCategories
    {
        [Benchmark]
        [BenchmarkCategory("A", "1")]
        public void A1() => Thread.Sleep(10); // Will be benchmarked

        [Benchmark]
        [BenchmarkCategory("A", "2")]
        public void A2() => Thread.Sleep(10); // Will be benchmarked

        [Benchmark]
        [BenchmarkCategory("B", "1")]
        public void B1() => Thread.Sleep(10); // Will be benchmarked

        [Benchmark]
        [BenchmarkCategory("B", "2")]
        public void B2() => Thread.Sleep(10);
    }
}

Command line examples:

--allCategories=A,B
--anyCategories=A,B

Sample: IntroJoin

If you are using BenchmarkSwitcher and want to run all the benchmarks with a category from all types and join them into one summary table, use the --join option (or BenchmarkSwitcher.RunAllJoined):

Source code

using System.Threading;
using BenchmarkDotNet.Attributes;

namespace BenchmarkDotNet.Samples
{
    // Run BenchmarkSwitcher with arguments: "--join --category=IntroJoinA"

    [DryJob]
    public class IntroJoin1
    {
        [Benchmark]
        [BenchmarkCategory("IntroJoinA")]
        public void A() => Thread.Sleep(10);

        [Benchmark]
        [BenchmarkCategory("IntroJoinB")]
        public void B() => Thread.Sleep(10);
    }

    [DryJob]
    public class IntroJoin2
    {
        [Benchmark]
        [BenchmarkCategory("IntroJoinA")]
        public void A() => Thread.Sleep(10);

        [Benchmark]
        [BenchmarkCategory("IntroJoinB")]
        public void B() => Thread.Sleep(10);
    }
}

Command line

--join --allCategories=IntroJoinA

Output

|       Type | Method |     Mean | Error |
|----------- |------- |---------:|------:|
| IntroJoin1 |      A | 10.99 ms |    NA |
| IntroJoin2 |      A | 12.50 ms |    NA |