DEV Community: StepOne

How to Mock gRPC in .NET with WireMock.Net and Protobuf

StepOne — Wed, 16 Sep 2026 21:25:36 +0000

TL;DR

WireMock.Net can mock gRPC, but its built-in mechanism requires .proto definitions at runtime and routes body matching through dynamically shaped JSON. That weakens compile-time checks and separates test serialization from the generated protobuf contracts used by the application.

I contributed to the project for several months, learned its internals, and wrote my own extension.

WireMock.Grpc.Protobuf binds requests and responses to generated Google.Protobuf models. It can match an incoming request exactly or evaluate only the fields relevant to a test through a typed predicate:

Request.Create().WithBodyAsGoogleProtobuf(new HelloRequest { Name = "StepOne" });
Request.Create().WithBodyAsGoogleProtobuf((HelloRequest x) => x.Name == "StepOne");
Response.Create().WithBodyAsGoogleProtobuf(new HelloReply { Message = "Hello, StepOne!" });

The rest of the article explains the integration bug that led to the package, the relevant WireMock.Net extension points, and the five-byte gRPC message framing the matcher must handle.

How WireMock.Net Mocks gRPC Requests

First, I should explain how I ended up this deep inside WireMock.Net in the first place.

If you have followed StepOne for a while, you may remember that my journey into the depths of WireMock.Net began with an ordinary bug. At work, I use WireMock to mock gRPC calls to external services and test the transport layer.

// Пример встроенного grpc мока WireMock.Net
// Требуется загрузить .proto файл в память программы
var protoDefinitionText = File.ReadAllText(@"c:\grpc\greet.proto");
var protoDefinitionId = "GrpcGreet";
var server = WireMockServer.Start(useHttp2: true);
server
    .AddProtoDefinition(protoDefinitionId, protoDefinitionText)
    // обратите внимание на отсутствие типизации
    // и возможности контролировать сериализацию JSON
    .Given(Request.Create()
        .UsingPost()
        .WithPath("/grpc/greet.Greeter/SayHello")
        .WithBodyAsProtoBuf("greet.HelloRequest", new JsonMatcher(new
        {
            name = "stef"
        })))
    .WithProtoDefinition(protoDefinitionId)
    .RespondWith(Response.Create()
        .WithHeader("Content-Type", "application/grpc")
        .WithTrailingHeader("grpc-status", "0")
        .WithBodyAsProtoBuf("greet.HelloReply",
            new
            {
                message = "hello {{request.BodyAsJson.name}} {{request.method}}"
            })
        .WithTransformer());

Component tests give us confidence in integrations before code reaches a real environment. Everything should have worked smoothly, but I ran into a nasty problem. As soon as I added several mocks and requests began hitting all of them, the mock server logs filled with errors. Something was clearly wrong.

16.04.2026 13:50:43 [Error] : Getting a Request MatchResult for Mapping 'e4601a45-5ba3-4777-9e8f-f69c2465be93' failed. This mapping will not be evaluated. Exception: System.IO.EndOfStreamException: Attempted to read past the end of the stream.
   at ProtoBuf.ProtoReader.State.ThrowEoF() in /_/src/protobuf-net.Core/ProtoReader.State.ReadMethods.cs:line 809
   at ProtoBuf.ProtoReader.StreamProtoReader.Ensure(State& state, Int32 count, Boolean strict) in /_/src/protobuf-net.Core/ProtoReader.Stream.cs:line 395
   at ProtoBuf.ProtoReader.StreamProtoReader.ImplSkipBytes(State& state, Int64 count) in /_/src/protobuf-net.Core/ProtoReader.Stream.cs:line 403
   at ProtoBuf.ProtoReader.State.ReadWrapped[T](SerializerFeatures features, T value, ISerializer`1 serializer) in /_/src/protobuf-net.Core/ProtoReader.State.ReadMethods.cs:line 1092
   at proto_4(State&, GetCustomerSegmentsRequest)
   at ProtoBuf.Internal.Serializers.SimpleCompiledSerializer`1.ProtoBuf.Serializers.ISerializer<T>.Read(State& state, T value) in /_/src/protobuf-net/Internal/Serializers/CompiledSerializer.cs:line 107
   at ProtoBuf.ProtoReader.State.ReadAsRoot[T](T value, ISerializer`1 serializer) in /_/src/protobuf-net.Core/ProtoReader.State.ReadMethods.cs:line 1157
   at ProtoBuf.ProtoReader.State.DeserializeRoot[T](T value, ISerializer`1 serializer) in /_/src/protobuf-net.Core/ProtoReader.State.ReadMethods.cs:line 1137
   at ProtoBuf.Internal.DynamicStub.ConcreteStub`1.TryDeserializeRoot(TypeModel model, State& state, Object& value, Boolean autoCreate) in /_/src/protobuf-net.Core/Internal/DynamicStub.cs:line 211
   at ProtoBuf.Meta.TypeModel.DeserializeRootAny(State& state, Type type, Object value, Boolean autoCreate) in /_/src/protobuf-net.Core/Meta/TypeModel.cs:line 1083
   at ProtoBuf.ProtoReader.State.DeserializeRootFallback(Object value, Type type) in /_/src/protobuf-net.Core/ProtoReader.State.ReadMethods.cs:line 1247
   at ProtoBuf.Serializer.Deserialize(Type type, Stream source) in /_/src/protobuf-net/Serializer.Deserialize.cs:line 55
   at ProtoBufJsonConverter.Utils.SerializeUtils.ConvertProtoBufToObject(Assembly assembly, String inputTypeFullName, Byte[] protoBufBytes, Boolean skipGrpcHeader)
   at ProtoBufJsonConverter.Converter.ConvertAsync(ConvertToObjectRequest request, CancellationToken cancellationToken)
   at WireMock.Matchers.ProtoBufMatcher.DecodeAsync(Byte[] input, Boolean throwException, CancellationToken cancellationToken)
   at WireMock.Matchers.ProtoBufMatcher.IsMatchAsync(Byte[] input, CancellationToken cancellationToken)

I traced the WireMock source step by step. I checked how protobuf bytes became gRPC C# objects and back again, and precisely where the logic failed.

Then it clicked: the server simply iterated over every stub and tried to convert the bytes into incompatible message types. Imagine a child with a shape sorter. Instead of looking for the square hole, the child methodically tries to push the cube through every opening.

WireMock.Net searching for a mapping for an incoming protobuf message

I contacted the Netherlands-based author of WireMock, and we began looking for a solution together. During the design discussion, it became clear that a stub needed to reject a request early based on explicit properties such as the URL, headers, cookies, and other metadata. Put simply, the system should immediately pick the square hole for the cube instead of trying every hole in turn. This removed the errors and spared the server unnecessary work.

The discussion is available on GitHub: https://github.com/wiremock/WireMock.Net/issues/1442

Solving the problem across borders was open-source collaboration at its best. My pull request was merged, and the change shipped in a new NuGet package version. The collaboration gave WireMock.Net a new feature: EarlyMismatch.

Request.Create()
    .UsingPost()
    .WithPath("/grpc/greet.Greeter/SayHello")
    .WithEarlyMismatch(RequestMatcherType.Path)
    .WithBodyAsProtoBuf("greet.HelloRequest", new JsonMatcher(new
    {
        name = "stef"
    })));

Matching Generated Protobuf Messages Instead of JSON

Using WireMock in component tests exposed a serious problem.

As soon as the transport layer configured JSON serialization with its own settings, it became clear that WireMock ignored the application's configuration. The mock server processed data according to its own internal rules. As a result, WireMock and the production service interpreted the same contract differently.

The problem lay in the library's architecture. Users could not provide their own JSON settings instance at all. WireMock hid the configuration behind a private modifier and offered no extension points. If you wanted custom settings, you had to rewrite the entire layer.

I proposed changing the API so that settings could be supplied through the constructor. After several review iterations, the PR was accepted: https://github.com/StefH/JsonConverter/pull/22

WireMockServer = WireMockServer.Start(
    new WireMockServerSettings
    {
        DefaultJsonSerializer = new SystemTextJsonConverter(
            new JsonSerializerOptions
            {
                // ...
            }),
    });

At first glance, the change looks tiny—just one new constructor. Yet extension points like this are exactly what let an open-source library fit into a large enterprise project instead of forcing the project to conform to the library.

Capturing WireMock.Net Logs in xUnit

The next improvement addressed another architectural limitation.

WireMock can write logs directly to ITestOutputHelper, which is convenient when debugging the mock server. But as soon as the server moved into an xUnit fixture, that capability practically disappeared. An ITestOutputHelper object does not yet exist when the fixture is created, so the logger required something that xUnit could not yet provide.

You had to choose between a sound test architecture with a shared fixture and convenient WireMock logs.

I suggested a simple idea: accept a Func<ITestOutputHelper> factory instead of a ready-made ITestOutputHelper. The logger would then obtain the current object only when writing a message, after the test had started: https://github.com/wiremock/WireMock.Net/pull/1488

public class WireMockFixture
{
    public WireMockFixture()
    {
        WireMockServer = WireMockServer.Start(
            new WireMockServerSettings
            {
                Logger = new TestOutputHelperWireMockLogger(() => TestOutputHelper)
            });
    }

    public WireMockServer WireMockServer { get; }

    public ITestOutputHelper? TestOutputHelper { get; set; }
}

The change required only a few lines of code, but it made WireMock work properly with conventional xUnit fixtures and infrastructure.

Building WireMock.Grpc.Protobuf

Despite my work fixing bugs and improving the architecture, gRPC mocking in WireMock.Net remained weak and awkward:

.proto files had to be loaded into memory, which caused failures in GitLab runners.
There was no static typing and therefore no IDE completion.
Matching worked only through JSON, with no way to configure serialization because the comparison logic used an isolated data-processing pipeline.

That was enough to make me dig deeper and solve the problem by creating my own NuGet package.

WireMock.Grpc.Protobuf is based on a simple idea: a generated Google.Protobuf class is more than a DTO. It already knows the protobuf contract and can turn itself into a binary wire-format message through ToByteArray(). The extension therefore does not need to reload .proto files, build dynamic descriptors, or send the object through JSON. The same IMessage<T> type used by the application remains the source of truth.

Meanwhile, the WireMock.Net server exposes the original request body as a byte[]. The extension only needs to hook into the processing and matching pipeline:

internal sealed class RequestGoogleProtobufMatcher(IObjectMatcher matcher) : IRequestMatcher
{
    public double GetMatchingScore(IRequestMessage requestMessage, IRequestMatchResult requestMatchResult)
    {
        var matchResult = matcher.IsMatch(requestMessage.BodyAsBytes);
        return requestMatchResult.AddMatchDetail(
            new MatchDetail
            {
                Name = matchResult.Name,
                MatcherType = nameof(RequestGoogleProtobufMatcher),
                Score = matchResult.Score,
                Exception = matchResult.Exception
            });
    }
}

The matching logic does not even need to compare C# objects through Equals. It only needs to parse the incoming gRPC message and extract the protobuf payload. The standard is straightforward. Before transmission, a five-byte header is prepended to the payload: one byte stores the compression flag, and the next four store the message length in big-endian format. The raw protobuf bytes follow.

internal sealed class GrpcMessageMatcher<TMessage> : IObjectMatcher
    where TMessage : IMessage<TMessage>
{
    // ...
    private readonly TMessage _messageValue;

    private bool IsMessageMatch(byte[] inputBytes)
    {
        const int compressionFlagIndex = 0;
        const int headerLength = 5;
        if (inputBytes[compressionFlagIndex] != 0)
            return false;
        var sizeHeader = new ReadOnlySpan<byte>(inputBytes, 1, 4);
        var length = BinaryPrimitives.ReadUInt32BigEndian(sizeHeader);
        if (inputBytes.Length - headerLength < length)
            return false;
        var messageBytes = new ReadOnlySpan<byte>(_messageValue.ToByteArray());
        return messageBytes.SequenceEqual(new ReadOnlySpan<byte>(inputBytes, headerLength, (int)length));
    }
}

Matching a mock by request body now comes down to one simple question: do the protobuf bytes received over the network match the bytes of the expected typed object? There is no reflection, JSON, or dynamic deserialization. That is the solution's main strength: the Google.Protobuf generator has already solved the complexity once. It knows field numbers, wire types, and the encoding rules for strings and nested messages. The extension does not try to build yet another model on top of protobuf; it simply uses the contract's existing binary representation.

For less strict scenarios, the package offers another route: a typed Func<T, bool> predicate. We still need to process the incoming message's five-byte header to extract the payload. The resulting bytes are then converted into an object with MessageParser<T> and passed to the supplied predicate.

internal sealed class GrpcPredicateMatcher<TMessage> : IObjectMatcher
    where TMessage : IMessage<TMessage>, new()
{
    // ...
    private static readonly TMessage Empty = new();
    private static readonly MessageParser<TMessage> Parser = new(() => Empty);
    private readonly Func<TMessage, bool> _predicate;

    private bool IsPredicateMatch(byte[] inputBytes)
    {
        const int compressionFlagIndex = 0;
        const int headerLength = 5;
        if (inputBytes[compressionFlagIndex] != 0)
            return false;
        var sizeHeader = new ReadOnlySpan<byte>(inputBytes, 1, 4);
        var length = BinaryPrimitives.ReadUInt32BigEndian(sizeHeader);
        if (inputBytes.Length - headerLength < length)
            return false;
        var inputMessage = Parser.ParseFrom(new ReadOnlySpan<byte>(inputBytes, headerLength, (int)length));
        return _predicate.Invoke(inputMessage);
    }
}

The user chooses the desired strictness: compare the message byte for byte, or check only the fields that matter to the test. In both cases, WireMock remains an off-the-shelf mock server, while responsibility for understanding the protobuf contract stays with the library built for that exact job: Google.Protobuf.

Takeaways

WireMock.Grpc.Protobuf keeps the generated protobuf type as the contract shared by production code and component tests. Exact byte matching is appropriate when the complete message matters; typed predicates keep tests resilient when only selected fields are part of the behavior under test.

The package remains an extension to WireMock.Net rather than a replacement for it. WireMock continues to own the mock server and request pipeline, while Google.Protobuf owns protobuf parsing and serialization.

The implementation and package are available here:

GitHub: https://github.com/Stepami/wiremock‑protobuf
NuGet: https://www.nuget.org/packages/WireMock.Grpc.Protobuf

Related .NET Testing Guides

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

Visitor Pattern in C#: acyclic, type-safe, no downcasts, no runtime checks with Visitor.NET

StepOne — Wed, 16 Sep 2026 20:39:48 +0000

Visitor becomes painful when a design gains type checks, downcasts, and boilerplate faster than it gains useful behavior. Those costs are especially visible in compilers, static analyzers, and other systems that repeatedly traverse object hierarchies.

This article starts with the classic and acyclic Visitor variants, shows where their dispatch mechanics break down in C#, and then derives a type-safe alternative from covariance and contravariance. The result became Visitor.NET, a library I use in HydraScript for static analysis and intermediate-representation generation.

When to Use the Visitor Pattern in C

Where is this pattern useful?

The most obvious application is compiler construction, because Visitor is one of the best ways to process an Abstract Syntax Tree.
The Expressions and Roslyn APIs also require direct processing of syntax object models.
The Composite pattern represents a recursive tree-shaped data structure.

DSL development deserves a separate mention because it gives me an excuse to point to an interesting talk about the practical use of DSLs in messy enterprise systems.

I first encountered them at university. My department, IU-9 at Bauman Moscow State Technical University, specializes in compiler construction. That determined my thesis topic: creating an interpreted programming language.

I parsed source code into an AST, traversed the tree, and generated an instruction list for a virtual machine—roughly the following transformation:

In this domain, an AST is as fundamental as JSON is in commercial software development. Many core tasks revolve around it:

Initializing scopes and symbol tables
Static analysis
Preliminary optimization
Code generation
And much more

That makes convenient, efficient processing of these data structures important.

Putting Operations on the Element Types

This is why Visitor was created. The flawed intrusive approach extends a recursive data structure through inheritance and subtype polymorphism:

public abstract class AbstractSyntaxTreeNode
{
    public virtual List<Instruction> ToInstructions(int start) => new();
}

This shortsighted design leads to bugs that are difficult to fix and debug. It also limits the system's evolution: implementing new features becomes exponentially harder because component responsibilities are distributed incorrectly.

In my case, intrusive code generation assigned incorrect addresses to instructions, causing the virtual machine either to enter an infinite loop or throw a runtime exception:

The code that generated some instructions before Visitor shows just how bad it was:

public override List<Instruction> ToInstructions(int start, string temp)
{
    var instructions = new List<Instruction>();
    (IValue left, IValue right) right = (null, null);
    if (_expression.Primary())
    {
        right.right = ((PrimaryExpression)_expression).ToValue();
    }
    else
    {
        instructions.AddRange(_expression.ToInstructions(start, temp));
        if (_expression is MemberExpression member && member.Any())
        {
            var i = start + instructions.Count;
            var dest = "_t" + i;
            var src = instructions.Any()
                ? instructions.OfType<Simple>().Last().Left
                : member.Id;
            var instruction = member.AccessChain.Tail switch
            {
                DotAccess dot => new Simple(dest, (new Name(src), new Constant(dot.Id, dot.Id)), ".", i),
                IndexAccess index => new Simple(dest, (new Name(src), index.Expression.ToValue()), "[]", i),
                _ => throw new NotImplementedException()
            };
            instructions.Add(instruction);
        }
        right.right = new Name(instructions.OfType<Simple>().Last().Left);
    }
    var number = instructions.Any() ? instructions.Last().Number + 1 : start;
    instructions.Add(new Simple(
        temp + number, right, _operator, number
    ));
    return instructions;
}

The next snippet shows how much better it became after applying the pattern. The code reads almost like plain English:

public AddressedInstructions Visit(UnaryExpression visitable)
{
    if (visitable.Expression is PrimaryExpression primary)
        return [new Simple(visitable.Operator, _valueDtoConverter.Convert(primary.ToValueDto()))];
    var result = visitable.Expression.Accept(This);
    var last = new Name(result.OfType<Simple>().Last().Left!);
    result.Add(new Simple(visitable.Operator, last));
    return result;
}

What is the magic behind the new architecture, and why does it work? Let us return to the beginning and refresh our memory.

Classic Visitor and Double Dispatch

Pictures make the idea easier to illustrate because we can place visitable elements opposite their visitors. Suppose we have an element hierarchy that needs to be processed. Each member of the hierarchy gets a virtual processing method. That method accepts a processor with one overloaded method for every element type:

The pattern's key properties are:

It solves the intrusive-approach problem by separating operations from data through the Visitor class.
It uses double dispatch: subtype polymorphism plus method overloading, or ad-hoc polymorphism. First, the correct override is chosen on the abstract element; then the concrete implementation selects the concrete overload.
Perhaps less obviously, a visitor can return values. Nothing prevents you from replacing void with string, for example.

Drawbacks of the Classic Visitor Pattern

We immediately introduce a cyclic dependency: Visitor knows everything about the Element subtype hierarchy.

As a result, we constantly need access to the source of both hierarchies: any change to the element hierarchy forces changes to the visitor hierarchy. Why do I say visitor hierarchy when the diagram shows one Visitor class?

abstract class Element
{
    abstract void Accept(IVisitor visitor);
}

interface IVisitor
{
    void Visit(ElementA elementA);

    void Visit(ElementB elementB);
}

class VisitorOne : IVisitor
{
    public void Visit(ElementA elementA)
    {
    }

    public void Visit(ElementB elementB)
    {
    }
}

class VisitorTwo : IVisitor
{
    public void Visit(ElementA elementA)
    {
    }

    public void Visit(ElementB elementB)
    {
    }
}

The Acyclic Visitor Pattern

The acyclic version removes the cyclic dependency of the classic implementation. It introduces two visitor abstractions that form an architectural boundary between contract and implementation. One is used on the receiving side; the other assembles a custom visitor. This declarative approach uses the type system to describe exactly which elements a visitor can handle—like assembling a visitor from LEGO bricks.

This is much better. The element hierarchy knows nothing about processor implementations, while concrete processors select only the elements they need. But we have introduced another problem.

public class ElementA : Element
{
    public override void Accept(IVisitor visitor)
    {
        if (visitor is IVisitor<ElementA> typed)
            typed.Visit(this);
    }
}

We have lost compile-time type safety and moved type checking to runtime.

The Downcasting Problem in Acyclic Visitor

When we ignore subtype polymorphism, we lose its main benefit: not having to think about an object's concrete type. Explicit casts often signal poor architecture—either insufficiently object-oriented or internally contradictory. They also provide an opening for elusive bugs that appear only when the application runs.

When should you consider downcasting?

You know the object's concrete runtime type with 100% certainty (no).
That knowledge gives you access to capabilities unavailable at compile time (partly).
Casting is dramatically faster and easier than refactoring the code to remove the explicit cast (no).

There is another problem: systems like this are difficult to unit-test. Suppose cross-cutting behavior is added to an element's Accept method. In this configuration, the mock setup simply will not compile:

The element processor cannot be converted to IVisitor, while IVisitor itself is a marker interface with no members:

That leaves us in a painful position.

Why Type Checks Undermine the Visitor Pattern

Why does everything break as soon as we step beyond textbook examples and generalize the existing approach? Let us fix it. The requirements are:

Preserve all advantages of the acyclic version: flexibility, selectivity, declarative design, OCP and LSP compliance, and so on.
Keep all type checks at compile time and use static typing to its full advantage.

Surprisingly, C# generic variance helps us solve the problem.

Contravariance

Contravariance lets us substitute a more general type for a generic type parameter used in function arguments.

interface IFooIn<in TInputType>
{
    void Bar(TInputType input);
}

The standard library's IComparable is one example. Contravariance allows this:

IComparable<IEnumerable<char>> charEnumerableComparable = // ...;
// ...
IComparable<string> stringComparable = charEnumerableComparable;

Covariance

Covariance lets us substitute a more derived type for a generic type parameter used in function return values.

interface IFooOut<out TOutputType>
{
    TOutputType Baz();
}

The standard library's IEnumerable is one example. Covariance allows this:

IEnumerable<Task<object>> tasksWithResults = // ...;
// ...
IEnumerable<Task> tasks = tasksWithResults;

Why Is This Useful?

First, covariance and contravariance can be combined within one type:

interface IFooInOut<in TInputType, out TOutputType>
{
    TOutputType Foo(TInputType input);
}

Second, variance conversions like the standard-library examples are fast: they generate no additional IL instructions.

What kinds of type conversion do we have?

Direct: both expressions have the same type.
Implicit: one expression's type is equivalent to the other's.
Explicit: the (Type) cast operator; IL contains a castclass instruction.
Safe (as): a failed conversion returns null instead of throwing; IL contains an isinst instruction.
Dynamic: the dynamic keyword defers type determination until runtime, moving resolution to the IL/runtime layer.

I wondered how each scenario performed, so I wrote a benchmark. The code is below.

Benchmark code

using System.Diagnostics.CodeAnalysis;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
BenchmarkRunner.Run<CastingBenchmarks>();

[SuppressMessage("ReSharper", "ReturnValueOfPureMethodIsNotUsed")]
[SuppressMessage("Performance", "CA1822:Пометьте члены как статические")]
#pragma warning disable CA1050
public class CastingBenchmarks
#pragma warning restore CA1050
{
    private static readonly ICovariant<Task<object>> SpecificCovariant = new Covariant<Task<object>>();
    private static readonly ICovariant<Task> GeneralCovariant = SpecificCovariant;
    private static readonly IContravariant<IEnumerable<char>> GeneralContravariant = new Contravariant<IEnumerable<char>>();
    private static readonly IContravariant<string> SpecificContravariant = GeneralContravariant;

    [Benchmark(Baseline = true)]
    public void Direct()
    {
        SpecificCovariantMethod(SpecificCovariant);
        GeneralContravariantMethod(GeneralContravariant);
    }

    [Benchmark]
    public void Implicit()
    {
        GeneralCovariantMethod(SpecificCovariant);
        SpecificContravariantMethod(GeneralContravariant);
    }

    [Benchmark]
    public void Explicit()
    {
        SpecificCovariantMethod((ICovariant<Task<object>>)GeneralCovariant);
        GeneralContravariantMethod((IContravariant<IEnumerable<char>>)SpecificContravariant);
    }

    [Benchmark]
    public void As()
    {
        SpecificCovariantMethod((GeneralCovariant as ICovariant<Task<object>>)!);
        GeneralContravariantMethod((SpecificContravariant as IContravariant<IEnumerable<char>>)!);
    }

    [Benchmark]
    public void Dynamic()
    {
        SpecificCovariantMethod((dynamic)GeneralCovariant);
        GeneralContravariantMethod((dynamic)SpecificContravariant);
    }
    // ReSharper disable once UnusedTypeParameter
    private interface ICovariant<out T>;

    private class Covariant<T> : ICovariant<T>;

    private static void SpecificCovariantMethod(ICovariant<Task<object>> input) =>
        input.ToString();

    private static void GeneralCovariantMethod(ICovariant<Task> input) =>
        input.ToString();
    // ReSharper disable once UnusedTypeParameter
    private interface IContravariant<in T>;

    private class Contravariant<T> : IContravariant<T>;

    private static void SpecificContravariantMethod(IContravariant<string> input) =>
        input.ToString();

    private static void GeneralContravariantMethod(IContravariant<IEnumerable<char>> input) =>
        input.ToString();
}

My hypothesis was that Dynamic would be slowest, while Implicit and Direct would be slightly faster than Explicit and As. The results confirmed it:

BenchmarkDotNet v0.13.11, macOS Ventura 13.7.2 (22H313) [Darwin 22.6.0]
Apple M1 Pro, 1 CPU, 10 logical and 10 physical cores
.NET SDK 9.0.200
  [Host]   : .NET 9.0.2 (9.0.225.6610), Arm64 RyuJIT AdvSIMD
  ShortRun : .NET 9.0.2 (9.0.225.6610), Arm64 RyuJIT AdvSIMD

Job=ShortRun  IterationCount=3  LaunchCount=1  
WarmupCount=3

Method	Mean	Ratio
Direct	5.226 ns	1.00
Implicit	5.234 ns	1.00
Explicit	5.266 ns	1.01
As	5.261 ns	1.01
Dynamic	14.278 ns	2.73

A Type-Safe Visitor Pattern with Visitor.NET

Combining contravariance and covariance opened new possibilities for abstraction design. I went beyond the original acyclic Visitor idea and introduced an abstraction for visitable elements: IVisitable. The resulting contracts are:

public interface IVisitable<out TVisitable>
    where TVisitable : IVisitable<TVisitable>
{
    TReturn Accept<TReturn>(IVisitor<TVisitable, TReturn> visitor);
}

public interface IVisitor<in TVisitable, out TReturn>
    where TVisitable : IVisitable<TVisitable>
{
    TReturn Visit(TVisitable visitable);
}

First, an element can now accept only a processor capable of processing it. There is no more downcasting.

Second, contravariance lets us operate through public base contracts without knowing both concrete hierarchies.

The result is triple dispatch:

The appropriate Accept override is selected polymorphically in the element hierarchy.
A base visitor for the hierarchy root is passed into Accept. Contravariance lets it flow into the derived class's Accept overload, where it becomes a visitor for that concrete subtype.
The concrete Accept overload calls the appropriate Visit overload for the element type.

public abstract class Element : IVisitable<Element>
{
    public abstract TReturn Accept<TReturn>(
        IVisitor<Element, TReturn> visitor);
}

public class ElementA : Element, IVisitable<ElementA>
{
    public override TReturn Accept<TReturn>(
        IVisitor<Element, TReturn> visitor) =>
        Accept(visitor);

    public TReturn Accept<TReturn>(
        IVisitor<ElementA, TReturn> visitor) =>
        visitor.Visit(this);
}

I do not even need a visitor example to communicate the idea: the entire design rests on contracts and abstractions. From the visitor's perspective, nothing has changed; it remains acyclic.

public class ElementVisitor : VisitorNoReturnBase<Element>,
    IVisitor<ElementA>
{
    public VisitUnit Visit(ElementA visitable)
    {
        return default;
    }
}

Visitor.NET + Source Generators

You may have noticed a drawback: every element in the hierarchy must implement two Accept overloads with fairly hard-to-read generic signatures. Source Generators already solve this problem.

Now you only need to annotate derived types with [AutoVisitable], supplying the hierarchy root in angle brackets:

[AutoVisitable<Element>]
public partial class ElementA : Element;

[AutoVisitable<Element>]
public partial class ElementB : Element;

Can the root be omitted? No. That would make the generator much harder to implement because developers may introduce intermediate hierarchy levels that move shared behavior into abstract subclasses:

[AutoVisitable<Element>]
public partial class ElementA : ParticularElement;

public abstract class ParticularElement : Element;

What About Multimethods?

When I described the library on my Telegram channel, a subscriber asked an interesting question:

What is a multimethod? It is a mechanism that dynamically selects a function based on the types of the supplied values, extending subtype polymorphism.

C# has no such feature, although it can be emulated with dynamic. Suppose we have an abstraction over numbers. A multimethod could implement an abstract addition operation.

public interface INumber
{
    INumber Add(INumber number);
}

record MyInt(int Val) : INumber;

record MyRational(int Num, int Den) : INumber;

We need to select an overload at runtime, which could be done like this:

record MyInt(int Val) : INumber
{
    public INumber Add(INumber number) => Add((dynamic)number);

    private INumber Add(MyInt myInt) => new MyInt(Val + myInt.Val);

    private INumber Add(MyRational myRational) =>
        myRational with
        {
            Num = Val * myRational.Den + myRational.Num
        };
}

This approach does not satisfy our requirements and performs poorly because of dynamic type conversion, as the benchmark showed. I therefore do not consider it a viable option here.

Takeaways

Classic Visitor keeps dispatch type-safe but couples every visitor to the full element hierarchy.
Acyclic Visitor reduces that coupling but commonly pays for it with downcasts.
C# variance can preserve an acyclic design without runtime type conversion.
Source generation can absorb the repetitive Accept overloads without hiding the dispatch model.
The approach is most valuable for stable hierarchies with many independent operations; a simple virtual method is still the better tool when the behavior belongs to the element itself.

You can star the project on GitHub: github.com/stepami/visitor-net.

NuGet packages:

Contracts: www.nuget.org/packages/Visitor.NET
Generator: www.nuget.org/packages/Visitor.NET.AutoVisitableGen

Related C# Guides

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

C# DIY Compiler with DDD and Clean Architecture

StepOne — Tue, 15 Sep 2026 19:24:15 +0000

Compiler projects are often presented as pipelines of algorithms: lexing, parsing, analysis, and code generation. Once the project grows, however, the harder problem is deciding which concepts own which behavior and how to stop one phase from leaking into every other phase.

This article is a two-year case study from my pet project, the HydraScript language interpreter. It shows where Domain-Driven Design and Clean Architecture clarified the compiler's boundaries, where my first abstractions failed, and why separate .NET projects became enforceable architectural constraints rather than folder decoration.

The project source code is available on GitHub.

What Is HydraScript?

The GitHub repository describes it as:

TypeScript & Go inspired open-source public research project written in C#

That description reflects the project at the time of writing. To explain how it got there, we need to go back a little.

It was 2022, my fourth year as an undergraduate at Bauman Moscow State Technical University. I was finishing my degree in the IU-9 department, whose specialization is “Analysis, Generation, and Transformation of Program Code.” Building new programming languages is part of the curriculum. The department even has its own GitHub organization, and it is well worth exploring.

Graduation naturally required a thesis project. Compiler construction had fascinated me throughout my studies because it brings together so much fundamental computer-science theory in one practical field.

My assigned topic was an interpreter for a subset of JavaScript defined by ECMA-262. If you have ever looked at JavaScript and asked, “Why does it behave like that?!”, I recommend reading the standard.

The resulting program works as follows.

It receives a source-code fragment:

  function abs(x: number) {
      if (x < 0)
          return -x
      return x
  }

  print(abs(-10) as string)

The lexer turns the fragment into a token stream:

  Keyword (1, 1)-(1, 9): function
  Ident (1, 10)-(1, 13): abs
  LeftParen (1, 13)-(1, 14): (
  Ident (1, 14)-(1, 15): x
  Colon (1, 15)-(1, 16): :
  Ident (1, 17)-(1, 23): number
  RightParen (1, 23)-(1, 24): )
  LeftCurl (1, 25)-(1, 26): {
  Keyword (2, 5)-(2, 7): if
  LeftParen (2, 8)-(2, 9): (
  Ident (2, 9)-(2, 10): x
  Operator (2, 11)-(2, 12): <
  IntegerLiteral (2, 13)-(2, 14): 0
  RightParen (2, 14)-(2, 15): )
  Keyword (3, 9)-(3, 15): return
  Operator (3, 16)-(3, 17): -
  Ident (3, 17)-(3, 18): x
  Keyword (4, 5)-(4, 11): return
  Ident (4, 12)-(4, 13): x
  RightCurl (5, 1)-(5, 2): }
  Ident (7, 1)-(7, 6): print
  LeftParen (7, 6)-(7, 7): (
  Ident (7, 7)-(7, 10): abs
  LeftParen (7, 10)-(7, 11): (
  Operator (7, 11)-(7, 12): -
  IntegerLiteral (7, 12)-(7, 14): 10
  RightParen (7, 14)-(7, 15): )
  Keyword (7, 16)-(7, 18): as
  Ident (7, 19)-(7, 25): string
  RightParen (7, 25)-(7, 26): )
  EOP

The parser turns those tokens into an abstract syntax tree according to the grammar:

From there, the path depends on your goals and implementation. You can interpret the AST directly, or treat it as the first intermediate representation (IR), perform static analysis, and then generate code:

    Goto End_abs
  Start_abs:
    BeginFunction abs
    PopParameter x
    _t1648079328 = x < 0
    IfNot _t1648079328 Goto End_if_else_53517805
    _t1783762424 = -x
    Return _t1783762424
    Goto End_if_else_53517805
  Start_if_else_53517805:
    BeginCondition if_else_53517805
  End_if_else_53517805:
    EndCondition if_else_53517805
    Return x
  End_abs:
    EndFunction abs
    _t196877937 = -10
    PushParameter _t196877937
    _t3435491484 = Call abs
    _t4127716996 = _t3435491484 as string
    Print _t4127716996
    End

If code generation is present, you can optimize the instruction stream first or execute it immediately on an embedded virtual machine:

Now let’s return to the development history of the HydraScript interpreter.

How the Compiler's Goal Shaped Its Architecture

The first iteration was written as a graduation project.

Every developer under time pressure knows the two rules:

If it works, do not touch it.

My case was no exception.

Everything was rushed. Bugs piled on bugs, while workarounds and reinventions patched the gaps well enough to get the project over the line.

There was no architecture at first. The interpreter executed the AST directly, but that design could not support functions, so I rewrote it around a minimal code-generation pipeline.

My ambitions grew along the way: “I’ll build an open-source JavaScript killer, and everyone will switch to my language.” I added a type system, basic blocks, a CFG, and optimizations. Within certain limitations, it worked.

Then I defended the thesis and had time to tidy the project up. Balancing it with a full-time job was difficult, however, and reality made it clear that I was not going to defeat JavaScript. The project needed a new direction.

I still wanted to maintain and develop it, but over the long term. I needed to be able to leave it alone for months, return, and still understand what I had written.

Because the source was public, other developers should also be able to understand it without deep prior knowledge of compiler construction.

Clean code and comprehensibility meant giving up on peak performance or serious production use for this interpreted language. That was acceptable: its educational mission—public, approachable reverse engineering—was valuable in its own right.

Applying Domain-Driven Design to a Compiler

DDD was popular on my team at the time, and I fell down the rabbit hole: blue books, red books, Merson’s talk, and everything around them.

It looked like exactly what I needed. A ubiquitous language shared by the compiler domain and the code could make the project easier to understand.

As I modeled the interpreter’s domain, I divided it into three subdomains:

FrontEnd — entities related to syntax analysis.
IR — constructs for working with the intermediate representation, used here during static analysis.
BackEnd — entities produced during code generation and related to direct code execution.

That division has stood the test of time. It is semantically coherent and repeatedly pushed the architecture in the right direction.

At that point I knew little about architecture, and the project was a conventional two-layer application whose boundaries existed only as folders.

You can find that version in the before branch. I kept it as a reminder of what not to do.

This pet project taught me an important architectural lesson:

Architecture proves itself when you add new functionality. If its evolution follows the right trajectory, implementations of difficult features begin to suggest themselves. They are not repetitions of what already exists, but new pieces that still fit the overall design.

The early DDD decision established that trajectory for the months of development and refactoring that followed.

Applying Clean Architecture to the Compiler

Saying “this project uses DDD” sounds reassuring. What could go wrong? Practically everything.

Architectural Mistakes and Their Cost

The first critical mistake was an intrusive approach to the AST. Operations were placed inside the tree as virtual methods and overridden down the hierarchy. Virtual methods are not inherently bad, but they do not fit every operation.

When an operation requires external context, separating the operation from the data in a more functional style is worth considering. The entity cannot encapsulate information it does not own.

Trying to put everything inside the hierarchy had several consequences. The system became hard to extend, and the cost of new features grew exponentially. Static analysis developed difficult bugs and rejected valid programs, so I disabled it. Code generation assigned incorrect addresses to instructions, which sent the virtual machine into infinite loops or caused runtime exceptions.

The Visitor pattern helped enormously. It was designed for processing structures that broadly belong to the Composite family.

Here is the method that generated instructions for a unary expression before Visitor:

public override List<Instruction> ToInstructions(int start, string temp)
{
    var instructions = new List<Instruction>();
    (IValue left, IValue right) right = (null, null);
    if (_expression.Primary())
    {
        right.right = ((PrimaryExpression)_expression).ToValue();
    }
    else
    {
        instructions.AddRange(_expression.ToInstructions(start, temp));
        if (_expression is MemberExpression member && member.Any())
        {
            var i = start + instructions.Count;
            var dest = "_t" + i;
            var src = instructions.Any()
                ? instructions.OfType<Simple>().Last().Left
                : member.Id;
            var instruction = member.AccessChain.Tail switch
            {
                DotAccess dot => new Simple(dest, (new Name(src), new Constant(dot.Id, dot.Id)), ".", i),
                IndexAccess index => new Simple(dest, (new Name(src), index.Expression.ToValue()), "[]", i),
                _ => throw new NotImplementedException()
            };
            instructions.Add(instruction);
        }
        right.right = new Name(instructions.OfType<Simple>().Last().Left);
    }
    var number = instructions.Any() ? instructions.Last().Number + 1 : start;
    instructions.Add(new Simple(
        temp + number, right, _operator, number
    ));
    return instructions;
}

And here is the same operation after applying the pattern:

public AddressedInstructions Visit(UnaryExpression visitable)
{
    if (visitable.Expression is PrimaryExpression primary)
        return [new Simple(visitable.Operator, _valueDtoConverter.Convert(primary.ToValueDto()))];
    var result = visitable.Expression.Accept(This);
    var last = new Name(result.OfType<Simple>().Last().Left!);
    result.Add(new Simple(visitable.Operator, last));
    return result;
}

Honestly, I can no longer explain exactly how the first version works. The second is almost self-documenting; it reads like a sequence of English sentences.

Getting there required several unusual and interesting engineering solutions.

AddressedInstructions

Moving code generation to Visitor was the biggest challenge in separating operations from data. The old method accepted an int start parameter: an offset into the instruction list that allowed it to calculate integer addresses.

That addressing system eventually failed, and the parameter no longer had a natural place in the new design. A global counter would be unsafe. A functional visitor would be easier to read and debug because you could step through the call chain and locate the source of an invalid result.

I therefore rebuilt instruction addressing from scratch. The result was both useful and technically interesting: a data structure that recalculates addresses in O(1) when its elements change.

What does that mean?

Previously, every instruction in a list had a numeric address:

0: a = 0 1: x = 2 2: y = a 3: print x

Instructions 0 and 2 are dead code and can be removed, leaving:

1: x = 2 3: print x

The virtual machine now fails. It starts at zero, and its default rule for calculating the next address is current address plus one. It cannot traverse the remaining instructions until we recalculate the addresses:

0: x = 2 1: print x

The goal was to avoid walking an entire array—or more—just to shift indices. Any deletion, insertion, or move should immediately yield correct addresses.

That required an abstraction for the concept of an address and a data structure that satisfies the requirements.

Visitor.NET

Adopting Visitor also required choosing among several implementations. If you are unfamiliar with the alternatives, Dmitri Nesteruk’s talk referenced in the original article is a good starting point.

The acyclic variant interested me because it lets a class declare which elements it visits:

public class TypeSystemLoader : IVisitor,
    IVisitor<ScriptBody>,
    IVisitor<AbstractSyntaxTreeNode>,
    IVisitor<TypeDeclaration>
{
    // ...
}

But I strongly disliked the explicit type check and cast required by the visitable object:

public class ScriptBody : AbstractSyntaxTreeNode
{
    public override void Accept(IVisitor visitor)
    {
        if (visitor is IVisitor<ScriptBody> typed)
            typed.Visit(this);
    }
}

I rejected that design and returned to the classic pattern, but the compromise also failed.

First, I had assigned some entities to the wrong subdomains: AST nodes ended up in IR rather than FrontEnd. Second, the classic Visitor implementation introduced a circular dependency. Third, the subdomains were not isolated; FrontEnd knew about BackEnd because the pattern implementation required it.

Despite every intention to write clean code, I had produced a high-coupling, low-cohesion bowl of spaghetti.

I had to reinvent the pattern as a type-safe, acyclic implementation that followed SOLID and required no casts at all.

www.nuget.org/packages/Visitor.NET

The result was the Visitor.NET library, which I later presented at the Stachka developer conference in Saint Petersburg. I also wrote a separate article for readers who could not attend.

Contravariance produced the required behavior:

public interface IVisitor<in TVisitable, out TReturn>
    where TVisitable : IVisitable<TVisitable>
{
    TReturn Visit(TVisitable visitable);
}

public interface IVisitable<out TVisitable>
    where TVisitable : IVisitable<TVisitable>
{
    TReturn Accept<TReturn>(IVisitor<TVisitable, TReturn> visitor);
}

public record Operation(
    char Symbol,
    BinaryTreeNode Left,
    BinaryTreeNode Right) : BinaryTreeNode, IVisitable<Operation>
{
    public override TReturn Accept<TReturn>(
        IVisitor<BinaryTreeNode, TReturn> visitor) =>
        Accept(visitor);

    public TReturn Accept<TReturn>(
        IVisitor<Operation, TReturn> visitor) =>
        visitor.Visit(this);
}

I then polished away the implementation boilerplate with incremental source generators:

www.nuget.org/packages/Visitor.NET.AutoVisitableGen

[AutoVisitable<BinaryTreeNode>]
public partial record Operation(
    char Symbol,
    BinaryTreeNode Left,
    BinaryTreeNode Right) : BinaryTreeNode;

Advanced Static Analysis

As mentioned earlier, static analysis in the pre-refactoring project had to be disabled because the intrusive design produced strange and difficult bugs. The language also lacked forward references, largely because the parser tried to populate the symbol table while parsing.

I once again had to invent and reverse-engineer a solution: one that could check semantics properly and remain extensible and resilient to change.

This happened alongside my rethinking of Visitor. Once I realized that analysis required several passes over the tree, I also realized that I needed a small framework for building visitors as services.

The result was a multi-stage algorithm, with implementation details at every stage. At the time of writing, the passes were:

Scope initialization: Some nodes use the current scope; others introduce a nested scope—for example, functions, objects, and blocks.
Type-system loading: Built-in and user-defined types are loaded into symbol tables, after which references between them are resolved.
Name reservation: All other symbols are registered. This is a separate pass because an omitted type must be inferred, and inference needs access to reserved identifiers.
Main program validation: Expressions, function calls, assignments, and other constructs are analyzed.

With this deeper approach, HydraScript rejects during semantic analysis code that TypeScript allows to fail at runtime:

let x = f()
function f() {
    print(x as string)
    return 5
}

Enforcing Boundaries with Separate .NET Projects

Solving those problems—introducing DDD and Visitor, then designing services—made the next step clearer with every commit: a complete move to Clean Architecture.

The domain core—lexers, parsers, instructions, and so on—needed to become a set of strictly isolated components.

Static analysis and code generation are application-layer features implemented through visitors acting as services.

Dump logging, configuration, and other supporting concerns belong to infrastructure. The CLI handler is the host that wires everything together.

I repeatedly failed to police layer and dependency constraints manually, so I made the compiler enforce them instead of relying on ArchUnitNET tests.

Projects instead of folders are architectural static typing in its purest form.

If components in one folder must not depend on components in another, place them in separate projects and let the compiler report violations.

Some people argue that this creates too many small projects, or that “small applications do not need it, while large applications turn into a mess.”

That uses the wrong criterion. Project size does not determine whether the technique applies; domain clarity does. If separate projects reveal the domain structure and make the system easier to understand, use them.

Takeaways

DDD and Clean Architecture did not make the compiler correct by themselves. They became useful only where they exposed stable domain concepts, isolated change, or let the C# compiler enforce a dependency rule. These are the lessons I would carry into another long-lived .NET codebase:

Start from the domain when writing code. It improves clarity and readability, assigns responsibilities to the right components, and leads to a flexible architecture that can survive change.
Stop assuming you are merely reinventing the wheel. Instead of believing everything has already been built, ask: “What if it has not?”
Learn to play the long game. If you cannot solve a problem today, do not abandon it or hide it behind a workaround. Admit that you are missing something, then advance in small steps—both deeper and broader.
Do not fear change; accept it. Early decisions are not carved in stone. Some may prove unexpectedly wrong and expensive, and you must be ready to work with that reality.
Do not be afraid to build complex algorithms and systems. Not every problem has a two-line solution.
Account for the cost of a decision. The more code a solution requires, the more carefully you should consider its consequences.

If you want hands-on open-source contribution experience, browse the HydraScript repository issues. There is usually something useful to work on.

Related Compiler-Construction Articles

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

System.Text.Json Polymorphism with Swagger in .NET 7

StepOne — Tue, 15 Sep 2026 18:59:10 +0000

Polymorphic JSON is not finished when System.Text.Json can serialize a derived type. The same discriminator contract must survive OpenAPI generation, server validation, client generation, and every serializer call that crosses a service boundary.

This article follows that contract through a .NET 7 application and shows where the surrounding tooling originally broke down. It is a historical snapshot from March 2023: use it to understand the integration mechanics, then verify current framework and library behavior before carrying the workarounds into a newer stack.

Polymorphic JSON Before .NET 7

The platform has been steadily bringing more functionality in-house.

Many NuGet packages that used to be staples of C# development now have counterparts in .NET itself. These alternatives are built in and require no additional dependency. The libraries live in the dotnet/runtime repository: dotnet/runtime/src/libraries.

JSON serialization is the clearest example of the platform replacing a popular open-source solution.

For years, developers moving data from Kafka into databases often reached for Json.NET, also known as Newtonsoft.Json or simply Newtonsoft. The library had almost 2.5 billion downloads at the time of writing. Before ASP.NET Core 3.0, the platform even supported it directly through various adapters.

Microsoft eventually decided:

As part of the work to improve the ASP.NET Core shared framework, Newtonsoft.Json (Json.NET) has been removed from the ASP.NET Core shared framework.

The default JSON serializer for ASP.NET Core is now System.Text.Json, which is new in .NET Core 3.0. Consider using System.Text.Json when possible. It's high-performance and doesn't require an additional library dependency. However, since System.Text.Json is new, it might currently be missing features that your app needs. For more information, see How to migrate from Newtonsoft.Json to System.Text.Json.

By the time of this article, System.Text.Json covered the everyday needs of working with JSON data. It was also more efficient than its third-party counterpart in both execution time and memory use.

Polymorphic Serialization with System.Text.Json

Polymorphic serialization was one of the major features missing from the first releases. Some gaps required custom code; others called for the usual collection of workarounds.

The two libraries handle inheritance hierarchies differently. Consider this minimal hierarchy:

abstract record Base;

record Derived(string Property) : Base;

Their default behavior is dramatically different:

Base baseObj = new Derived("String Property");
Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(baseObj));
// {"Property":"String Property"}
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(baseObj));
// {}

The difference comes from how each serializer gathers information about the type it is processing. The source code makes this clear.

Newtonsoft builds contracts on the fly from runtime information alone. Give it a Type instance, and it takes care of the rest:

protected virtual JsonContract CreateContract(Type objectType)
{
    Type t = ReflectionUtils.EnsureNotByRefType(objectType);
    if (IsJsonPrimitiveType(t))
        return CreatePrimitiveContract(objectType);
    t = ReflectionUtils.EnsureNotNullableType(t);
    JsonContainerAttribute? containerAttribute = JsonTypeReflector.GetCachedAttribute<JsonContainerAttribute>(t);
    if (containerAttribute is JsonObjectAttribute)
        return CreateObjectContract(objectType);
    if (containerAttribute is JsonArrayAttribute)
        return CreateArrayContract(objectType);
    if (containerAttribute is JsonDictionaryAttribute)
        return CreateDictionaryContract(objectType);
    if (t == typeof(JToken) || t.IsSubclassOf(typeof(JToken)))
        return CreateLinqContract(objectType);
    if (CollectionUtils.IsDictionaryType(t))
        return CreateDictionaryContract(objectType);
    if (typeof(IEnumerable).IsAssignableFrom(t))
        return CreateArrayContract(objectType);
    if (CanConvertToString(t))
        return CreateStringContract(objectType);
    return CreateObjectContract(objectType);
}

Take a look at CreateObjectContract when you have time. It is a particularly revealing example of reflection under the hood.

System.Text.Json takes a more involved route. It searches every converter available to it:

Custom converters
Converters specified by JsonConverterAttribute
Built-in converters
Converter factories

There are plenty of them; just browse this directory. Only after exhausting those options does it try to create a converter:

internal static JsonConverter GetConverterForType(
    Type typeToConvert,
    JsonSerializerOptions options,
    bool resolveJsonConverterAttribute = true)
{
    RootDefaultInstance(); // Ensure default converters are rooted.

    // Priority 1: Attempt to get custom converter from the Converters list.
    JsonConverter? converter = options.GetConverterFromList(typeToConvert);
    // Priority 2: Attempt to get converter from [JsonConverter] on the type being converted.
    if (resolveJsonConverterAttribute && converter == null)
    {
        JsonConverterAttribute? converterAttribute =
            typeToConvert.GetUniqueCustomAttribute<JsonConverterAttribute>(inherit: false);
        if (converterAttribute != null)
        {
            converter = GetConverterFromAttribute(
                converterAttribute,
                typeToConvert: typeToConvert,
                memberInfo: null,
                options);
        }
    }
    // Priority 3: Query the built-in converters.
    converter ??= GetBuiltInConverter(typeToConvert);
    // Expand if factory converter & validate.
    converter = options.ExpandConverterFactory(converter, typeToConvert);
    if (!converter.TypeToConvert.IsInSubtypeRelationshipWith(typeToConvert))
    {
        ThrowHelper.ThrowInvalidOperationException_SerializationConverterNotCompatible(
            converter.GetType(),
            converter.TypeToConvert);
    }
    JsonSerializerOptions.CheckConverterNullabilityIsSameAsPropertyType(converter, typeToConvert);
    return converter;
}

Why converters? Because they provide the type information used during serialization—but only when the type passed to the serializer matches the converter’s type:

if (converter.TypeToConvert == type)
{
    // For performance, avoid doing a reflection-based instantiation
    // if the converter type matches that of the declared type.
    jsonTypeInfo = converter.CreateCustomJsonTypeInfo(options);
}
else
{
    Type jsonTypeInfoType = typeof(CustomJsonTypeInfo<>).MakeGenericType(type);
    jsonTypeInfo = (JsonTypeInfo)jsonTypeInfoType.CreateInstanceNoWrapExceptions(
        parameterTypes: new Type[] { typeof(JsonConverter), typeof(JsonSerializerOptions) },
        parameters: new object[] { converter, options })!;
}

The distinction is visible in the public APIs as well:

public static string Newtonsoft.Json.JsonConvert.SerializeObject(object? value);

public static string System.Text.Json.JsonSerializer.Serialize<TValue>(TValue value, JsonSerializerOptions? options = null);

Before .NET 7, you could make System.Text.Json behave like Newtonsoft in the example above by calling Serialize with object as the generic type argument—an approach the Microsoft documentation itself recommended:

System.Text.Json.JsonSerializer.Serialize<object>(baseObj);

That explicitly tells the serializer to use reflection-based instantiation. With .NET 7, this trick is no longer necessary, thanks to...

JsonDerivedTypeAttribute

The short version is that we can update the previous example to use the library’s new API:

[JsonDerivedType(typeof(Derived), typeDiscriminator: nameof(Derived))]
abstract record Base;

record Derived(string Property) : Base;

Base baseObj = new Derived("String Property");
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(baseObj));
// {"$type":"Derived","Property":"String Property"}

For the long version, see the official Microsoft documentation. It explains the new attribute clearly and includes plenty of detailed examples.

The key point is that the resulting JSON now contains a discriminator field that identifies the object’s type. Polymorphic deserialization into a base-class instance therefore requires that field to be present.

There are also three details worth calling out:

The discriminator must appear at the start of the JSON object:

The type discriminator must be placed at the start of the JSON object, grouped together with other metadata properties like $id and $ref.

Use one discriminator type consistently:

While the API supports mixing and matching type discriminator configurations, it's not recommended. The general recommendation is to use either all string type discriminators, all int type discriminators, or no discriminators at all.

Polymorphic serialization works only when the serializer receives the root type of the hierarchy:

For polymorphic serialization to work, the type of the serialized value should be that of the polymorphic base type. This includes using the base type as the generic type parameter when serializing root-level values, as the declared type of serialized properties, or as the collection element in serialized collections.

So far, so good. But...

Why Swagger Must Understand the Type Discriminator

Imagine an application whose services communicate with one another. Some service contracts contain variants: depending on the payload, a message may represent one object, another object, or a third.

One way to model this is with composition. Each field represents one possible variant, but only one field is populated at a time.

Suppose a service accepts a message describing an animal. The animal may be a dog or a cat. A dog looks like this:

{
    "dog": {
        "bark": true
    },
    "cat": null
}

And a cat looks like this:

{
    "dog": null,
    "cat": {
        "meow": true
    }
}

Now add a horse, cow, pig, and many more:

{
    "dog": ...,
    "cat": ...,
    "horse": ...,
    "cow": ...,
    "pig": ...
}

Every new field makes the object larger and adds proportional infrastructure code. This design is clearly not flexible.

For messages used only in internal data exchange, polymorphic contracts look appropriate. Inheritance and polymorphism are supported by OpenAPI 3, and the specification provides a dedicated Discriminator Object for identifying types.

Defining Polymorphic Contracts in .NET 7

Let’s define our animal hierarchy:

[JsonDerivedType(typeof(Cat), typeDiscriminator: nameof(Cat))]
[JsonDerivedType(typeof(Dog), typeDiscriminator: nameof(Dog))]
public abstract record Animal;

public record Cat : Animal
{
    public bool Meow { get; set; } = true;
}

public record Dog : Animal
{
    public bool Bark { get; set; } = true;
}

Then we add a simple controller with two endpoints: one returns data, and the other accepts it.

[ApiController]
[Route("[controller]")]
public class AnimalsController : Controller
{
    [HttpGet]
    public IEnumerable<Animal> GetAnimals() =>
        new List<Animal> { new Dog(), new Cat() };

    [HttpPost]
    public void PostAnimal([FromBody] Animal animal, [FromServices] ILogger<AnimalsController> logger) =>
        logger.LogInformation("{Animal}", animal.ToString());
}

Everything works. GET returns:

[
    {
        "$type": "Cat",
        "meow": true
    },
    {
        "$type": "Dog",
        "bark": true
    }
]

Sending a cat with POST:

{
    "$type": "Cat",
    "meow": true
}

Produces this log output:

info: PolymorphicContracts.AnimalsController[0]
      Cat { Meow = True }

End of article? Not quite. Let’s inspect the generated Swagger UI:

Disappointment awaits...

This documentation is not enough for anyone to understand how to call the API. Maybe the UI generator is at fault. Let’s inspect schemas:

{
    "schemas": {
        "Animal": {
            "type": "object",
            "additionalProperties": false
        }
    }
}

The generated schema does not match reality. Swagger failed to recognize the inheritance and polymorphism in the documented contracts. Let’s configure it:

builder.Services.ConfigureSwaggerGen(opt => opt.UseOneOfForPolymorphism());

The regenerated schemas look like this:

{
    "schemas": {
        "Animal": {
            "type": "object",
            "additionalProperties": false
        },
        "Cat": {
            "type": "object",
            "allOf": [
                {
                    "$ref": "#/components/schemas/Animal"
                }
            ],
            "properties": {
                "meow": {
                    "type": "boolean"
                }
            },
            "additionalProperties": false
        },
        "Dog": {
            "type": "object",
            "allOf": [
                {
                    "$ref": "#/components/schemas/Animal"
                }
            ],
            "properties": {
                "bark": {
                    "type": "boolean"
                }
            },
            "additionalProperties": false
        }
    }
}

Better: the derived types are present. But every schema is missing the $type discriminator, which should be marked as required. Swagger does not see it because the serializer adds it later to the JSON string; it is not a member of the .NET type. Yet the documentation says this should not happen:

If UseAllOfForInheritance or UseOneOfForPolymorphism is enabled, and your serializer supports (and has enabled) emitting/accepting a discriminator property, then Swashbuckle will automatically generate the corresponding discriminator metadata on base schema definitions.

Let’s select the discriminator metadata manually:

builder.Services.ConfigureSwaggerGen(opt =>
{
    opt.UseOneOfForPolymorphism();
    opt.SelectDiscriminatorNameUsing(_ => "$type");
    opt.SelectDiscriminatorValueUsing(subType => subType.BaseType!
        .GetCustomAttributes<JsonDerivedTypeAttribute>()
        .FirstOrDefault(x => x.DerivedType == subType)?
        .TypeDiscriminator!.ToString());
});

The schemas now include the required $type property and the mapping:

{
    "schemas": {
        "Animal": {
            "required": [
                "$type"
            ],
            "type": "object",
            "properties": {
                "$type": {
                    "type": "string"
                }
            },
            "additionalProperties": false,
            "discriminator": {
                "propertyName": "$type",
                "mapping": {
                    "Cat": "#/components/schemas/Cat",
                    "Dog": "#/components/schemas/Dog"
                }
            }
        },
        "Cat": {
            "type": "object",
            "allOf": [
                {
                    "$ref": "#/components/schemas/Animal"
                }
            ],
            "properties": {
                "meow": {
                    "type": "boolean"
                }
            },
            "additionalProperties": false
        },
        "Dog": {
            "type": "object",
            "allOf": [
                {
                    "$ref": "#/components/schemas/Animal"
                }
            ],
            "properties": {
                "bark": {
                    "type": "boolean"
                }
            },
            "additionalProperties": false
        }
    }
}

Another step forward, but still not the result we want. First, the library contract forces discriminator values to strings even though they may be numbers. Second, it does not expose the allowed values—not even as an enum—or the corresponding default for each derived type. The library cannot help us any further, so it is time to build our own workaround.

Generating Polymorphic Swagger Schemas

The idea is to scan the application for hierarchies that use polymorphic JSON serialization, then pass the collected information to a custom ISchemaFilter implementation that enriches the generated schemas.

The algorithm is straightforward:

Obtain the list of assemblies that contain contracts—for example, configure it in appsettings.json and bind it through IOptions<>.
Scan those assemblies for types decorated with [JsonDerivedType]. These are the hierarchy roots. Because the attribute explicitly lists derived types and discriminators, no additional discovery is necessary; store the information for later.
Use the collected hierarchy data to enrich the documentation in a new ISchemaFilter.
Generate the enriched schema.

To make this approach practical, the hierarchies must follow a few rules:

Use discriminators consistently: either all strings or all numbers.
The hierarchy root must not be an interface; use an abstract class or abstract record.
Derive directly from the base class. In other words, keep the hierarchy one level deep.

Here is a hierarchy that violates every rule:

[JsonDerivedType(typeof(DerivedFirst), typeDiscriminator: 1)]
[JsonDerivedType(typeof(DerivedSecond), typeDiscriminator: "2")]
interface IBase
{
}

record DerivedFirst : IBase;

record DerivedSecond : DerivedFirst;

After spending some time on the implementation, I got the desired schema: the base discriminator has an enum, and every derived schema has its own required discriminator with a default value.

{
    "schemas": {
        "Animal": {
            "required": [
                "$type"
            ],
            "type": "object",
            "properties": {
                "$type": {
                    "enum": [
                        "Cat",
                        "Dog"
                    ],
                    "type": "string"
                }
            },
            "additionalProperties": false,
            "discriminator": {
                "propertyName": "$type",
                "mapping": {
                    "Cat": "#components/schemas/Cat",
                    "Dog": "#components/schemas/Dog"
                }
            }
        },
        "Cat": {
            "required": [
                "$type"
            ],
            "type": "object",
            "allOf": [
                {
                    "$ref": "#/components/schemas/Animal"
                }
            ],
            "properties": {
                "meow": {
                    "type": "boolean"
                },
                "$type": {
                    "type": "string",
                    "default": "Cat"
                }
            },
            "additionalProperties": false
        },
        "Dog": {
            "required": [
                "$type"
            ],
            "type": "object",
            "allOf": [
                {
                    "$ref": "#/components/schemas/Animal"
                }
            ],
            "properties": {
                "bark": {
                    "type": "boolean"
                },
                "$type": {
                    "type": "string",
                    "default": "Dog"
                }
            },
            "additionalProperties": false
        }
    }
}

Two more boundaries need the same contract: validation and generated clients.

Validating Polymorphic Request Models

FluentValidation provides abstract, polymorphic, and strongly typed APIs for routine validation code in .NET, even if the wiring is implicit in the [UsedImplicitly] sense.

It handles our scenario too. Continue writing validators for the concrete types, then register them like this—no wrapper required:

public class AnimalValidator : AbstractValidator<Animal>
{
    public AnimalValidator()
    {
        RuleFor(x => x)
            .SetInheritanceValidator(v => v
                .Add(new CatValidator())
                .Add(new DogValidator())
            );
    }
}

Polymorphic Contracts in Generated API Clients

Suppose you adopt polymorphic contracts in several services and now need to communicate with those services extensively. Nobody wants to hand-write every integration, so teams turn to generated or declarative clients.

Remember that polymorphic serialization requires passing the base type to the serializer:

JsonSerializer.Serialize<BaseType>(derivedTypeObj);

Libraries such as Refit, RestEase, and RestSharp often pass the wrong type—sometimes even object—when serializing a request such as POST. Service-side deserialization then fails and the client receives a 500 response:

System.NotSupportedException: Deserialization of types without a parameterless constructor, a singular parameterized constructor, or a parameterized constructor annotated with 'JsonConstructorAttribute' is not supported.

The override point differs by library. Refit, for example, provides IHttpContentSerializer. Implement the interface and supply the implementation when creating the client:

var refitSettings = new RefitSettings
{
    ContentSerializer = new PolymorphicSerializer(
        new SystemTextJsonContentSerializer(),
        SystemTextJsonContentSerializer.GetDefaultJsonSerializerOptions()
    )
};

internal class PolymorphicSerializer : IHttpContentSerializer
{
    private readonly IHttpContentSerializer _defaultSerializer;
    private readonly JsonSerializerOptions _serializerOptions;

    public PolymorphicSerializer(
        IHttpContentSerializer defaultSerializer,
        JsonSerializerOptions serializerOptions) =>
        (_defaultSerializer, _serializerOptions) =
        (defaultSerializer, serializerOptions);

    public HttpContent ToHttpContent<T>(T item) =>
        JsonContent.Create(item, item!.GetType().BaseType!, options: _serializerOptions);

    public Task<T?> FromHttpContentAsync<T>(HttpContent content, CancellationToken cancellationToken = default) =>
        _defaultSerializer.FromHttpContentAsync<T?>(content, cancellationToken);

    public string? GetFieldNameForProperty(PropertyInfo propertyInfo) =>
        _defaultSerializer.GetFieldNameForProperty(propertyInfo);
}

Takeaways

In the .NET 7 ecosystem described here, polymorphic serialization worked before the complete interservice toolchain did. A production contract therefore needed explicit checks at each boundary:

Serialize and deserialize through the declared base type.
Verify that OpenAPI contains the discriminator and every derived schema.
Exercise generated or declarative clients against the real server contract.
Register validation for each concrete type.
Keep the discriminator stable once external consumers depend on it.

I built a NuGet package while writing the article to solve the Swagger problem:

Package: www.nuget.org/packages/PolymorphicContracts.TypeDiscriminatorSwaggerSetup
Repository: github.com/Stepami/swagger-discriminator-setup
Demo project behind this article: github.com/StefanioHabrArticles/polymorphic-contracts

Related .NET Guides

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases

Java vs. C#: Four Java Features C# Handles Differently

StepOne — Sat, 12 Sep 2026 20:55:08 +0000

Language comparisons are most useful when they expose different design choices, not when they try to declare a winner. Java has several features that make certain modeling and one-off implementation tasks concise; C# either solves those tasks differently or leaves more ceremony to the developer.

This article examines four of those differences: class-based enums, covariant returns, functional interfaces, and anonymous interface implementations. It was written in September 2022, so treat the language-support details as a snapshot of that date and follow the linked proposals for later changes.

1. Class-Based Enums

Unlike Java, enums in C# and C++ are named numeric constants. That is no secret. What are enums in Java? In essence, they are syntactic sugar over a class. Let us write one that represents the token types recognized by a lexical analyzer:

enum TokenType {
    IDENTIFIER,
    NUMBER,
    ASSIGN;
}

Because an enum is also a class, we can add a constructor, methods, fields, and even an interface implementation. Let us give each enum constant the ability to produce a regular expression:

interface ToPattern {
    Pattern getPattern();
}

enum TokenType implements ToPattern {
    IDENTIFIER("[a-zA-Z][a-zA-Z0-9]*"),
    NUMBER("[0-9]+"),
    ASSIGN("[=]");

    private final String pattern;

    private TokenType(String pattern) {
        this.pattern = pattern;
    }

    @Override
    public Pattern getPattern() {
        return Pattern.compile(pattern);
    }
}

How can we do something similar in C#? There are two options:

Attributes and extension methods with reflection—but they cannot implement interfaces:

[AttributeUsage(AttributeTargets.Field)]
internal class PatternAttribute : Attribute
{
    public string Pattern { get; }

    public PatternAttribute(string pattern) =>
        Pattern = pattern;
}

public enum TokenType
{
    [Pattern("[a-zA-Z][a-zA-Z0-9]*")]
    Identifier,

    [Pattern("[0-9]+")]
    Number,

    [Pattern("[=]")]
    Assign
}

public static class TokenTypeExtensions
{
    public static Regex GetRegex(this TokenType tokenType) =>
        new(typeof(TokenType)
            .GetField(tokenType.ToString())!
            .GetCustomAttribute<PatternAttribute>()!
            .Pattern);
}

Classes with public static constants:

interface IHasRegex
{
    Regex Regex { get; }
}

class TokenType : IHasRegex
{
    public static readonly TokenType Identifier =
        new("[a-zA-Z][a-zA-Z0-9]*");
    public static readonly TokenType Number =
        new("[0-9]+");
    public static readonly TokenType Assign =
        new("[=]");
    private readonly string _pattern;

    private TokenType(string pattern) =>
        _pattern = pattern;

    public Regex Regex => new(_pattern);
}

That raises a question:

Why do I need C# enums if I can implement them the way Java does internally?

The question is especially relevant given the new capabilities added to the switch keyword in recent language versions.

2. Full Support for Covariant Return Types

Since C# 9, the language has supported covariant method return types. Previously, you might have written code like this:

abstract record Fruit;

record Apple : Fruit;

record Orange : Fruit;

abstract class FruitFactory<TFruit>
    where TFruit : Fruit
{
    public abstract TFruit Create();
}

class AppleFactory : FruitFactory<Apple>
{
    public override Apple Create() => new();
}

class OrangeFactory : FruitFactory<Orange>
{
    public override Orange Create() => new();
}

Now you can omit the extra constructs:

abstract class FruitFactory
{
    public abstract Fruit Create();
}

class AppleFactory : FruitFactory
{
    public override Apple Create() => new();
}

class OrangeFactory : FruitFactory
{
    public override Orange Create() => new();
}

Java has supported this for almost its entire history, and the feature applies more broadly. It also works when implementing and extending interfaces. Suppose I define a structure that can be copied along with its data. I need to indicate that it is copyable, which is what the Cloneable contract does. By default, clone returns Object. To avoid littering the code with casts, I can declare that clone returns the type being copied:

class Tree<T> implements Cloneable {
    private final Node<T> root;

    public Tree(Node<T> root) {
        this.root = root;
    }

    @Override
    public Tree<T> clone() throws CloneNotSupportedException {
        super.clone();
        return new Tree<>(root.clone());
    }
}

class Node<T> implements Iterable<Node<T>>, Cloneable {
    private final T data;
    private final List<Node<T>> children;

    public Node(T data) {
        this.data = data;
        children = new ArrayList<>();
    }

    private void push(Node<T> node) {
        children.add(node);
    }

    @Override
    public Iterator<Node<T>> iterator() {
        return new ArrayList<>(children).iterator();
    }

    @Override
    public Node<T> clone() throws CloneNotSupportedException {
        super.clone();
        var node = new Node<>(data);
        for (var child : this) {
            node.push(child.clone());
        }
        return node;
    }
}

You cannot do the same in C#. It produces an error:

Method 'Clone' cannot implement method from interface 'System.ICloneable'. Return type should be 'object'.

class Foo : ICloneable
{
    public Foo Clone()
    {
        throw new NotImplementedException();
    }
}

Why interfaces still lack covariant return types is an open question, even in the language specification discussion.

3. Functional Interfaces

Java has the concept of a functional interface. A functional interface is an interface with a single abstract method. Its key feature is that instances can be initialized with lambda expressions—since Java 8:

@FunctionalInterface
interface IntegerBinaryExpression {
    int evaluate(int a, int b);
}

// ...
IntegerBinaryExpression add = (a, b) -> a + b;
System.out.println(add.evaluate(3, 5)); // 8

It is not hard to see why this works if you inspect what the IDE suggests as a replacement for the value assigned to the IntegerBinaryExpression variable named add:

IntelliJ IDEA

Accepting the suggested replacement gives us:

IntegerBinaryExpression add = Integer::sum;

Together with the double-colon syntax (::), this points to one conclusion: functional interfaces are Java's mechanism for implementing callbacks. C# has delegates, so the need for similar syntactic sugar is debatable. It does look convenient, however, especially for interfaces instantiated only once in a project.

4. Anonymous Interface Implementations

Perhaps the previous example belongs in this section because it demonstrates a special case of another Java feature I find excellent: anonymous interface implementations.

Consider a contract with at least two methods:

interface Pair<F, S> {
    F first();
    S second();
}

If we start typing new Pair to create an instance of this interface, the IDE does not report that abstract types cannot be instantiated. Instead, it offers to implement the methods:

var myPair = new Pair<String, Integer>() {
    @Override
    public String first() {
        return "first";
    }

    @Override
    public Integer second() {
        return 2;
    }
};

You can do the same with classes, whether abstract or not:

class Book {
    public void read() {
        // ...
    }
}

// ...
var myBook = new Book() {
    @Override
    public void read() {
        super.read();
    }
};

This feature opens up new options when you want to avoid bloating the project structure and create contract implementations on the fly, or when you need to encapsulate a specific contract usage scenario. I would welcome it in C#; the CLR has everything it needs to support it. There is even a feature request in the Roslyn repository.

What C# Developers Can Learn from Java

None of these features should be copied into C# merely because Java has them. Delegates already cover much of the functional-interface use case, while richer enums and anonymous implementations would trade convenience for new language and tooling complexity.

The useful question for a C# codebase is narrower: when the language lacks a construct, does the local workaround remain explicit, navigable, and easy to debug? If it does not, understanding how another language models the same problem can lead to a better API even when C# never adopts the syntax.

Related C# Language Guides

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

C# Generic Math: A Convex Hull with Static Interfaces

StepOne — Sat, 12 Sep 2026 20:43:48 +0000

Static abstract interface members let a C# algorithm depend on operations instead of concrete numeric types. A convex-hull implementation is a good stress test: its coordinate type must support comparison, addition, negation, and multiplication, but the algorithm should not care whether those operations come from int, double, or a domain-specific number.

This article connects algebraic rings to the Graham scan convex-hull algorithm and shows how C# 11 expresses the required capabilities through Generic Math contracts.

Algebraic Rings and C# Generic Math

My previous articles on this topic came out almost a year ago. They included some experiments in designing algebraic structures, but I will not reuse those designs here because a lot has changed since then.

In particular, C# 11 introduced a rather interesting language feature: static abstract interface members. You can read more about static abstract members in interfaces here.

As a reminder, a ring is a structure that forms an Abelian group under addition and a monoid under multiplication. Multiplication must also be distributive over addition.

Previously, the algebraic structure itself had to be modeled as a separate type. Now we can instead say that the structure can be defined over the type itself. I will demonstrate this with a ring, leaving its relationship to other structures aside.

Before:

public interface IRing<T>
{
    T Plus(T left, T right);

    T Zero { get; }

    T Inverse(T item);

    T Times(T left, T right);

    T One { get; }
}

After:

public interface IRing<T>
    where T : IRing<T>
{
    static abstract T operator +(T x, T y);

    static abstract T Zero { get; }

    static abstract T operator -(T x);

    static abstract T operator *(T x, T y);

    static abstract T One { get; }
}

The abstraction over the operations is now part of the type definition instead of living in a separate data structure. The next question is how to use these constructs.

If you are creating a custom data type, nothing stops you from implementing IRing<T> and calling it a day. That trick does not work with system types such as int and double, however.

The .NET team anticipated this problem so thoroughly that the standard library now contains contracts describing the very same algebraic structures I am writing about for the third time.

To see this for ourselves, let us look inside the source code for int.

The Int32 struct now implements many new interfaces. Among them is the generic ISignedNumber<T> interface, which extends INumberBase<T>. This contract describes the abstraction of a number and assembles the properties we already know through interfaces such as IAdditionOperators<T, T, T>, IAdditiveIdentity<T, T>, IMultiplicativeIdentity<T, T>, and others.

Each of these types represents one atomic abstract property belonging to some algebraic structure. You can find all of them in the System.Numerics namespace.

For compatibility with the C# standard library, we can therefore describe a ring as follows:

public interface IRing<T> :
    IAdditionOperators<T, T, T>,
    IAdditiveIdentity<T, T>,
    IUnaryNegationOperators<T, T>,
    IMultiplyOperators<T, T, T>,
    IMultiplicativeIdentity<T, T>
    where T :
    IAdditionOperators<T, T, T>,
    IAdditiveIdentity<T, T>,
    IUnaryNegationOperators<T, T>,
    IMultiplyOperators<T, T, T>,
    IMultiplicativeIdentity<T, T>
{
}

This lets us create custom data types that support ring operations while also using system types that already provide those operations. There is one catch, though: when designing consumers of those types, we cannot use our interface as a generic constraint.

That is because C# has no intersection types.

Implementing IRing<T> implies implementing a collection of other interfaces, but implementing each of those interfaces separately is not considered equivalent. This subject has even been discussed in a proposal thread in the dotnet/csharplang repository.

For example, let us rewrite the endomorphism ring from one of the previous articles. The new implementation represents an endomorphism itself as a wrapper around Func<T, T>. For the reason described above, however, the constraint that these mappings can exist only over Abelian groups is not especially concise.

public class Endomorphism<TGroup> : IRing<Endomorphism<TGroup>>
    where TGroup :
    IAdditionOperators<TGroup, TGroup, TGroup>,
    IAdditiveIdentity<TGroup, TGroup>,
    IUnaryNegationOperators<TGroup, TGroup>
{
    private readonly Func<TGroup, TGroup> _func;

    private Endomorphism(Func<TGroup, TGroup> func) =>
        _func = func;

    public TGroup At(TGroup x) =>
        _func(x);

    public static implicit operator Endomorphism<TGroup>(Func<TGroup, TGroup> func) =>
        new(func);

    public static Endomorphism<TGroup> operator +(Endomorphism<TGroup> left, Endomorphism<TGroup> right) =>
        (Func<TGroup, TGroup>)(x => left.At(x) + right.At(x));

    public static Endomorphism<TGroup> AdditiveIdentity =>
        (Func<TGroup, TGroup>)(_ => TGroup.AdditiveIdentity);

    public static Endomorphism<TGroup> operator -(Endomorphism<TGroup> value) =>
        (Func<TGroup, TGroup>)(x => -value.At(x));

    public static Endomorphism<TGroup> operator *(Endomorphism<TGroup> left, Endomorphism<TGroup> right) =>
        (Func<TGroup, TGroup>)(x => left.At(right.At(x)));

    public static Endomorphism<TGroup> MultiplicativeIdentity =>
        (Func<TGroup, TGroup>)(x => x);
}

Implementing Graham Scan with Generic Math

Continuing with the idea of generalizing algorithms through algebraic structures—rings in particular—I want to focus on constructing a convex hull. Wikipedia offers a good explanation, including the familiar board, nails, and rubber-band analogy.

The black outline is the board and the points are nails. The blue line is the rubber band—our convex hull.

There are many algorithms for constructing a convex hull. We will look at one of the most popular, Graham scan, because it is relatively efficient while remaining straightforward to implement.

The implementation needs to determine the turn formed by three points and sort points on a plane by increasing polar angle. Put it all together, and we get something like this:

public record Point2D(int X, int Y)
{
    public static Point2D operator -(Point2D p1, Point2D p2) =>
        new(p1.X - p2.X, p1.Y - p2.Y);

    public static int operator *(Point2D p1, Point2D p2) =>
        p1.X * p2.X + p1.Y * p2.Y;

    public static int operator ^(Point2D p1, Point2D p2) =>
        p1.X * p2.Y - p1.Y * p2.X;
}

public enum Turn : byte
{
    ClockWise,
    Collinear,
    CounterClockWise
}

public class TurnCalculator : ITurnCalculator
{
    public Turn GetTurn(Point2D p1, Point2D p2, Point2D p3)
    {
        var crossProduct =
            (p2.X - p1.X) * (p3.Y - p1.Y) -
            (p2.Y - p1.Y) * (p3.X - p1.X);
        return crossProduct switch
        {
            < 0 => Turn.ClockWise,
            > 0 => Turn.CounterClockWise,
            _ => Turn.Collinear
        };
    }
}

public class GrahamScan : IConvexHullFinder
{
    private readonly ITurnCalculator _calculator;

    public GrahamScan(ITurnCalculator calculator) =>
        _calculator = calculator;

    public IEnumerable<Point2D>? GetConvexHull(IList<Point2D>? points)
    {
        if (points is null or { Count: < 3 })
            return null;
        var p0 = points.OrderBy(p => p.X).ThenBy(p => p.Y).First();
        points = points.OrderBy(p => p, new PolarOrderComparer(p0)).ToList();
        var hull = new Stack<Point2D>();
        hull.Push(points[0]);
        hull.Push(points[1]);
        hull.Push(points[2]);
        for (var i = 3; i < points.Count; i++)
        {
            while (_calculator.GetTurn(hull.NextToTop(), hull.Peek(), points[i]) != Turn.CounterClockWise)
                hull.Pop();
            hull.Push(points[i]);
        }
        return hull;
    }
}

The implementation begins by finding the leftmost and lowest point in the set. It then sorts the remaining points by increasing polar angle, measured between the X-axis and a vector originating at the lowest point. This sorting step guarantees that the algorithm visits each point counterclockwise.

Next, it initializes a stack with the first three points to hold the hull. The algorithm walks through the remaining points counterclockwise, adding each to the hull and removing any points that violate the polygon's convexity.

At the heart of the algorithm is the while loop. It keeps removing points from the hull until the current point makes a counterclockwise turn with the last two points already in the hull.

For example, given the following set of points:

IConvexHullFinder.Instance.GetConvexHull(new List<Point2D>
    {
        new(0, 3),
        new(1, 1),
        new(2, 2),
        new(4, 4),
        new(0, 0),
        new(1, 2),
        new(3, 1),
        new(3, 3)
    })?.ToList().ForEach(Console.WriteLine);

We get the hull formed by the points below:

Point2D { X = 0, Y = 3 }
Point2D { X = 4, Y = 4 }
Point2D { X = 3, Y = 1 }
Point2D { X = 0, Y = 0 }

A graphical representation of the result

Look closely at the implementation and you will notice that we can define a ring over the point coordinates. The cross product used to determine the turn direction indeed relies on every property of this algebraic structure. We also need to require the coordinate type to implement IComparable<T>. The modified point class looks like this:

public record Point2D<TRing>(TRing X, TRing Y)
    where TRing :
    IComparable<TRing>,
    IAdditionOperators<TRing, TRing, TRing>,
    IAdditiveIdentity<TRing, TRing>,
    IUnaryNegationOperators<TRing, TRing>,
    IMultiplyOperators<TRing, TRing, TRing>,
    IMultiplicativeIdentity<TRing, TRing>
{
    public static Point2D<TRing> operator -(Point2D<TRing> p1, Point2D<TRing> p2) =>
        new(p1.X + -p2.X, p1.Y + -p2.Y);

    public static TRing operator *(Point2D<TRing> p1, Point2D<TRing> p2) =>
        p1.X * p2.X + p1.Y * p2.Y;

    public static TRing operator ^(Point2D<TRing> p1, Point2D<TRing> p2) =>
        p1.X * p2.Y + -(p1.Y * p2.X);
}

The same generic constraints then need to be propagated to the corresponding methods, replacing 0 with TRing.AdditiveIdentity. Subtraction can likewise be replaced with a combination of addition and unary negation, or you can use the ISubtractionOperators<T, T, T> contract.

When Generic Math Improves an Algorithm

The convex-hull algorithm no longer depends on a specific coordinate type. Convex hulls also appear beyond computational geometry, including finance, machine learning, and text analysis.

For example, define an operation that tests whether a point lies inside the hull, and you already have a basic classifier.

The broader lesson is not that every algorithm needs a ring abstraction. Generic constraints are valuable when they state the minimum operations an algorithm genuinely requires and when multiple useful types can satisfy that contract. Otherwise, a concrete numeric type will be easier to read and maintain.

The source code used in this article is available on GitHub: github.com/StefanioHabrArticles/generalize-this-and-that.

Continue with StepOne C# Content

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

Generic Math in C#: The Complete Guide

StepOne — Fri, 11 Sep 2026 19:14:56 +0000

Generic Math is easy to dismiss as a feature for numerical libraries. Its more important contribution is static abstraction: generic code can require operators, identities, parsing, and other type-level behavior without reflection, dynamic, or a runtime object hierarchy.

This guide builds the feature from first principles, examines the contracts in System.Numerics, and applies the same mechanics to parsing, generated database models, DDD types, architectural boundaries, tensors, and SIMD. It also covers the limitations and alternative designs, because static abstract constraints are powerful enough to become expensive when used casually.

What C# Generic Math Changed

Let’s briefly return to the past.

On November 8, 2022, .NET 7 shipped the first production release of Generic Math.

Later, I ran a poll in my Telegram channel. The results were personally disappointing.

Most developers did not use Generic Math and did not understand what the feature was for.

My goal here is therefore to give you the most complete explanation I could assemble from Microsoft’s public materials.

There is plenty to cover.

Why Generic Arithmetic Was Difficult Before .NET 7

Back in 2020, Kirill Maurin pointed out a frustrating limitation of C#: you could not write even the simplest generic summation function. This code fails to compile:

public static T Sum<T>(this T[] array, T initial)
{
    var result = initial;
    for (var i = 0; i < array.Length; i++)
        result += array[i];
    return result;
}

The compiler reports CS0019: “Operator '+=' cannot be applied to operands of type 'T' and 'T'.” The reason is straightforward. T tells the compiler almost nothing, while an overloaded operator is a static member of a type.

Intuition suggests adding a constraint that says the type supports addition:

public static T Sum<T>(this T[] array, T initial)
    where T : +
{
    var result = initial;
    for (var i = 0; i < array.Length; i++)
        result += array[i];
    return result;
}

Now we get CS1031: “Type expected.” Constraints accept types, not arbitrary symbols, and C# had no way to express the presence of an operator.

Generic Math in C# and .NET

What did we eventually get? In short, an extension to both the language and the standard library.

The first working draft was presented to Microsoft’s Language Design Meeting on June 29, 2020. Miguel de Icaza and Aaron Bockover showed the result of a year’s work. The meeting notes are available on GitHub.

The draft later became a full proposal discussed by the C# community. Reception was generally positive, although commenters raised interesting objections: some feared C++-style complexity, while others could not see a production use case. The full discussion is in dotnet/csharplang issue 4436.

The language solved the problem by introducing static abstract interface members: static abstract. An interface can now define a contract for values that support addition, and a data type can implement it:

interface IAddable<T> where T : IAddable<T>
{
    static abstract T Zero { get; }

    static abstract T operator +(T t1, T t2);
}

struct Int32 : IAddable<Int32>
{
    static int operator +(int x, int y) => x + y;

    public static int Zero => 0;
}

We can finally write the sum. Its actual form is slightly different because .NET’s arithmetic abstractions live in System.Numerics:

public static T Sum<T>(this T[] array) where T :
    IAdditiveIdentity<T, T>,
    IAdditionOperators<T, T, T>
{
    var result = T.AdditiveIdentity;
    for (var i = 0; i < array.Length; i++)
        result += array[i];
    return result;
}

Two details are important. First, the generic constraint uses two contracts rather than one; we will return to the reason later. Second, both the feature and the framework interfaces make heavy use of the curiously recurring template pattern (CRTP).

.NET Numerics

This new part of the standard library contains abstractions for implementing numeric types. The interfaces are deliberately fine-grained, allowing you to assemble a custom derived abstraction from small building blocks.

The full architecture is captured in a huge UML diagram. It is too large to display well in an article, but the .svg is available in my Telegram channel.

The raster preview already hints at its size:

Open a built-in type such as int, or Int32, and follow its interfaces upward. You will find INumberBase, which describes an abstract number: an object on which abstract numeric operations can be performed. Surprisingly, the core operations themselves live in separate interfaces.

Core operations

IAdditionOperators.cs — addition

  public interface IAdditionOperators<TSelf, TOther, TResult>
      where TSelf : IAdditionOperators<TSelf, TOther, TResult>?
  {
      static abstract TResult operator +(TSelf left, TOther right);

      static virtual TResult operator checked +(TSelf left, TOther right) => left + right;
  }

IAdditiveIdentity.cs — additive identity, or zero

  public interface IAdditiveIdentity<TSelf, TResult>
      where TSelf : IAdditiveIdentity<TSelf, TResult>?
  {
      static abstract TResult AdditiveIdentity { get; }
  }

IUnaryNegationOperators.cs — unary negation

  public interface IUnaryNegationOperators<TSelf, TResult>
      where TSelf : IUnaryNegationOperators<TSelf, TResult>?
  {
      static abstract TResult operator -(TSelf value);

      static virtual TResult operator checked -(TSelf value) => -value;
  }

ISubtractionOperators.cs — subtraction

  public interface ISubtractionOperators<TSelf, TOther, TResult>
      where TSelf : ISubtractionOperators<TSelf, TOther, TResult>?
  {
      static abstract TResult operator -(TSelf left, TOther right);

      static virtual TResult operator checked -(TSelf left, TOther right) => left - right;
  }

IMultiplyOperators.cs — multiplication

  public interface IMultiplyOperators<TSelf, TOther, TResult>
      where TSelf : IMultiplyOperators<TSelf, TOther, TResult>?
  {
      static abstract TResult operator *(TSelf left, TOther right);

      static virtual TResult operator checked *(TSelf left, TOther right) => left * right;
  }

IMultiplicativeIdentity.cs — multiplicative identity, or one

  public interface IMultiplicativeIdentity<TSelf, TResult>
      where TSelf : IMultiplicativeIdentity<TSelf, TResult>?
  {
      static abstract TResult MultiplicativeIdentity { get; }
  }

.NET Numerics arrived as a BCL expansion through a series of pull requests to the .NET runtime: the filtered pull-request list is here.

One of the earliest and most important PRs is dotnet/runtime#54650. It covered several tasks:

Creating numeric contracts. The interfaces provide abstractions for the operations shown above.
Applying those contracts to built-in data types. If a type already supported +, such as DateTime, it implemented the corresponding interface.
Adding runtime support in System.Runtime.cs.

Notice how few lines the pull request removed: only 27.

How Static Abstract Interface Members Work

The compiler backend required no substantial changes.

The Intermediate Language restriction against using static and abstract together was removed. The platform had been prepared for the feature since at least C# 8, which introduced default interface implementations.

When the compiler generates IL for a call to an abstract static member, it emits a constrained. call sequence.

public static T Sum<T>(this T[] array) where T :
    IAdditiveIdentity<T, T>,
    IAdditionOperators<T, T, T>
{
    var result = T.AdditiveIdentity;
    for (var i = 0; i < array.Length; i++)
        result += array[i];
    return result;
}

Generic Math Uses Beyond Numerical Code

The standard library gained more than algebraic abstractions. It also received useful utility contracts, including a standardized way to turn strings into objects.

IParsable

public interface IParsable<TSelf>
    where TSelf : IParsable<TSelf>?
{
    static abstract TSelf Parse(string s, IFormatProvider? provider);

    static abstract bool TryParse(
        [NotNullWhen(true)] string? s,
        IFormatProvider? provider,
        [MaybeNullWhen(false)] out TSelf result);
}

At the API level, this is effectively a formalized Value Object contract. It is especially useful in ASP.NET Core. Suppose an endpoint accepts a date range encoded as a query-string value:

public class DateRange
{
    public DateOnly? From { get; init; }

    public DateOnly? To { get; init; }
}

Previously, even Microsoft’s documentation did not make the recommended string-to-object mechanism obvious. Should you use TypeConverter, IModelBinder, or something else? Every solution was fairly verbose and sometimes invasive. Here is my earlier IModelBinder implementation.

Old ASP.NET Core model binding

First, implement the model binder:

internal class DateRangeModelBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        ArgumentNullException.ThrowIfNull(bindingContext);
        var fieldName = bindingContext.FieldName;
        var valueProviderResult = bindingContext.ValueProvider.GetValue(fieldName);
        if (valueProviderResult == ValueProviderResult.None)
            return Task.CompletedTask;
        bindingContext.ModelState.SetModelValue(fieldName, valueProviderResult);
        var value = valueProviderResult.FirstValue;
        if (string.IsNullOrEmpty(value))
        {
            bindingContext.Result = ModelBindingResult.Failed();
            return Task.CompletedTask;
        }
        var segments = value.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        var dtfi = new DateTimeFormatInfo
        {
            DateSeparator = "/"
        };
        if (segments.Length == 2
            && DateOnly.TryParse(segments[0], dtfi, out var fromDate)
            && DateOnly.TryParse(segments[1], dtfi, out var toDate))
        {
            var dateRange = new DateRange
            {
                From = fromDate,
                To = toDate
            };
            bindingContext.Result = ModelBindingResult.Success(dateRange);
            return Task.CompletedTask;
        }
        bindingContext.Result = ModelBindingResult.Failed();
        return Task.CompletedTask;
    }
}

Then connect it to the endpoint. It is still unclear how to handle a date range nested inside another request object:

// GET /WeatherForecast/ByRange?range=7/24/2022,07/26/2022
public IActionResult ByRange(
    [ModelBinder<DateRangeModelBinder>] DateRange range)
{
    // ...
}

With the .NET 7 interfaces, implementing IParsable once is enough:

public class DateRange : IParsable<DateRange>
{
    public DateOnly? From { get; init; }

    public DateOnly? To { get; init; }

    public static DateRange Parse(string value, IFormatProvider? provider)
    {
        if (!TryParse(value, provider, out var result))
        {
            throw new ArgumentException("Could not parse supplied value.", nameof(value));
        }
        return result;
    }

    public static bool TryParse(string? value,
        IFormatProvider? provider, out DateRange dateRange)
    {
        var segments = value?.Split(
            ',',
            StringSplitOptions.RemoveEmptyEntries |
            StringSplitOptions.TrimEntries);
        if (segments?.Length == 2
            && DateOnly.TryParse(segments[0], provider, out var fromDate)
            && DateOnly.TryParse(segments[1], provider, out var toDate))
        {
            dateRange = new DateRange { From = fromDate, To = toDate };
            return true;
        }
        dateRange = new DateRange { From = default, To = default };
        return false;
    }
}

The endpoint becomes:

// GET /WeatherForecast/ByRange?range=7/24/2022,07/26/2022
public IActionResult ByRange([FromQuery] DateRange range)
{
    // ...
}

Designing a Cache-Like Store

Suppose we need a cache-like store whose key depends on the type of the stored item. Before .NET 7, the options all had drawbacks.

An instance contract can require every object to expose a key, but it cannot retrieve an object from the cache when no instance exists.

  interface IResource
  {
      string CacheKey { get; }
  }

An attribute can mark cacheable types, but reading its metadata through reflection costs performance.

  [CacheKey(nameof(MyResource) + "suffix")]
  record MyResource;

  class CacheKeyAttribute(string value) : Attribute
  {
      public string Value { get; } = value;
  }

A separate provider service can hold the logic, but distributing and exposing it cleanly becomes difficult.

  abstract class KeyProvider
  {
      public abstract string Key { get; }
  }

  abstract class Resource<TKeyProvider>
      where TKeyProvider : KeyProvider, new()
  {
      public string CacheKey =>
          new TKeyProvider().Key;
  }

An explicit type-to-key map requires ongoing configuration maintenance and loses type safety.

  class Cache(IReadOnlyDictionary<Type, string> resourceTypeToKeyMap);

Static abstract members make the design straightforward: define a contract and put information shared by all instances on the type itself.

interface IResource
{
    //...
    static abstract string CacheKey { get; }
}

class Cache
{
    public TResource Get<TResource>() where TResource : IResource
    {
        string cacheKey = TResource.CacheKey;
        // ...
        return //...;

    }

    public void Set<TResource>(TResource resource) where TResource : IResource
    {
        string cacheKey = TResource.CacheKey;
        // ...
    }
}

Static Abstraction Patterns in C

We can now design patterns for algorithms that need information at the type level but have no object instance. The result is type-safe, more general code:

public interface IAsyncFactory<T>
{
    static abstract Task<T> CreateAsync();
}

public interface IExampleStrategy
{
    static abstract bool IsEnabled(string foo);

    void DoStuff(string foo);
}

Integrating with Generic Attributes

As I demonstrated in an article about unit tests, static members on abstract contracts can extend attribute behavior by invoking logic from a constructor’s static context:

public interface IFixtureCustomizer
{
    static abstract void Customize(IFixture fixture);
}

public class AutoDataAttribute<TFixtureCustomizer>() :
    AutoDataAttribute(
        fixtureFactory: () =>
        {
            var fixture = new Fixture();
            TFixtureCustomizer.Customize(fixture);
            return fixture;
        }) where TFixtureCustomizer : IFixtureCustomizer;

Generic Math for Domain-Driven Design

Static abstract members also let us reconsider how we design entities in C# applications that use Domain-Driven Design. A common practice is for every operation on an entity to emit a domain event that can be handled elsewhere:

interface IDomainEvent;

interface IEntityCreated<T> : IDomainEvent
{
    T Entity { get; }
}

record CustomerCreated(Customer Entity) : IEntityCreated<Customer>;

Constructors are often avoided for entity creation because they cannot return an event. Static factory methods can return whatever the domain requires:

record CustomerCreateDto(string Name, DateTimeOffset DateOfBirth);

class Customer(Guid id, string name, DateTimeOffset? dateOfBirth)
{
    public static IEntityCreated<Customer> Create(CustomerCreateDto createDto) =>
        new CustomerCreated(
            new Customer(
                id: Guid.NewGuid(),
                createDto.Name,
                createDto.DateOfBirth));
}

We can generalize creation for Customer, and for any other entity, while expressing the domain’s creation scenarios in the type system—a genuine ubiquitous language:

interface IFactory<TEntity, TEntityCreateDto>
    where TEntity : class, IFactory<TEntity, TEntityCreateDto>
    where TEntityCreateDto : class
{
    static abstract IEntityCreated<TEntity> Create(
        TEntityCreateDto createDto);
}

Because a customer’s birth date is optional, we can describe two creation scenarios: one with a date and one without.

record CustomerCreateDto(string Name, DateTimeOffset DateOfBirth);

record CustomerCreateWithoutDateOfBirthDto(string Name);

class Customer(Guid id, string name, DateTimeOffset? dateOfBirth) :
    IFactory<Customer, CustomerCreateDto>,
    IFactory<Customer, CustomerCreateWithoutDateOfBirthDto>
{
    public static IEntityCreated<Customer> Create(
        CustomerCreateDto createDto) =>
        new CustomerCreated(
            new Customer(
                id: Guid.NewGuid(),
                createDto.Name,
                createDto.DateOfBirth));

    public static IEntityCreated<Customer> Create(
        CustomerCreateWithoutDateOfBirthDto createDto) =>
        new CustomerCreated(
            new Customer(
                id: Guid.NewGuid(),
                createDto.Name,
                dateOfBirth: null));
}

Contracts for Generated Database Models

Suppose a project uses Database First and generates C# classes from an existing schema. A documents table is represented by a generated Document class:

partial class Document
{
    public required string Name { get; set; }
    // ...
    public static int NameLengthConstraint { get; }
}

We want an interface containing information about the corresponding columns. An instance contract for the columns looks obvious:

interface IDocument
{
    // ...
    public string Name { get; set; }
}

partial class Document : IDocument;

But the generator also produces static fields describing constraints, such as the maximum string length. Ordinary interfaces could not include those values. static abstract can:

interface IDocumentConstraints<TDocument>
    where TDocument : IDocumentConstraints<TDocument>
{
    static abstract int NameLengthConstraint { get; }
}

partial class Document :
    IDocument,
    IDocumentConstraints<Document>;

Static Interfaces as an Architectural Boundary

Consider a DDD and Clean Architecture solution in which subdomains are separated into projects.

A domain entity lives in HydraScript.Domain.FrontEnd. Its implementation needs a regular expression produced by a source generator in HydraScript.Infrastructure.LexeRegexGenerator. How can the implementation cross that boundary cleanly? The same tactical DDD patterns can be applied in a new form. First define a regular-expression container, inject it into the domain entity through a static abstract contract, and wire the closed generic type through dependency injection.

public interface IStructure : IEnumerable<TokenType>
{
    public Regex Regex { get; }

    public TokenType FindByTag(string tag);
}

public interface IGeneratedRegexContainer
{
    public static abstract Regex Regex { get; }
}

public class Structure<TContainer>(ITokenTypesProvider provider) : IStructure
    where TContainer : IGeneratedRegexContainer
{
    // ...
    public Regex Regex { get; } = TContainer.Regex;
}
// ...
services.AddSingleton<IStructure, Structure<GeneratedRegexContainer>>();

A Note on ML.NET

ML.NET brings machine learning to .NET applications in both online and offline scenarios. Its central abstraction is a machine-learning model: a black box that, after training, produces an output for a given input.

You can train a model with ML.NET or import a pretrained model in the ONNX format—the closest thing the neural-network ecosystem has to a widely shared interchange format. In practice, however, models are rarely trained on .NET because the tooling and algorithm implementations remain limited.

Dmitry Soshnikov’s talk referenced in the original article discusses ML.NET’s problems.

After Generic Math arrived, a large-scale framework refactoring opened the door to deep learning on .NET (dotnet/machinelearning#6664).

Spans, Tensors, and SIMD

The AI problem is also being approached through System.Numerics.Tensors, a NuGet package for tensor computations. The broader direction only became clear over time.

.NET 9 introduced the Tensor type and expanded TensorPrimitives, which now provides generic operations over vector data exposed through Span wrappers.

These methods use the CPU’s available SIMD acceleration, including AVX and SSE.

public class ManhattanDistance<T> : IDistanceCalculator<T>
    where T : unmanaged, INumberBase<T>
{
    public double ComputeDistance(T[] attributesOne, T[] attributesTwo)
    {
        Span<T> diff = stackalloc T[Math.Min(attributesOne.Length, attributesTwo.Length)];
        TensorPrimitives.Subtract(attributesOne, attributesTwo, diff);
        var l1Norm = TensorPrimitives.SumOfMagnitudes<T>(diff);
        return double.CreateTruncating(l1Norm);
    }
}

This looks like a long-running, multi-step strategy involving Generic Math, Span, stackalloc, and more. It addresses several goals at once:

OOP developers get a powerful architectural tool that replaces singleton workarounds and awkward attempts to simulate ad hoc polymorphism.
Microsoft moves closer to a competitive machine-learning platform, including deep-model development and the possibility of training neural networks in C# rather than Python.
Performance-focused developers get accelerated computations over Span, which the JIT does not optimize in exactly the same way as arrays or lists.

Advantages of C# Generic Math

First, Generic Math solves the long-standing inability to abstract over arithmetic operations. Microsoft is now actively filling the corresponding holes in platform APIs.

Second, it provides a powerful advanced-design tool—possibly one ahead of its time.

Third, as the alternatives and benchmark below demonstrate, static abstract members do not introduce a performance penalty in C# code.

Limitations of C# Generic Math

First, Generic Math works only when the participating type completes the entire contract: you own the contract and the implementation. You cannot retroactively apply an abstraction to third-party code. Suppose I combine two interfaces into a monoid-like IAdditive contract and implement it for a custom string wrapper:

interface IAdditive<TAdditive> :
    IAdditiveIdentity<TAdditive, TAdditive>,
    IAdditionOperators<TAdditive, TAdditive, TAdditive>
    where TAdditive : IAdditive<TAdditive>;

class AdditiveString(string s) : IAdditive<AdditiveString>
{
    private readonly string _string = s;

    public static AdditiveString AdditiveIdentity => new(string.Empty);

    public static AdditiveString operator +(AdditiveString left, AdditiveString right) =>
        new(left._string + right._string);
}

The custom type works, but built-in types are excluded even when they appear to satisfy the same requirements—+ and zero.

The two practical workarounds are wrappers and large generic constraint lists. A language feature that might have solved this was implicit interface: adding implicit to the interface declaration would make the code in the screenshot compile. The idea appeared in 2015, but discussion stalled in 2020 and the proposal became “Likely Never” (dotnet/csharplang#110).

Second, an abstract base class cannot defer implementation of abstract static members. This code does not compile:

abstract class AdditiveBase<TAdditive> : IAdditive<TAdditive>
    where TAdditive : IAdditive<TAdditive>
{
    public abstract static TAdditive AdditiveIdentity { get; }

    public abstract static TAdditive operator +(TAdditive left, TAdditive right);
}

The restriction is understandable: abstract static members are not polymorphic in the same way as instance members.

Alternatives to C# Generic Math

We have covered Generic Math, production and exploratory use cases, strengths, and limitations. Now let’s compare it with other language designs and with approaches available inside C# itself. First, a short detour into three kinds of polymorphism.

Three Kinds of Polymorphism

Polymorphism means more than object-oriented inheritance. Many kinds exist; we need three of them.

Suppose we need a printer that can print several kinds of object. The design depends on which form of polymorphism we choose.

Subtype polymorphism is the familiar OOP model: define a base abstraction and implement it in derived types.

   interface IPrintable
   {
       string Content { get; }
   }

   interface IPrinter
   {
       void Print(IPrintable printable);
   }

Parametric polymorphism is implemented in C# through generics. The implementation is parameterized by something—in this case, a type.

   interface IPrinter<in T>
   {
       void Print(T item);
   }

Ad hoc polymorphism appears in C# as method overloading. The compiler selects the required implementation.

   interface IPrinter
   {
       void Print(int i);

       void Print(string s);

       void Print(bool b);
   }

Ad hoc polymorphism comes closest to the static generic abstraction we want, but it raises another question: how can the compiler provide one universal contract instead of many overloads? One answer is the pattern known as...

Type Classes

Type classes separate operations from data. The approach comes from functional programming and is built into some functional languages, including Haskell.

In C#, we can model the pattern with generics and structs. Here is the printer example:

class Printer
{
    public void Print<T, TPrintable>(T item)
        where TPrintable : struct, IPrintable<T>
    {
        var content = default(TPrintable).GetContent(item);
        Console.WriteLine(content);
    }
}

interface IPrintable<T>
{
    string GetContent(T item);
}

struct PrintableInt : IPrintable<int>
{
    public string GetContent(int item) =>
        item.ToString();
}

struct PrintableBool : IPrintable<bool>
{
    public string GetContent(bool item) =>
        item ? "true" : "false";
}

var printer = new Printer();
printer.Print<int, PrintableInt>(13);
printer.Print<bool, PrintableBool>(false);

Armed with that technique, we can solve the generic-summation problem in a functional style:

interface IAdder<T>
{
    T Zero { get; }

    T Plus(T left, T right);
}

public static T SumTypeClass<T, TAdder>(
    this IReadOnlyList<T> array,
    TAdder adder = default)
    where TAdder : struct, IAdder<T>
{
    var result = adder.Zero;
    var count = array.Count;
    for (var i = 0; i < count; i++)
        result = adder.Plus(result, array[i]);
    return result;
}

int[] array = [1, 2, 3];
var sum = array.SumTypeClass<int, IntAdder>();

struct IntAdder : IAdder<int>
{
    public int Zero => 0;

    public int Plus(int left, int right) =>
        left + right;
}

The code is efficient and reasonably clean, but it creates a new problem: callers must explicitly specify both generic type arguments to SumTypeClass. C# inference flows from source to destination and cannot infer the evidence type here. Explicitly typed extension wrappers can hide the extra argument.

Could C# have gained type classes directly? In 2017, a proposal named “Type Classes for the Masses” appeared (discussion).

It would have introduced a new language entity: the concept.

A concept would act as a contract implemented by an instance. The implicit keyword would solve the explicit-type-argument problem by resolving the type from context.

concept Num<A>
{
    A operator +(A a, A b);
    A operator *(A a, A b);
    A operator -(A a, A b);
    implicit operator A(int i);
}

instance NumInt
{
    int operator +(int a, int b) => a + b;
    int operator *(int a, int b) => a * b;
    int operator -(int a, int b) => a – b;
    implicit operator int(int i) => i;
}

public static A F<A, implicit NumA>(A x)
    where NumA : Num<A> =>
    x * x + x + 666;

The proposal is “Likely Never” for reasons we can only speculate about. Some believe it was a political decision to follow the OOP route to the end. Others blame the association with Scala’s problematic implicits: perhaps .NET should fix the JVM ecosystem’s mistakes rather than repeat them.

trait Comparator[A]:
    def compare(x: A, y: A): Int

object Comparator:
    given Comparator[Int] with
        def compare(x: Int, y: Int): Int = Integer.compare(x, y)

    given Comparator[String] with
        def compare(x: String, y: String): Int = x.compareTo(y)
end Comparator

def max[A](x: A, y: A)(using comparator: Comparator[A]): A =
    if comparator.compare(x, y) >= 0 then x
    else y

println(max(10, 6))             // 10
println(max("hello", "world"))  // world

For more about ad hoc polymorphism and type classes:

Swift’s Alternative

Let’s briefly visit iOS development and examine another form of generic arithmetic. Swift’s counterpart to interfaces is the protocol:

protocol Animal {
    var maxBabiesCount: Int { get }
    func getSound() -> String
}

class Cat : Animal {
    let maxBabiesCount: Int = 5

    func getSound() -> String {
        "Meow"
    }
}

A protocol can declare an associated type, which is roughly analogous to parameterizing an interface:

protocol Animal {
    associatedtype BabyType
    var babies: [BabyType] { get set }
}

class Cat : Animal {
    var babies = [Kitten]()
}

class Kitten { }

A protocol can also require an associated type to be the implementing type itself. For example, animals may mate only with their own kind: cats with cats and cows with cows.

protocol Animal {
    func mate(with: Self)
}

class Cat : Animal {
    func mate(with: Cat) {
        print("mating with another cat")
    }
}

Swift was therefore prepared at the language level for a generic arithmetic library: protocols support both Self and static members. This led to the Swift Numerics proposal, authored by LLVM creator Chris Lattner.

public protocol AdditiveArithmetic : Equatable {
    static var zero: Self { get }
    static func + (lhs: Self, rhs: Self) -> Self
}

The main difference from .NET is that Swift groups arithmetic properties much like algebraic structures do. The lack of fine-grained interfaces may be related to Swift’s ability to apply abstractions to external code, although I cannot say for certain.

Performance

Now that we have alternatives to compare, let’s benchmark C# Generic Math summation against the type-class implementation, a classic loop, and LINQ.

Benchmark configuration:

BenchmarkDotNet v0.13.12
macOS Monterey 12.3
Apple M1 Pro, 1 CPU, 10 logical and 10 physical cores
.NET SDK 8.0.100

Benchmark code

struct IntAdder : IAdder<int>
{
    public int Zero => 0;

    public int Plus(int left, int right) =>
        left + right;
}

interface IAdder<T>
{
    T Zero { get; }

    T Plus(T left, T right);
}

static class ArrayExtensions
{
    public static T SumTypeClass<T, TAdder>(
        this IReadOnlyList<T> array,
        TAdder adder = default)
        where TAdder : struct, IAdder<T>
    {
        var result = adder.Zero;
        var count = array.Count;
        for (var i = 0; i < count; i++)
            result = adder.Plus(result, array[i]);
        return result;
    }

    public static T SumGenericMath<T>(
        this IReadOnlyList<T> array) where T :
        IAdditiveIdentity<T, T>,
        IAdditionOperators<T, T, T>
    {
        var result = T.AdditiveIdentity;
        var count = array.Count;
        for (var i = 0; i < count; i++)
            result += array[i];
        return result;
    }
}

[SimpleJob]
[SuppressMessage("ReSharper", "UnassignedField.Global")]
#pragma warning disable CA1050
public class SumBenchmarks
#pragma warning restore CA1050
{
    private IReadOnlyList<int> _dataSet = [];
    private readonly Consumer _consumer = new();
    [Params(100_000)]
    public int CollectionCount;
    [Params(CollectionType.Array, CollectionType.ImmutableArray)]
    public CollectionType CollectionType;

    [GlobalSetup]
    public void GlobalSetup()
    {
        var enumerable = Enumerable.Range(1, CollectionCount)
            .Select(_ => Random.Shared.Next(1, 10001));
        _dataSet = CollectionType switch
        {
            CollectionType.Array => enumerable.ToArray(),
            CollectionType.ImmutableArray => enumerable.ToImmutableArray(),
            _ => throw new ArgumentOutOfRangeException(nameof(CollectionType))
        };
    }

    [Benchmark(Baseline = true)]
    public void SumLinq()
    {
        var sum = _dataSet.Sum();
        _consumer.Consume(sum);
    }

    [Benchmark]
    public void SumClassicFor()
    {
        var sum = 0;
        for (var i = 0; i < CollectionCount; i++)
            sum += _dataSet[i];
        _consumer.Consume(sum);
    }

    [Benchmark]
    public void SumTypeClass()
    {
        var sum = _dataSet.SumTypeClass<int, IntAdder>();
        _consumer.Consume(sum);
    }

    [Benchmark]
    public void SumGenericMath()
    {
        var sum = _dataSet.SumGenericMath();
        _consumer.Consume(sum);
    }
}
#pragma warning disable CA1050
public enum CollectionType
#pragma warning restore CA1050
{
    Array,
    ImmutableArray
}

The result was interesting: LINQ beat our summation functions. Looking at the source revealed why. The array and list paths use optimizations based on Span and marshalling.

Takeaways

Generic Math is worth considering when an algorithm needs capabilities that can be stated as compile-time contracts: operators, identities, parsing, or other static members. It can remove reflection and runtime dispatch while keeping algorithms reusable across built-in and domain-specific types.

The cost is a denser public API, longer constraint lists, and abstractions that many C# developers have not yet internalized. Keep the constraints as small as the algorithm allows, expose domain-focused interfaces when raw numeric contracts leak too far, and benchmark the complete workload rather than assuming generic code is automatically faster.

Related C# Content

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

AutoFixture and AutoData: Reduce .NET Test Setup

StepOne — Fri, 11 Sep 2026 19:00:23 +0000

A unit test can spend more lines constructing irrelevant objects and mocks than expressing the behavior it protects. That Arrange boilerplate slows reviews, obscures the important inputs, and becomes another structure to maintain when constructors change.

This article shows how AutoFixture, AutoData, and AutoNSubstitute can generate data and compose dependencies so a test keeps only the setup that matters. It is aimed at experienced .NET developers and technical leads evaluating whether convention-based fixture generation will improve—or hide—the intent of their test suite.

Why Arrange Boilerplate Hurts Unit Tests

Who writes unit tests at work? Probably almost everyone reading this article.

Who runs short of time while writing them? Probably almost everyone who writes them.

I will assume unit tests need no defense here.

Building a new feature? Verify the implementation.
Found a bug? Cover the fix with a test.
Trying to understand legacy code? Debug it through the test runner.

No matter how many AI tools appear, the situation remains familiar: the sprint has been packed with business features, and your manager looks like this:

The problem is a lack of time. Before we can tackle it, though, we need to talk about…

Arrange, Act, and Assert in .NET Tests

Teams use different libraries and tools, but in my commercial experience, two conventions work well for organizing and structuring test code.

I am talking, of course, about AAA and Roy Osherove's naming convention.

AAA in Plain English

As you may have guessed, this is not about batteries or video games. It is about unit testing.

Programming is already complex enough; navigating a codebase becomes even harder when everything is scattered and nothing is where it belongs.

Life is much easier when everything has a clear place.

Tests can also be organized into clear, concrete stages:

Arrange. Set up the test: create objects, prepare data, configure mocks, and so on.
Act. Perform the action—call the functionality under test.
Assert. Verify the result. Check the data, object state, expected calls, errors, or anything else the scenario requires.

Arrange-Act-Assert gives tests a simple, effective, and recognizable structure.

Roy Osherove in Plain English

A second convention covers test names.

Roy Osherove's test-naming convention looks like this:

UnitOfWork_StateUnderTest_ExpectedBehavior

For English speakers, the structure is mostly self-explanatory. A test name specifies:

the unit of work,
the state configured by the test,
the expected behavior.

Does that look familiar? If it reminded you of AAA, you have the idea.

This simple rule is easy to adopt, yet it improves project structure and navigation.

Example

public record Adder(int Value)
{
    public Adder Add(Adder that) =>
        new(Value + that.Value);
}

public class AdderTests
{
    [Fact]
    public void Add_AddingToZero_ResultNotAffectedByZero()
    {
        // arrange
        Adder ten = new(10);
        Adder zero = new(0);

        // act
        var sum = ten.Add(zero);

        // assert
        sum.Should().Be(ten);
    }
}

The Cost of Manual Test-Data Setup

Why did we need to discuss these conventions? Because this kind of structure makes the process systematic—and makes bottlenecks obvious.

Unit tests really have one bottleneck: Arrange. Act and Assert usually take about two lines each. Arrange is where things get interesting—and large. Object setup, collections, integration behavior, configuration: it all lives there.

Now imagine that we are working on a typical task in an enterprise codebase. We write some thoroughly average code and end up with an equally average…

A Typical Handler

public class SomeHandler(
    ISomeRepository repository,
    ISomeProcessingService service,
    ISomeSessionAccessor sessionAccessor,
    ISomeExternalDataProvider provider,
    IOptions<SomeOptions> options,
    ILogger<SomeHandler> logger)
{
    private readonly SomeOptions _options = options.Value;

    public async Task<SomeResponse> Handle(SomeRequest request, CancellationToken ct)
    {
        if (request.Field1 < 0)
            throw new SomeException();
        var entity = await repository.GetByField2(request.Field2, ct);
        if (request.Field3)
        {
            await service.ProcessAsync(entity, ct);
            logger.LogInformation("processed");
        }
        var session = sessionAccessor.Session;
        session.ChangeStatus();
        var externalData = await Task.WhenAll(
            _options.Sources.Select(
                source => provider.GetCollectionBySource(source, ct)));
        return new SomeResponse(
            entity,
            externalData.SelectMany(x => x).ToArray());
    }
}

This is your average piece of JSON plumbing: it changes something in a session, logs something, reads some configuration, writes something to a database, and returns something to the outside world.

A meaningless and merciless sequence of symbols, even if it is semantically and syntactically valid.

Now let us write a unit test according to London-school practices. It will not even fit on a single PowerPoint slide.

I used NSubstitute for mocking: www.nuget.org/packages/NSubstitute.

I prefer it for its concise API and lack of SponsorLink incidents.

public class SomeHandlerTests
{
    [Fact]
    public async Task Handle_HappyPath_DoesNotThrow()
    {
        var repository = Substitute.For<ISomeRepository>();
        repository.GetByField2(default, default)
            .ReturnsForAnyArgs(new SomeEntity(
                Field2: nameof(SomeEntity.Field2),
                Data: nameof(SomeEntity.Data)));
        var service = Substitute.For<ISomeProcessingService>();
        var sessionAccessor = Substitute.For<ISomeSessionAccessor>();
        sessionAccessor.Session.Returns(Substitute.For<ISession>());
        var provider = Substitute.For<ISomeExternalDataProvider>();
        provider.GetCollectionBySource(default, default)
            .ReturnsForAnyArgs([
                new SomeExternalData(Guid.NewGuid(), Content: 1.ToString(), [1, 2, 3]),
                new SomeExternalData(Guid.NewGuid(), Content: 2.ToString(), [4, 5, 6]),
            ]);
        var handler = new SomeHandler(
            repository,
            service,
            sessionAccessor,
            provider,
            Options.Create(new SomeOptions { Sources = ["source1", "source2"] }),
            NullLogger<SomeHandler>.Instance);
        var response = await handler.Handle(new SomeRequest(
                Field1: 123,
                Field2: "123",
                Field3: true),
            ct: default);
        Assert.NotNull(response);
    }
}

All that just to test the basic happy path.

And we still have branches, behavior changes, integration failures, and much more. You might extract SUT (system under test) creation into a separate method and call it from every test.

But the application contains other handlers and services. The code will be duplicated, and the boilerplate will grow at least linearly.

What Can We Do?

Arrange has one simple goal: prepare the test.

To achieve it, boilerplate code prepares data and behavior for the scenario we want to run.

The answer practically suggests itself:

Automate data preparation. Eliminate as many new() and [] calls as possible.
Automate behavior preparation. Eliminate as much mock creation and setup as possible.

Reducing Arrange with AutoFixture and AutoData

Before discussing how, let us meet the tools whose combination will solve the problem. These are several NuGet packages you may or may not have encountered. The first is…

AutoFixture

www.nuget.org/packages/AutoFixture

This NuGet package can create instances of data types with public constructors:

var fixture = new Fixture();
var bar = fixture.Create<Bar>();

record Foo(Guid Id);

record Bar(
    Foo Foo,
    string Name,
    bool IsBaz,
    int Number);

The library was created by Mark Seemann, author of Dependency Injection in .NET.

It solves exactly the problem we identified: when a meaningless 300-field DTO needs to go into the database, you can replace manual initialization with a one-line call.

The code above creates an object like this:

{
    "Foo": {
        "Id": "537478f7-a6f0-4e85-8ca2-1d7e0da97e7e"
    },
    "Name": "Name0e4afc29-8ef7-4991-aaa1-2294a456cccc",
    "IsBaz": false,
    "Number": 58
}

AutoData

www.nuget.org/packages/AutoFixture.Xunit2/5.0.0-preview0011

I am lazy not only as a programmer: I do not want to instantiate Fixture objects and create every related object myself. I want everything ready by the time the test starts.

Fortunately, AutoFixture has connectors for test frameworks such as xUnit. Informally, I call this family of features AutoData, after the attribute that provides the behavior I need.

We apply the attribute to theory tests. It implicitly creates a data source whose Fixture instance produces the objects requested by the theory parameters.

public class TestClass
{
    [Theory, AutoData]
    public void TestMethod1(string foo)
    {
        foo.Should().NotBeEmpty();
    }

    [Theory, AutoData]
    public void TestMethod2(Foo foo)
    {
        foo.Bar.Should().NotBeEmpty();
    }
}

public class Foo
{
    public string Bar { get; set; }
}

Strictly speaking, this is a synthetic theory because it has only one case. But what if you already have data sources?

There are InlineAutoData, MemberAutoData, ClassAutoData, and other attributes:

public class TestClass
{
    [Theory]
    [MemberAutoData(nameof(TestData))]
    public void TestMethod3(int a, int b, int c)
    {
        c.Should().BeGreaterThan(a + b);
    }

    public static IEnumerable<object[]> TestData =
    [
        [-1, -2],
        [-3, -4]
    ];
}

Here, the data source supplied the first two test parameters for each case, while AutoFixture created the third. One theory now covers every listed case without repeating incidental setup.

Data preparation is now automated, so we are ready to move on.

AutoData + Mocks = AutoNSubstitute

What should we do about mocks?

When preparing them, we create a mock instance and configure some return value—either an object or another mock.

What if we asked AutoFixture to create a mock whose return values were populated with the results of Create calls?

It turns out that the AutoNSubstitute customization does exactly that.

NuGet packages also exist for Moq, RhinoMocks, and FakeItEasy.

To create mocks, enhance the data generator with Customize. The test looks like this:

public class TestClassClass
{
    [Fact]
    public async Task Test()
    {
        var fixture = new Fixture()
            .Customize(
                new AutoNSubstituteCustomization
                {
                    ConfigureMembers = true
                });
        var provider = fixture.Create<ISomeExternalDataProvider>();
        var collection = await provider.GetCollectionBySource(
            source: fixture.Create<string>(),
            ct: default);
        Assert.NotEmpty(collection);
    }
}

The debugger screenshot shows the service instance that AutoFixture created for ISomeExternalDataProvider, including the automatically mocked method's return value.

Combining AutoFixture, AutoData, and AutoNSubstitute

We can now combine all three pieces behind a single attribute.

A test method marked with this attribute receives both objects and configured mocks:

public class AutoNSubstituteDataAttribute() :
    AutoDataAttribute(
        () => new Fixture().Customize(
            new AutoNSubstituteCustomization
            {
                ConfigureMembers = true
            }));

This attribute is not included out of the box. Mark Seemann suggests creating it yourself in his blog, using inheritance as the extension model.

Return to our typical handler. The test that would not fit on any screen can now be rewritten in two lines, letting us ignore the routine setup and focus on scenarios that verify the logic:

public class SomeHandlerTests2
{
    [Theory, AutoNSubstituteData]
    public async Task Handle_HappyPath_DoesNotThrow(
        SomeRequest request,
        SomeHandler handler)
    {
        var response = await handler.Handle(request, ct: default);
        Assert.NotNull(response);
    }

    [Theory, AutoNSubstituteData]
    public async Task Handle_Field1LessThanZero_ThrowsSomeException(
        SomeRequest request,
        SomeHandler handler)
    {
        await Assert.ThrowsAsync<SomeException>(
            () => handler.Handle(request with { Field1 = -1 }, ct: default));
    }

    [Theory, AutoNSubstituteData]
    public async Task Handle_NoExternalData_ItIsEmptyInResponse(
        SomeRequest request,
        [Frozen] ISomeExternalDataProvider provider,
        SomeHandler handler)
    {
        provider.GetCollectionBySource(default, default)
            .ReturnsForAnyArgs([]);
        var response = await handler.Handle(request, ct: default);
        response.ExternalDataCollection.Should().BeEmpty();
    }
}

Advanced Scenarios

AutoFixture is a powerful data generator, but it cannot infer every domain rule or create exactly the data you want. You have to tell it how.

That brings us back to extending its behavior. Inheritance is not an ideal extension model here: one codebase may contain multiple domains and business-logic implementations, potentially causing an explosion of derived attributes that quickly become confusing.

We can modify the behavior another way. Here is a real example from practice. Suppose we have a Value Object that models a discrete rating from 1 to 5:

public struct Rate
{
    public Rate(byte value)
    {
        if (value is >= 1 and <= 5)
            Value = value;
        else
            throw new ArgumentOutOfRangeException(
                nameof(value),
                value,
                message: "rate can be from 1 to 5");
    }

    public byte Value { get; }
}

If we ask for a rating object in a test, we get an error:

public class TestClassClass
{
    [Theory, AutoData]
    public void Test22(Rate rate)
    {
        rate.Value.Should().NotBe(0);
    }
}

The reason is that AutoFixture generates data according to its own rules:

Generic Attributes + `static abstract`

Let us investigate. Look inside [AutoData] and you will see a constructor that accepts a Func<Fixture> delegate:

public AutoDataAttribute()
    : this(() => new Fixture())
{
}

We can use that hook to configure the Fixture object however we need. But how do we obtain different services and dependencies from a static constructor context, especially when attribute parameters can contain only constants and types?

Two C# 11 features help us: static abstract members and generic attributes. They work surprisingly well together.

public interface IFixtureCustomizer
{
    static abstract void Customize(IFixture fixture);
}

public class AutoDataAttribute<TFixtureCustomizer> : AutoDataAttribute
    where TFixtureCustomizer : IFixtureCustomizer
{
    public AutoDataAttribute() : base(
        fixtureFactory: () =>
        {
            var fixture = new Fixture();
            TFixtureCustomizer.Customize(fixture);
            return fixture;
        })
    {
    }
}

Our data-generator extension for ratings now looks like this:

public class RateGenerator : IFixtureCustomizer
{
    public static void Customize(IFixture fixture) =>
        fixture.Register(() => new Rate((byte)Random.Shared.Next(1, 6)));
}

public class TestClassClass
{
    [Theory, AutoData<RateGenerator>]
    public void Test22(Rate rate)
    {
        rate.Value.Should().NotBe(0);
    }
}

If your project is still on .NET 6 or earlier, adapt the solution as follows:

Make IFixtureCustomizer instance-based.
Have the attribute extension accept a type supplied through typeof.
Instantiate the customizer inside the attribute through Activator.CreateInstance.

Test Data Types

You can also describe the desired behavior and test-data generation scenario with classes whose objects AutoData creates as theory parameters.

For example, AutoFixture uses the Fare library to generate strings from a regular expression.

I recently needed this in a pet project: a test had to generate random sequences of strings from a particular lexical grammar. Armed with the documentation and some ingenuity, I automated preparation of those strings with a class passed as a test parameter:

public record LexerInput([property: MinLength(10), MaxLength(25)] TokenInput[] TokenInputs) : IReadOnlyList<string>
{
    public IEnumerator<string> GetEnumerator() =>
        TokenInputs.Select(x => x.Value).GetEnumerator();

    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();

    public int Count => TokenInputs.Length;

    public string this[int index] => TokenInputs[index].Value;

    public override string ToString() =>
        TokenInputs.Aggregate(
            TokenInput.AdditiveIdentity,
            (x, y) => x + y).Value;
}

public record TokenInput([property: RegularExpression(TokenInput.Pattern)] string Value) :
    IAdditiveIdentity<TokenInput, TokenInput>,
    IAdditionOperators<TokenInput, TokenInput, TokenInput>
{
    [StringSyntax(StringSyntaxAttribute.Regex)]
    public const string Pattern = "[a-zA-Z]+|[0-9]+|[+]{2}";

    public static TokenInput operator +(TokenInput left, TokenInput right) =>
        new(left.Value + " " + right.Value);

    public static TokenInput AdditiveIdentity { get; } = new(string.Empty);
}

AutoFixture reads data-creation rules from attributes in the System.ComponentModel.DataAnnotations namespace.

Here, [RegularExpression] supplies the pattern used to initialize the annotated string property, while [MinLength] and [MaxLength] provide the bounds for choosing a random array length.

The test uses it like this:

public class RegexLexerTests(ITestOutputHelper output)
{
    [Theory, AutoHydraScriptData]
    public void GetTokens_MockedRegex_ValidOutput(
        LexerInput input,
        [Frozen] IStructure structure,
        RegexLexer lexer)
    {
        output.WriteLine(input.ToString());
        var patterns = TokenInput.Pattern.Split('|');
        structure.Regex.ReturnsForAnyArgs(
            new Regex(string.Join('|', patterns.Select((x, i) => $"(?<TYPE{i}>{x})"))));
        var tokenTypes = Enumerable.Range(0, patterns.Length)
            .Select(x => new TokenType($"TYPE{x}"))
            .ToList();
        // ReSharper disable once GenericEnumeratorNotDisposed
        structure.GetEnumerator()
            .ReturnsForAnyArgs(_ => tokenTypes.GetEnumerator());
        var tokens = lexer.GetTokens(input.ToString());
        for (var i = 0; i < input.Count; i++)
        {
            output.WriteLine(tokens[i].ToString());
            tokens[i].Value.Should().BeEquivalentTo(input[i]);
            tokens[i].Type.Should().BeOneOf(tokenTypes);
        }
    }
}

Takeaways

AutoFixture can automate both parts of Arrange:

Data preparation = AutoFixture + AutoData.
Behavior preparation = AutoFixture + AutoData + mocks.

The technique works best when generated values are incidental to the behavior under test. Keep meaningful boundary values explicit, freeze dependencies whose identity matters, and add fixture customizations only when they encode a stable project-wide convention. If a reader must reverse-engineer the fixture to understand the scenario, the abstraction has removed too much Arrange.

Modern C# features let customizations remain type-safe even as the fixture setup becomes reusable across a large test suite.

Related .NET Content

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

Lord of the Algebras: Groups, Rings, and Semirings in C#

StepOne — Tue, 08 Sep 2026 22:32:07 +0000

The same matrix algorithm can count paths, find shortest paths, or find longest paths. The data structure does not change; the algebra assigned to its operations does. That is the practical payoff of modeling groups, rings, and semirings instead of hard-coding arithmetic.

Last time, we met semigroups and monoids. Algebra did not end there. As the previous article showed, moving forward means placing more constraints on the operation defined over the structure's carrier set. But how do we know which direction to take?

Much of the original interest in this field grew out of questions about equations. The exact questions do not matter here; the important word is equations.

Assume from this point onward that we have a structure and some abstract binary operation. Take the pair $(G, \circ)$ , which we call a monoid. We can choose any $a$ and $b$ from $G$ , compute $a \circ b$ , and obtain some $c \in G$ . Fine. But what if we are asked this?

a \circ x = b a, x, b \in G x = ?

A monoid alone cannot answer. We can say that $x = a^{- 1} \circ b$ , where $a^{- 1}$ is the inverse of $a$ , and $a$ is invertible. Formally, $a$ is invertible if:

\exists h = a^{- 1} : a \circ h = h \circ a = e

But a monoid does not guarantee that every element is invertible. There is, however, a way out.

Groups in `C#`

Not every element of a monoid is invertible. A monoid may nevertheless contain invertible elements, and they form a subset. That subset is a group. A group is a monoid in which every element has an inverse. This is our next constraint—the third axiom.

\forall g \in G \exists h = g^{- 1} \in G : g \circ h = h \circ g = e

public interface IGroup<T> : IMonoid<T>
{
    T Inverse(T item);
}

Inside a group, our equation $a \circ x = b$ always has a solution.

What makes groups interesting? Every object, whatever its nature, has an opposite: an inverse, a reversal, a symmetry. You may have heard group theory described as the mathematics of symmetry.

There is even a symmetric group $S_{n}$ . It contains every bijection that rearranges a set of $n$ elements. A readable representation uses two rows: $1... n$ on top, and their destinations below. For an arbitrary $ϕ \in S_{3}$ :

ϕ = (123231)

The first element moves to the second position, the second to the third, and the third to the first. Composition is defined by $(ϕ \circ π) (i) = π (ϕ (i))$ . To find the inverse, swap and reorder the rows: $ϕ (i) = j ⟹ ϕ^{- 1} (j) = i$ .

Permutation.cs

public class Permutation : IEquatable<Permutation>
{
    private readonly int[] _map;

    public Permutation(params int[] map)
    {
        _map = new int[map.Length];
        for (var i = 0; i < map.Length; i++)
        {
            _map[i] = map[i];
        }
    }

    public int this[int index] => _map[index];

    public bool Equals(Permutation other)
    {
        if (other != null && _map.Length == other._map.Length)
        {
            return _map.Zip(other._map)
                .All(pair => pair.First == pair.Second);
        }
        return false;
    }

    public override string ToString() =>
        new StringBuilder()
            .AppendJoin(' ', Enumerable.Range(1, _map.Length))
            .Append('\n')
            .AppendJoin(' ', _map.Select(x => x + 1))
            .ToString();
}

SymmetricGroup.cs

public readonly struct SymmetricGroup : IGroup<Permutation>
{
    private readonly int _length;

    public SymmetricGroup(int length)
    {
        _length = length;
    }

    public Permutation Plus(Permutation left, Permutation right)
    {
        var newMap = new int[_length];
        for (var i = 0; i < _length; i++)
        {
            newMap[i] = right[left[i]];
        }
        return new Permutation(newMap);
    }

    public Permutation Zero =>
        new(Enumerable.Range(0, _length).ToArray());

    public Permutation Inverse(Permutation item)
    {
        var newMap = new int[_length];
        for (var i = 0; i < _length; i++)
        {
            newMap[item[i]] = i;
        }
        return new Permutation(newMap);
    }
}

For the solution $x = b \circ a^{- 1}$ , the operation $\circ$ must also be commutative. Restricting groups this way gives Abelian groups $G$ :

\forall g, h \in G : g \circ h = h \circ g

That is enough theory to get a feel for the concept. Let us turn to something more practical.

Suppose we want an append-only catalog. We can record only changes—events that happened to the catalog.

public record CatalogueEvent<T>;

public record Add<T>(T Data) : CatalogueEvent<T>;

public record Remove<T>(T Data) : CatalogueEvent<T>;

public record Nothing<T> : CatalogueEvent<T>;

We also need to traverse its elements and obtain an aggregate. Each catalog item maps into a monoid element so it can be aggregated. Where do groups enter the picture?

The problem contains a symmetry: we can add or remove, and those actions are opposites. A group lets the event-to-aggregate mapping preserve that relationship.

public class Catalogue<T> : IEnumerable<CatalogueEvent<T>>
{
    private readonly List<CatalogueEvent<T>> _catalogueEvents = new();

    public S Reduce<S, G>(Func<T, S> map, G group = default)
        where G : struct, IGroup<S>
        => _catalogueEvents.Select(t =>
            t switch
            {
                Add<T> add => map(add.Data),
                Remove<T> rm => group.Inverse(map(rm.Data)),
                Nothing<T> => group.Zero,
                _ => default
            }
        ).Sum<S, G>();

    public Catalogue<T> Add(T item)
    {
        _catalogueEvents.Add(new Add<T>(item));
        return this;
    }

    public Catalogue<T> Remove(T item)
    {
        _catalogueEvents.Add(new Remove<T>(item));
        return this;
    }

    public Catalogue<T> Nothing()
    {
        _catalogueEvents.Add(new Nothing<T>());
        return this;
    }

    public IEnumerator<CatalogueEvent<T>> GetEnumerator() =>
        _catalogueEvents.GetEnumerator();

    IEnumerator IEnumerable.GetEnumerator() =>
        GetEnumerator();
}

Reduce performs exactly that mapping. map targets a monoid, aggregation uses the earlier article's Sum extension, and narrowing the monoid to a group gives every Remove event the inverse of its object.

var stringsCatalogue = new Catalogue<string>()
    .Add("abc")
    .Nothing()
    .Remove("c")
    .Remove("a")
    .Add("ed");

IntAddGroup.cs

private struct IntAddGroup : IGroup<int>
{
    public int Plus(int left, int right) => left + right;

    public int Zero => 0;

    public int Inverse(int item) => -item;
}

For example, obtain the resulting string length:

stringsCatalogue.Reduce<int, IntAddGroup>(s => s.Length); // 3

The catalog may not feel strongly motivated yet, but the mechanism clearly works. What if we want to reconstruct the resulting string? Concatenation gives strings a monoid, but there is no obvious string subtraction. We can imagine:

"abc" - "c" == "ab"

But what should "abc" - "d", "" - "", or "" - "xyz" mean? The question has no answer under those rules, but there is still a way forward.

We might model a string as an IEnumerable<char> and generalize from sets to collections. Union makes sets only a commutative monoid. Symmetric difference gives an Abelian group, but not the behavior we want.

Track inclusions and exclusions separately instead: represent a set as a pair of sets, with elements to include on the left and elements to exclude on the right.

PairedHashSet.cs

public record PairedSet<T>(HashSet<T> First, HashSet<T> Second)
{
    public PairedSet() : this(new(), new())
    {
    }

    public PairedHashSet(IEnumerable<T> single) : this(new(single), new())
    {
    }
}

public static class PairedSetExtensions
{
    public static HashSet<T> ToHashSet<T>(this PairedSet<T> pairedSet)
    {
        var (first, second) = pairedSet;
        return first.Except(second);
    }
}

public static class HashSetExtensions
{
    public static HashSet<T> Except<T>(this HashSet<T> first, HashSet<T> second)
    {
        var result = new HashSet<T>(first);
        result.ExceptWith(second);
        return result;
    }

    public static HashSet<T> Union<T>(this HashSet<T> first, HashSet<T> second)
    {
        var result = new HashSet<T>(first);
        result.UnionWith(second);
        return result;
    }
}

public struct PairedHashSetGroup<T> : IGroup<PairedHashSet<T>>
{
    public PairedHashSet<T> Plus(PairedHashSet<T> left, PairedHashSet<T> right)
    {
        var (left1, left2) = left;
        var (right1, right2) = right;
        var newLeft = left1.Except(right2).Union(right1.Except(left2));
        var newRight = left2.Except(right1).Union(right2.Except(left1));
        return new PairedHashSet<T>(newLeft, newRight);
    }

    public PairedHashSet<T> Zero => new();

    public PairedHashSet<T> Inverse(PairedHashSet<T> item)
    {
        var (first, second) = item;
        return new PairedHashSet<T>(second, first);
    }
}

The same logic transfers easily to lists, where we can choose whether to remove from the beginning or the end.

PairedList.cs

public record PairedList<T>(List<T> First, List<T> Second)
{
    public PairedList() : this(new(), new())
    {
    }

    public PairedList(IEnumerable<T> single) : this(new(single), new())
    {
    }
}

public static class PairedListExtensions
{
    public static List<T> ToList<T>(this PairedList<T> pairedList)
    {
        var (first, second) = pairedList;
        return first.Except(second);
    }
}

public static class ListExtensions
{
    public static List<T> Union<T>(this List<T> list, List<T> items)
    {
        var result = new List<T>(list);
        result.AddRange(items);
        return result;
    }

    public static List<T> Except<T>(this List<T> first, List<T> second)
    {
        var result = new List<T>(first);
        second.ForEach(item =>
        {
            var li = result.LastIndexOf(item);
            if (li > -1)
            {
                result.RemoveAt(li);
            }
        });
        return result;
    }
}

PairedListGroup.cs

public struct PairedListGroup<T> : IGroup<PairedList<T>>
{
    public PairedList<T> Plus(PairedList<T> left, PairedList<T> right)
    {
        var (left1, left2) = left;
        var (right1, right2) = right;
        var newLeft = left1.Except(right2).Union(right1.Except(left2));
        var newRight = left2.Except(right1).Union(right2.Except(left1));
        return new PairedList<T>(newLeft, newRight);
    }

    public PairedList<T> Zero => new();

    public PairedList<T> Inverse(PairedList<T> item)
    {
        var (first, second) = item;
        return new PairedList<T>(second, first);
    }
}

Returning to the catalog, we can test the result:

var chars = stringsCatalogue.Reduce<PairedList<char>, PairedListGroup<char>>(
    s => new PairedList<char>(s)).ToList();
Console.WriteLine(string.Join("", chars)); // bed

We can also aggregate catalog events into the final collection by mapping every object to a singleton paired list.

// немного расширим список конструкторов
public record PairedList<T>(List<T> First, List<T> Second)
{
    ...
    public PairedList(T item) : this(new List<T> { item })
    {
    }
}

public static class CatalogueExtensions
{
    public static List<T> Collect<T>(this Catalogue<T> catalogue) =>
        catalogue.Reduce<PairedList<T>, PairedListGroup<T>>(
            x => new PairedList<T>(x)
        ).ToList();
}

This even works for an arbitrary DTO:

public record SomeDto(int Number, bool Flag, string Field)
{
}

var someDtosCatalogue = new Catalogue<SomeDto>()
    .Add(new SomeDto(1, false, "asa"))
    .Add(new SomeDto(2, true, "asa"))
    .Remove(new SomeDto(1, false, "asa"));

Get the collection's size:

someDtosCatalogue.Reduce<int, IntAddGroup>(_ => 1)

Or retrieve the collection itself:

var someDtosObjects = someDtosCatalogue.Collect();
someDtosObjects.ForEach(Console.WriteLine);
// SomeDto { Number = 2, Flag = True, Field = asa }

Or inspect the log:

var logs = someDtosCatalogue.ToList();
logs.ForEach(Console.WriteLine);
// Add { Data = SomeDto { Number = 1, Flag = False, Field = asa } }
// Add { Data = SomeDto { Number = 2, Flag = True, Field = asa } }
// Remove { Data = SomeDto { Number = 1, Flag = False, Field = asa } }

We have spent long enough on groups. Time to move on.

Rings in `C#`

The Pythagorean theorem says that a right triangle with sides $a, b, c$ satisfies $a^{2} + b^{2} = c^{2}$ . People have long studied triangles whose sides are integers. Eventually all such triples were described, but generalization continued.

Mathematicians and programmers share a desire to generalize. The formula is a special case of the Diophantine equation $x^{n} + y^{n} = z^{n}$ . In 1637, Pierre de Fermat stated that no integer triples exist for natural $n > 2$ . This historical problem helped set the stage for ring theory.

Early proof attempts handled specific values of $n$ by studying divisibility in sets such as $Z [- n] = a + b - n : a, b \in Z$ . Their elements behaved like integers, creating a need to generalize integer arithmetic. That is how the concept of a ring arose.

A commutative ring is a set $R$ with operations $+$ and $\times$ such that:

$(R, +)$ is an Abelian group.
$(R, \times)$ is a commutative monoid.
$\times$ distributes over $+$ on both sides: $\forall a, b, c \in R : (a + b) \times c = a \times c + b \times c$ .

public interface IRing<T> : IGroup<T>
{
    T One { get; }

    T Times(T left, T right);
}

The remaining examples are more toy-like, but no less interesting. Rings generalize integer arithmetic and are useful when multiplication needs to be generalized. Let us therefore use non-numeric structures.

A homomorphism is a mapping between two structures that preserves their operation. For structures $(G, \oplus)$ and $(H, \otimes)$ , $ϕ : G \to H$ is a homomorphism if:

\forall x, y \in X ϕ (x \oplus y) = ϕ (x) \otimes ϕ (y)

Homomorphisms are an abstract class of mappings: they may be surjective, injective, endomorphic, and so on. The most important is an isomorphism, a bijection preserving the operation. Two isomorphic structures have the same operational behavior and a one-to-one correspondence, so we can move between them freely.

For example, real numbers under addition $(R, +)$ and positive reals under multiplication $(R +^{*}, *)$ are groups connected by $x \mapsto e^{x}$ . Why study both separately when one can be described _up to isomorphism?

An endomorphism is a homomorphism from a structure to itself. All endomorphisms of $S$ form $E n d (S)$ . If $S$ is an Abelian group, $E n d (S)$ is a ring under pointwise addition and function composition.

public struct End<T, G> : IRing<Func<T, T>>
    where G : struct, IGroup<T>
{
    public Func<T, T> Plus(Func<T, T> left, Func<T, T> right) =>
        x => default(G).Plus(left(x), right(x));

    public Func<T, T> Zero => _ => default(G).Zero;

    public Func<T, T> Inverse(Func<T, T> item) =>
        x => default(G).Inverse(x);

    public Func<T, T> One => x => x;

    public Func<T, T> Times(Func<T, T> left, Func<T, T> right) =>
        x => left(right(x));
}

Let us use End<T, G> to build a function producing powers of two. Add a singleton constructor to PairedHashSet<T> and an extension that computes a ring power.

RingExtensions.cs

public static class RingExtensions
{
    public static T Power<T>(this IRing<T> ring, T item, int n)
    {
        var result = item;
        for (var i = 1; i < n; i++)
        {
            result = ring.Times(result, item);
        }
        return result;
    }
}

var end = default(End<PairedHashSet<int>, PairedHashSetGroup<int>>);
var id = end.One;
Func<PairedHashSet<int>, PairedHashSet<int>> x2 =
    s => new(s.ToHashSet().Select(i => i * 2));
var idPlusX2 = end.Plus(id, x2);
var pows = end.Power(idPlusX2, 6)(new(1)); // {1, 2, 4, 8, 16, 32, 64}

Semirings for Graph Algorithms

Like a group, a ring has a "semi" counterpart. A semiring is a triple $(S, +, \times)$ such that:

$(S, +)$ is a commutative monoid.
$(S, \times)$ is a monoid.
Multiplication distributes over addition.
Zero is absorbing: $\forall x \in S x \times 0 = 0 = 0 \times x$ .

public interface ISemiRing<T> : IMonoid<T>
{
    T One { get; }

    T Times(T left, T right);
}

Unlike a ring, a semiring does not require additive inverses; the zero law compensates for the absence of formal subtraction. Examples where it fails are available here.

Semirings have many practical applications. This book, for example, shows mathematically how a broad class of graph problems can be solved uniformly by generalizing matrix multiplication and adapting the incidence matrix.

Treat matrices not as systems of numbers but as systems of arbitrary elements with an algebra. For all $n \times n$ matrices $M_{n} (S)$ over a semiring $(S, \oplus, \otimes)$ , define multiplication as:

c_{ij} = k = 1 ⨁ n a_{ik} \otimes b_{kj}

public class SquareMatrix<T, S> : IEnumerable<SquareMatrix<T, S>.Vector>
    where S : struct, ISemiRing<T>
{
    private readonly int _size;
    private readonly List<Vector> _rows = new();

    public SquareMatrix(int size)
    {
        _size = size;
        for (var i = 0; i < _size; i++)
        {
            _rows.Add(new Vector(
                Enumerable.Repeat(default(S).Zero, _size)
            ));
        }
    }

    public SquareMatrix(int size, params IEnumerable<T>[] rows)
    {
        _size = size;
        _rows.AddRange(rows.Select(x => new Vector(x)));
    }

    public T this[int i, int j]
    {
        get => _rows[i][j];
        set => _rows[i][j] = value;
    }

    public SquareMatrix<T, S> Transpose()
    {
        var columns = Enumerable
            .Range(0, _size)
            .Select(i => _rows.Select(col => col[i]));
        return new(_size, columns.ToArray());
    }

    public SquareMatrix<T, S> Product(SquareMatrix<T, S> that)
    {
        var transposed = that.Transpose();
        var rows = this
            .Select(x => transposed.Select(x.Dot));
        return new(_size, rows.ToArray());
    }

    public SquareMatrix<T, S> Power(int n)
    {
        var result = this;
        for (var i = 1; i < n; i++)
        {
            result = result.Product(this);
        }
        return result;
    }

    public IEnumerator<Vector> GetEnumerator() => _rows.GetEnumerator();

    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();

    public override string ToString() =>
        new StringBuilder()
            .AppendJoin('\n', _rows.Select(row =>
                new StringBuilder()
                    .Append('|')
                    .AppendJoin(", ", row)
                    .Append('|')))
            .ToString();

    public class Vector : IEnumerable<T>
    {
        private readonly List<T> _items;

        public Vector(IEnumerable<T> items)
        {
            _items = new List<T>(items);
        }

        public T this[int index]
        {
            get => _items[index];
            set => _items[index] = value;
        }

        public T Dot(Vector that) => _items
            .Zip(that._items)
            .Select(pair => default(S).Times(pair.First, pair.Second))
            .Sum<T, S>();

        public IEnumerator<T> GetEnumerator() => _items.GetEnumerator();

        IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
    }
}

The semiring $(R \cup + \infty, min, +)$ finds the shortest path from $i$ to $j$ in at most $k$ steps. $(R \cup - \infty, max, +)$ analogously finds the longest path.

MinPlus.cs

public struct MinPlus : ISemiRing<double>
{
    public double Plus(double left, double right) => Min(left, right);

    public double Zero => double.PositiveInfinity;

    public double One => 0;

    public double Times(double left, double right) => left + right;
}

MaxPlus.cs

public struct MaxPlus : ISemiRing<double>
{
    public double Plus(double left, double right) => Max(left, right);

    public double Zero => double.NegativeInfinity;

    public double One => 0;

    public double Times(double left, double right) => left + right;
}

First verify exponentiation over the integer semiring:

SquareMatrix<int, IntSemiRing> testMatrix = new(3,
    new[] { 1, 0, 3 },
    new[] { 0, 5, 0 },
    new[] { 2, 0, 6 });
Console.WriteLine(testMatrix.Power(4));

The result is indeed:

(343010290625068602058)

Now consider this graph:

Generalized matrix multiplication solves both problems by calculating $A_{ij k}$ .

public class WeightedGraph
{
    private readonly int _size;
    private readonly Dictionary<int, List<(int Vertex, double Weight)>> _adjancencyList = new();

    public WeightedGraph(int size, params (int, List<(int Vertex, double Weight)>)[] adjancencyList)
    {
        _size = size;
        adjancencyList.ToList()
            .ForEach(x => _adjancencyList[x.Item1] = x.Item2);
    }

    private SquareMatrix<double, S> GetAdjacencyMatrix<S>()
        where S : struct, ISemiRing<double>
    {
        var adjancencyMatrix = new SquareMatrix<double, S>(_size);
        for (var i = 0; i < _size; i++)
        {
            adjancencyMatrix[i, i] = default(S).One;
        }
        foreach (var key in _adjancencyList.Keys)
        {
            foreach (var (vertex, weight) in _adjancencyList[key])
            {
                adjancencyMatrix[key, vertex] = weight;
            }
        }
        return adjancencyMatrix;
    }

    public double GetShortestPath(int i, int j, int k) =>
        GetAdjacencyMatrix<MinPlus>()
            .Power(k)[i, j];

    public double GetLongestPath(int i, int j, int k) =>
        GetAdjacencyMatrix<MaxPlus>()
            .Power(k)[i, j];
}

The shortest $a \to d$ path in at most three steps costs 8, while the longest in at most two steps costs 13.

var weightedGraph = new WeightedGraph(4,
    (0, new() { (1, 3), (2, 8), (3, 12) }),
    (1, new() { (2, 2), (3, 10) }),
    (2, new() { (3, 3) }));
Console.WriteLine(weightedGraph.GetShortestPath(0, 3, 3)); // 8
Console.WriteLine(weightedGraph.GetLongestPath(0, 3, 2)); // 13

When Groups, Rings, and Semirings Pay Off

Algebraic structures let one implementation operate over several meanings of “addition” and “multiplication.” In this example, changing the semiring changes the graph question while the matrix exponentiation code stays intact.

That reuse is valuable only if the laws hold and the abstraction remains understandable to the team. Test the identities and distributive laws for custom implementations, document what each operation means in the domain, and prefer direct code when there is only one concrete use case.

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

Algebraic code on GitHub

Abstract Algebra in Action: Semigroups and Monoids in C#

StepOne — Tue, 08 Sep 2026 21:19:44 +0000

Many production problems are aggregation problems in disguise: merge partial results, combine filters, reduce collections, or compute values in parallel. Abstract algebra gives those operations precise names and laws, which makes it easier to design reusable code and reason about whether regrouping or parallel execution is safe.

This article introduces semigroups and monoids through C# examples. The point is not to decorate ordinary code with mathematical vocabulary; it is to make composition rules explicit enough that the compiler and your teammates can see them.

Many of us studied at technical universities and took a long list of mathematics courses while wondering why we needed them. Algebra may have been one of those courses. I do not mean a school textbook packed with tedious exercises about polynomials and equations. Abstract algebra is a difficult, expansive subject with a steep learning curve, but it is also fascinating. Its central objects of study are algebraic structures, which you can build almost anywhere and from almost anything. They can also inspire new approaches to writing code. Before we get there, let us take a short algebraic detour.

Semigroups, Monoids, and Their Laws

We will barely scratch the surface of abstract algebra. We will cover only the basic axioms and definitions needed to understand what is going on. There will not even be any theorems or proofs.

Let us begin with an arbitrary set $X$ , assuming familiarity with sets and mappings. If we take a mapping $\circ : X \times X \to X$ together with our set, we get an algebraic structure. In other words, an algebraic structure is a pair $(X, \circ)$ consisting of a set and a closed binary operation. The integers under addition, $(Z, +)$ , are one example.

This is where the operations become important: they determine the structure and behavior of the elements. Arbitrary functions are not useful enough, so we require them to have certain properties. Put differently, the operation must satisfy a set of axioms. We will add them one at a time.

Associativity is a natural first constraint. A binary operation $\circ$ on a set $X$ is associative if the following holds:

(a \circ b) \circ c = a \circ (b \circ c)

Once this axiom holds, $(X, \circ)$ is a semigroup. Why are semigroups useful? Associativity means that grouping does not affect the result of the operation, so semigroup elements can be "combined" in parallel. We would also like to be able to ignore some elements. That takes us to the next level of structure.

An element $e \in X$ is called an identity element if the following holds:

\exists e \in X : \forall x \in X e \circ x = x \circ e = x

Our semigroup $(X, \circ)$ with identity $e$ is now a monoid. The two equalities in the axiom are not redundant: left and right identities also exist, but that is a different story.

Which monoids do we already know? Once again, the integers: $(Z, +, 0)$ , $(Z, *, 1)$ . But enough about numbers.

Implementing Monoids in C

Which monoids can we build in real code?

$(St r in g, +, "")$ — strings under concatenation;
$(L i s t, C o n c a t (),)$ — lists under list concatenation;
$(I n t 32, ma x, - 2^{31} + 1)$ — integers using maximum instead of addition;
$(B oo l e an, ∣∣, f a l se)$ ;

And so on. First, let us express what we learned in code.

public interface ISemiGroup<T>
{
    T Plus(T left, T right);
}

public interface IMonoid<T> : ISemiGroup<T>
{
    T Zero { get; }
}

Update: As @Googolplex correctly noted, these interfaces are type classes. That comment made me rethink and improve the code in the article. The idea remains the same, but the implementation is slightly better. Instead of classes, we can implement these interfaces with structs. This reduces the cost of calling their functions and lets us use ad hoc polymorphism.

I deliberately called the operation "plus" and the identity element "zero." Spoiler: algebra has structures with two operations, such as rings, where "addition" must be distinguished from "multiplication." That distinction is not important here, though. Let us implement a maximum monoid.

public struct Max<T> : IMonoid<T> where T : IComparable<T>, new()
{
    public T Zero => new();

    public T Plus(T left, T right) =>
        left.CompareTo(right) > 0
            ? left
            : right;
}

Now we need some DTO to use with it.

public record Person(string Name, int Money) : IComparable<Person>
{
    public Person() : this("", int.MinValue)
    {
    }

    public int CompareTo(Person other) => Money.CompareTo(other.Money);
}

This leads to an important point. I am not going to take just two people and find the richer one. I need to process many people. I have a list.

var people = new List<Person>
{
    new("Bob", 1000),
    new("Tim", 1239),
    new("Jeff", 2000000000)
};

In other words, we can use these structures for different kinds of aggregation. With monoids, we could even write an extension like this:

public static class EnumerableExtensions
{
    public static T Sum<T, M>(this IEnumerable<T> collection, M monoid = default)
        where M : struct, IMonoid<T> =>
        collection.Aggregate(monoid.Zero, monoid.Plus);
}

What to do next is obvious:

var richest = people.Sum<Person, Max<Person>>();

Magic! Primitive magic, perhaps—for now. What other common aggregation do we have? The average. It turns out that calculating an average can be parallelized. This is not immediately obvious, but consider what an average consists of: a count and a sum. We need to track those two values separately. That gives us a structure analogous to $(Z^{2}, +, (0, 0))$ . Let us put that idea into code.

public class AveragedValue
{
    private double _sum;
    private int _count;

    public AveragedValue() : this(0, 0)
    {
    }

    public AveragedValue(double sum, int count = 1)
    {
        _sum = sum;
        _count = count;
    }

    public double Get() => _sum == 0
        ? 0
        : _sum / _count;

    public static AveragedValue operator +(AveragedValue av1, AveragedValue av2)
    {
        var newCount = av1._count + av2._count;
        var newSum = av1._sum + av2._sum;
        return new AveragedValue(newSum, newCount);
    }
}

public struct Avg : IMonoid<AveragedValue>
{
    public AveragedValue Plus(AveragedValue left, AveragedValue right) => left + right;

    public AveragedValue Zero => new();
}

That is better, but I would still like a real problem. One came to mind. I once needed to build a text filter for a table field, but there were so many conditions that the result looked ugly:

public bool Fits(string text) =>
    text ... ||
    text ... ||
    text ... ||
    ...;

What if the customer wants a different filter for another field, or a more flexible filter? I do not want to duplicate this tangle of conditionals, so let us look at the problem differently. A filter is a predicate: a Boolean function, or more formally, a mapping from a given type to the set of truth values. If we "add" predicates using logical OR, we get a monoid.

public struct Any<T> : IMonoid<Predicate<T>>
{
    public Predicate<T> Zero => _ => false;

    public Predicate<T> Plus(Predicate<T> left, Predicate<T> right) =>
        x => left(x) || right(x);
}

We can then compose the predicates without hard-coding each condition:

var predicates = new List<Predicate<char>>
{
    x => x >= '0' && x <= '9',
    x => x >= 'A' && x <= 'Z',
    x => x >= 'a' && x <= 'z'
};
var digitOrLetter = predicates.Sum<Predicate<char>, Any<char>>();

We can build a more interesting monoid over dictionaries and a merge operation. Let us require the dictionary values to form at least a semigroup, because conflicts will be resolved by adding the elements. The result looks like this:

public struct MapMonoid<K, V, S> : IMonoid<Dictionary<K, V>>
    where S : struct, ISemiGroup<V>
{
    public Dictionary<K, V> Zero => new();

    public Dictionary<K, V> Plus(Dictionary<K, V> left, Dictionary<K, V> right)
    {
        var valueSemiGroup = default(S);
        var result = Zero;
        foreach (var (key, value) in left.Concat(right))
        {
            result[key] = result.ContainsKey(key)
                ? valueSemiGroup.Plus(result[key], value)
                : value;
        }
        return result;
    }
}

How can we use it? Suppose we have a list of strings.

var strings = new List<string> { "foo", "foo", "foo", "bar", "bar", "baz", "pipi", "pupu" };

We can group the strings by occurrence count, find words of the same length, or implement any other idea you have.

var dicts = strings
    .Select(x => new Dictionary<string, int> { { x, 1 } });
var anotherDicts = strings
    .Select(x => new Dictionary<int, List<string>>
    {
        { x.Length, new List<string> { x } }
    });

Now add them using the appropriate semigroups: numbers under addition and lists under concatenation.

private struct IntSemiGroup : ISemiGroup<int>
{
    public int Plus(int left, int right) => left + right;
}

private struct ListSemiGroup<T> : ISemiGroup<List<T>>
{
    public List<T> Plus(List<T> left, List<T> right)
    {
        var result = new List<T>(left);
        result.AddRange(right);
        return result;
    }
}

var map = dicts
    .Sum<Dictionary<string, int>, MapMonoid<string, int, IntSemiGroup>>();
var anotherMap = anotherDicts
    .Sum<Dictionary<int, List<string>>, MapMonoid<int, List<string>, ListSemiGroup<string>>>();

This produces the following output:

When Algebraic Abstractions Help C# Code

Algebraic abstractions earn their place when the laws give you something concrete: safe regrouping, parallel aggregation, reusable composition, or clearer tests. If a named structure only makes familiar code harder to read, keep the direct implementation.

The practical takeaway is to look for associative operations and identity values in recurring aggregation code. Once those properties are explicit, a single generic reduction can replace several unrelated-looking loops without hiding their behavior.

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

Algebraic code on GitHub

Ad-Hoc Polymorphism and the Type Class Pattern in C#

StepOne — Tue, 08 Sep 2026 20:14:40 +0000

Subtype polymorphism is not the only way to make an algorithm work across types. Sometimes you cannot change the types, do not want wrapper allocations, or need behavior selected by a generic constraint rather than a runtime hierarchy.

This article explains ad hoc polymorphism, the problems it solves, and how to model the type class pattern in C#. The technique is useful for reusable libraries and generic algorithms, but it adds generic complexity, so the tradeoff must be visible at the call site.

Ad Hoc, Subtype, and Parametric Polymorphism

We will distinguish three kinds of polymorphism:

Parametric polymorphism.
Ad hoc polymorphism.
Subtype polymorphism.

Let us begin with parametric polymorphism. Suppose we have a list of elements. It could be a list of integers, floating-point numbers, strings, or anything else. Now imagine a GetHead() method that returns the first element of the list. It does not care whether the returned element is an int, string, Apple, or Orange. Its return type is the formal type parameter represented by T in IList<T>, and its implementation is the same for every type: "return the first element."

interface IList<T>
{
    T GetHead();
}

Unlike parametric polymorphism, ad hoc polymorphism depends on the type. The type determines which of several implementations is called. Method overloading is one example. You can have two versions of a method that joins one value to another: one accepts two integers and adds them, while the other accepts two strings and concatenates them. You know that 2 + 3 = 5, but "2" + "3" = "23".

class Appender
{
    public int AppendItems(int a, int b) =>
        a + b;

    public string AppendItems(string a, string b) =>
        $"{a}{b}";
}

With subtype polymorphism, derived classes provide different implementations of a method from a base class. Ad hoc polymorphism decides which implementation to call at compile time—early binding—whereas subtype polymorphism makes that decision at runtime—late binding.

abstract class Animal
{
    public abstract int GetMeatMass();
}

class Cow : Animal
{
    public override int GetMeatMass() => 20;
}

class Dog : Animal
{
    public override int GetMeatMass() => 5;
}

Now let us examine ad hoc polymorphism more closely and leave the other two kinds for another time. As noted above, method overloading is one way to achieve it: each version accepts different parameters, and the call selects the appropriate implementation from their types. But imagine a different scenario. We want only one method, which we can call AppendItems(), that accepts two "appendable" values. With integers, it should combine them through arithmetic addition. With strings, it should combine them through concatenation. We could define behavior for many other types, but int and string are enough for this example.

The brute-force solution is to write an overload for every data type, but we would rather make the compiler help us without creating hundreds of methods.

class Appender
{
    public int AppendItems(int a, int b) =>
        a + b;

    public string AppendItems(string a, string b) =>
        $"{a}{b}";

    public bool AppendItems(bool a, bool b) =>
        a || b;
}

The C# Problem: Combining Unrelated Types

We need AppendItems() to accept two instances of something "appendable" and combine them. The combine operation must also have different implementations for different appendable objects: addition for integers and concatenation for strings. This is a perfect example of ad hoc polymorphism.

Notice that the method must have only one implementation—no overloading or overriding. How can it perform different operations for different types? The idea is that AppendItems() should not know how the append operation is implemented. It should simply invoke it. Here is the method:

class Appender
{
    T AppendItems<T>(T a, T b) => a.Append(b);
}

This is the difficult part: we need to obtain an append operation for integers and strings. How? From the perspective of AppendItems(), they will not be integers or strings. They will be something "appendable." In essence, this is behavioral duck typing: if it walks like a duck and quacks like a duck, we treat it as a duck. We do not care what it is; we care only that it can quack. Here, instead of requiring values to quack, we require them to append.

The method above will not compile because the generic type T has no Append() method. What can we do? I will explain two approaches: wrapper types and the type class pattern.

Wrapper Types as an Adapter

To convince the compiler that T is appendable, we can use a wrapper-type approach built from familiar C# mechanisms. Then we can implement AppendItems() much like the version shown above.

class Appender
{
    public T AppendItems<T>(AppendableValue<T> a, AppendableValue<T> b) =>
        a.Append(b);
}

This method says, "I take two AppendableValue<T> elements and append them." The compiler replies, "Fine. I will let you call Append() on an AppendableValue<T> because you promised that it would have such a method, and I am holding you to that promise." If the method does not exist at compile time, the compiler will be unhappy, to put it mildly, and compilation will fail.

Now that we have AppendItems(), let us move on to AppendableValue<T>.

First, AppendableValue<T> will be an abstract class. An abstract class is convenient for implementing a wrapper type when you need to pass parameters to a base-class constructor, inherit it in C# code, and so on.

Second, AppendableValue<T> will be parameterized: it has a formal type parameter. Why? Because its Append() operation—not to be confused with our AppendItems() method—is generic. It will be implemented differently for different types: addition for integers and concatenation for strings. Because Append() depends on the type, the entire abstract class depends on the type. If it did not, this would be parametric polymorphism. Because it does, this is ad hoc polymorphism.

Here is our small wrapper type, implemented as an abstract class:

abstract class AppendableValue<T>
{
    public T Value { get; }

    protected AppendableValue(T value) =>
        Value = value;

    public abstract T Append(AppendableValue<T> item);
}

Now that the wrapper type is defined, let us write two implementations: one for int and one for string.

class AppendableIntValue :
    AppendableValue<int>
{
    public AppendableIntValue(int value) :
        base(value)
    {
    }

    public override int Append(AppendableValue<int> item) =>
        Value + item.Value;
}

class AppendableStringValue :
    AppendableValue<string>
{
    public AppendableStringValue(string value) :
        base(value)
    {
    }

    public override string Append(AppendableValue<string> item) =>
        $"{Value}{item.Value}";
}

The string interpolation is only for demonstration. I could simply—and more conventionally—write Value + item.Value, which would combine them just as well. I deliberately wanted AppendableStringValue to look different from AppendableIntValue to emphasize that the implementation is type-specific.

That was not difficult, was it? We can now pass ordinary wrapper instances to AppendItems(), and the code type-checks. Here is everything in use:

var appender = new Appender();
Console.WriteLine(
    appender.AppendItems(
        new AppendableIntValue(1),
        new AppendableIntValue(2)));
Console.WriteLine(
    appender.AppendItems(
        new AppendableStringValue("1"),
        new AppendableStringValue("2")));

Implementing the Type Class Pattern in C

Wrapper classes were fun, but type classes are even more interesting. They are more flexible and therefore more powerful. Do not take my word for it—read on and see for yourself.

The type class concept originated in Haskell. Given what we know so far, the simplest explanation is this: rather than wrapping values in AppendableIntValue and AppendableStringValue to perform an operation, separate types provide the operation for those values. In essence, this separates data from operations.

That means we need to change AppendItems() slightly. It still accepts two elements to combine, but instead of a wrapper type, it now needs the type class for the appendable type. The closest C# description would be the following impossible code:

class Appender
{
    public T AppendItems<IAppendable<T>>(T a, T b) =>
        IAppendable.Append(a, b);
}

Unlike Haskell, C# has no built-in type class construct, so we have to model it—much as we model monads. The usual approach is to define a type-class interface and implement it for different concrete type parameters. Here are a few lines of code that demonstrate the concept:

interface IAppendable<T>
{
    T Append(T a, T b);
}

struct AppendableInt : IAppendable<int>
{
    public int Append(int a, int b) =>
        a + b;
}

struct AppendableString : IAppendable<string>
{
    public string Append(string a, string b) =>
        $"{a}{b}";
}

There it is: an IAppendable<T> interface and two implementations, AppendableInt and AppendableString.

One powerful property of type classes is that they make it easy to extend libraries without access to their source code. To support types other than int and string, you only need to provide new implementations. You can also provide alternative implementations for existing types—for example, appending integers by multiplication instead of addition.

struct AppendableIntMultiplicative : IAppendable<int>
{
    public int Append(int a, int b) =>
        a * b;
}

The next question is how to modify AppendItems() to use IAppendable<T>. You may have noticed that every interface implementation is a struct, declared with struct. In a generic context, this lets us create instances with the default operator and zero allocation cost. Creating an instance of the appendable type class costs nothing. The tradeoff is that we need two formal type parameters.

class Appender
{
    public T AppendItems<TAppendable, T>(T a, T b)
        where TAppendable : struct, IAppendable<T> =>
        default(TAppendable).Append(a, b);
}

Here is how to use it:

Console.WriteLine(appender.AppendItems<AppendableInt, int>(1, 2));
Console.WriteLine(appender.AppendItems<AppendableString, string>("1", "2"));

When to Use Type Classes in C

C# expresses ad hoc polymorphism through method overloading. The supplied type determines which method implementation is selected, so the compiler helps us through early binding. If we want it to keep helping while using a single generic contract instead of many overloads, we can reach for the powerful type class pattern from functional programming. In C#, it is implemented by separating operations from data.

P.S.

In addition to this article, there is a proposal in the dotnet repository and the language-ext library, both of which contain more interesting examples:

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.

How to Consume Rate-Limited APIs in .NET

StepOne — Fri, 04 Sep 2026 21:39:35 +0000

An outbound integration can be perfectly healthy and still fail under load because your client exceeds the provider's request quota. Retrying every 429 Too Many Requests response often makes the burst worse; the client needs admission control before the request leaves the process.

This article compares SemaphoreSlim, System.Threading.RateLimiting, and Polly resilience pipelines for rate-limited HttpClient calls. The focus is not only on staying below a requests-per-second limit, but also on configuration, dependency injection, rejection behavior, retries, and unit-testability.

Client-Side Rate Limiting vs. Throttling

The general term for deliberately restricting the rate of work is throttling. In this scenario, the client admits outbound requests according to a policy that reflects the provider's quota.

Throttling is not the same as retrying. A limiter controls when new work may start; a retry policy decides what to do after an attempt fails. Production integrations often need both, configured so retries also consume permits instead of bypassing the quota.

Action games often require players to press buttons rapidly to perform actions such as shooting or striking. Players usually press them much more often than necessary, perhaps because they get caught up in the action. A player may press the attack button 10 times in five seconds, while the character can attack no more than once per second. Throttling the attack event lets the game ignore repeated presses during that second.

How do we implement a similar limit?

Rate-Limiting Algorithms in .NET

Several algorithms implement rate limiting by controlling how much traffic an object admits.

Many rate-limiting algorithms can control a flow of requests. .NET 7 introduced four of them.

Concurrency Limit

A concurrency limiter restricts the number of simultaneous requests that can access a resource. If the limit is 10, then 10 requests can access the resource at once and the 11th is rejected. When one request finishes, one permit becomes available; when two finish, two become available, and so on. This happens when Dispose is called on the RateLimitLease instance, which we will discuss later.

Token Bucket Limit

The token bucket algorithm takes its name from how it works. Imagine a bucket filled to the brim with tokens. An incoming request takes a token and keeps it forever. At intervals, someone adds a predefined number of tokens to the bucket, never exceeding its capacity. If the bucket is empty, an incoming request is denied access to the resource.

Here is a concrete example. Suppose the bucket can hold 10 tokens, and 2 tokens are added every minute. The first request takes 1 token, leaving 9. Three more requests take 3 tokens, leaving 6. A minute later, 2 new tokens arrive, bringing the total to 8. Eight requests consume the remaining tokens and empty the bucket. Any request after that cannot access the resource until more tokens are available. In this example, tokens are replenished every minute. After five minutes without requests, the bucket contains all 10 tokens again, and no more are added until new requests begin consuming them.

Fixed Window Limit

The fixed window algorithm uses the concept of a window, which also appears in the next algorithm. A window is the period during which a limit applies before the algorithm moves to the next window. With a fixed window, moving to the next one resets the limit to its initial state.

Imagine a movie theater with one 100-seat auditorium showing a two-hour film. When the film begins, people may queue for the next showing two hours later. Up to 100 people can join the queue before newcomers are told to return later. After two hours, the film ends and anywhere from 0 to 100 people can enter the auditorium, allowing a new queue to form. That is equivalent to moving the window in the fixed-window algorithm.

Sliding Window Limit

The sliding window algorithm resembles the fixed window algorithm but divides the window into segments. A segment is one part of the window. If we split the two-hour window from the previous section into four segments, we get four 30-minute segments. The algorithm also tracks the current segment index, which always points to the newest segment in the window. Requests during a 30-minute period enter the current segment, and every 30 minutes the window advances by one segment. If the segment that slides out of the window contained requests, those requests expire and the available limit increases by that amount. If it contained none, the limit remains unchanged.

Three Ways to Rate-Limit HttpClient Calls

Approach	Best fit in this article
`SemaphoreSlim`	A simple concurrency cap with minimal dependencies
`System.Threading.RateLimiting`	An explicit, configurable rate-limiting algorithm
Polly resilience pipeline	Rate limiting composed with retries, telemetry, and other resilience policies

That is enough theory for now. The manager is still waiting for the integration, so we need to start writing code as soon as possible.

This is what the manager looks like, by the way:

Suppose we have a DataObject that contains some Content.

We can retrieve a DataObject by calling an IDataObjectExternalApiService, where an HttpClient instance sends the request under the hood:

record DataObject(string Content);

interface IDataObjectExternalApiService
{
    Task<DataObject> GetByIdAsync(int id, CancellationToken ct = default);
}

We have thousands of identifiers and need to download the corresponding content for each one:

interface IDataObjectCollectionProvider
{
    Task<IReadOnlyCollection<DataObject>> GetByIdsAsync(
        IReadOnlyCollection<int> ids,
        CancellationToken ct = default);
}

There is one problem: the external API allows no more than 10 RPS.

SemaphoreSlim

If the requirement means no more than 10 simultaneous requests, we can try to implement a concurrency limiter with the SemaphoreSlim synchronization primitive.

SemaphoreSlim is a lightweight alternative to Semaphore that limits the number of threads that can access a resource or pool of resources at the same time. It also works with async/await.

The result looks roughly like this:

class DataObjectCollectionProvider : IDataObjectCollectionProvider
{
    private readonly IDataObjectExternalApiService _externalApiService;

    public DataObjectCollectionProvider(IDataObjectExternalApiService externalApiService) =>
        _externalApiService = externalApiService;

    public async Task<IReadOnlyCollection<DataObject>> GetByIdsAsync(
        IReadOnlyCollection<int> ids,
        CancellationToken ct = default)
    {
        if (ids.Count == 0)
            return [];

        var semaphoreSlim = new SemaphoreSlim(
            initialCount: 10,
            maxCount: 10);

        ConcurrentBag<DataObject> dataObjects = [];

        var tasks = ids.Select(async id =>
        {
            await semaphoreSlim.WaitAsync(ct);

            try
            {
                var dataObject = await _externalApiService.GetByIdAsync(id, ct);
                dataObjects.Add(dataObject);
            }
            finally
            {
                semaphoreSlim.Release();
            }
        });

        await Task.WhenAll(tasks);

        return dataObjects;
    }
}

In my view, this looks fairly ad hoc. We have to embed the synchronization primitive in the invocation and iteration logic, mixing infrastructure code with business logic.

What happens if we need a different algorithm?

System.Threading.RateLimiting

As mentioned above, .NET 7 introduced the System.Threading.RateLimiting NuGet package, which implements the algorithms discussed in this article.

They all derive from the abstract RateLimiter class:

public abstract class RateLimiter : IAsyncDisposable, IDisposable
{
    public abstract int GetAvailablePermits();

    public abstract TimeSpan? IdleDuration { get; }

    public RateLimitLease Acquire(int permitCount = 1);

    public ValueTask<RateLimitLease> WaitAsync(
        int permitCount = 1,
        CancellationToken cancellationToken = default);

    public void Dispose();

    public ValueTask DisposeAsync();
}

Each derived class accepts dedicated configuration options that control the algorithm's behavior.

We now have a choice. In my opinion, a fixed window is the most intuitive solution to this problem.

We can rewrite the code like this:

class DataObjectCollectionProvider : IDataObjectCollectionProvider
{
    private readonly IDataObjectExternalApiService _externalApiService;

    public DataObjectCollectionProvider(IDataObjectExternalApiService externalApiService) =>
        _externalApiService = externalApiService;

    public async Task<IReadOnlyCollection<DataObject>> GetByIdsAsync(
        IReadOnlyCollection<int> ids,
        CancellationToken ct = default)
    {
        if (ids.Count == 0)
            return [];

        var limiter = new FixedWindowRateLimiter(
            new FixedWindowRateLimiterOptions
            {
                Window = TimeSpan.FromSeconds(1),
                PermitLimit = 10,
                QueueLimit = 10
            });

        ConcurrentBag<DataObject> dataObjects = [];

        var tasks = ids.Select(async id =>
        {
            using var lease = await limiter.AcquireAsync(cancellationToken: ct);

            if (lease.IsAcquired)
            {
                var dataObject = await _externalApiService.GetByIdAsync(id, ct);
                dataObjects.Add(dataObject);
            }
        });

        await Task.WhenAll(tasks);

        return dataObjects;
    }
}

This is better: the algorithm is replaceable, and the options can be injected through DI.

Notice that the limiter uses PermitLimit = 10 and QueueLimit = 10. This means no more than 10 requests enter a one-second window, while queued WaitAsync calls may request at most 10 permits in total.

But what happens if a request cannot obtain a permit and the limiter rejects it? How should we build the error-handling logic—and keep it unit-testable?

Polly.RateLimiting

This is where Polly helps. It wraps System.Threading.RateLimiting in the Polly.RateLimiting package.

The tool changed significantly when it introduced pipelines. A pipeline wraps the call you need to make after you attach all the necessary bells and whistles. See this documentation section for details.

Rate limiters can be added as pipeline stages, and the pipeline itself can be passed through DI to a particular consumer.

Injection uses a dedicated provider that retrieves the pipeline by key. For simplicity, I will use the consumer type name as the key.

We can decorate the external service and execute its call through the pipeline:

class DataObjectServiceRateLimiterDecorator : IDataObjectExternalApiService
{
    private readonly IDataObjectExternalApiService _decorated;
    private readonly ResiliencePipeline<DataObject> _pipeline;

    public DataObjectServiceRateLimiterDecorator(
        IDataObjectExternalApiService decorated,
        ResiliencePipelineProvider<string> pipelineProvider)
    {
        _decorated = decorated;
        _pipeline = pipelineProvider.GetPipeline<DataObject>(
            key: nameof(DataObjectServiceRateLimiterDecorator));
    }

    public async Task<DataObject> GetByIdAsync(int id, CancellationToken ct = default) =>
        await _pipeline.ExecuteAsync(async token => await _decorated.GetByIdAsync(id, token), ct);
}

class DataObjectCollectionProvider : IDataObjectCollectionProvider
{
    private readonly IDataObjectExternalApiService _externalApiService;

    public DataObjectCollectionProvider(IDataObjectExternalApiService externalApiService) =>
        _externalApiService = externalApiService;

    public async Task<IReadOnlyCollection<DataObject>> GetByIdsAsync(
        IReadOnlyCollection<int> ids,
        CancellationToken ct = default)
    {
        if (ids.Count == 0)
            return [];

        var tasks = ids.Select(id => _externalApiService.GetByIdAsync(id, ct));

        return await Task.WhenAll(tasks);
    }
}

Suppose the RPS value comes from options and we want to configure a retry policy alongside the limiter. The configuration would look roughly like this:

services.AddResiliencePipeline<string, DataObject>(
    nameof(DataObjectServiceRateLimiterDecorator),
    (builder, pollyContext) =>
    {
        var allowedRps = pollyContext.ServiceProvider
            .GetRequiredService<IOptions<IDataObjectApiOptions>>()
            .Value.RequestsPerSecond;

        builder
            .ConfigureTelemetry(NullLoggerFactory.Instance)
            .AddRetry(
                new RetryStrategyOptions<DataObject>
                {
                    Delay = TimeSpan.FromSeconds(1),
                    MaxRetryAttempts = 5
                })
            .AddRateLimiter(
                new FixedWindowRateLimiter(
                    new FixedWindowRateLimiterOptions
                    {
                        Window = TimeSpan.FromSeconds(1),
                        PermitLimit = allowedRps,
                        QueueLimit = allowedRps / 3 + 10,
                    }));
    });

Finally, we can write unit tests that verify pipeline behavior in several situations. For example:

public class DataObjectServiceRateLimiterDecoratorTests
{
    [Theory]
    [InlineData(1)]
    [InlineData(2)]
    [InlineData(3)]
    [InlineData(4)]
    [InlineData(5)]
    public async Task GetByIdAsync_ApiReturnedError_RetryCallHappened(int retryCount)
    {
        // arrange
        var response = new DataObject(Content: Guid.NewGuid().ToString());
        var apiService = new Mock<IDataObjectExternalApiService>();

        var sequentialResult = apiService.SetupSequence(
            x => x.GetByIdAsync(
                It.IsAny<int>(),
                It.IsAny<CancellationToken>()));

        for (var i = 0; i < retryCount - 1; i++)
            sequentialResult = sequentialResult.ThrowsAsync(new Exception());

        sequentialResult.ReturnsAsync(response);

        var pipelineProvider = new Mock<ResiliencePipelineProvider<string>>();
        pipelineProvider
            .Setup(
                x => x.GetPipeline<DataObject>(
                    nameof(DataObjectServiceRateLimiterDecorator)))
            .Returns(
                new ResiliencePipelineBuilder<DataObject>()
                    .AddRetry(
                        new RetryStrategyOptions<DataObject>
                        {
                            MaxRetryAttempts = retryCount,
                            Delay = TimeSpan.FromMilliseconds(1)
                        })
                    .Build());

        var decorator = new DataObjectServiceRateLimiterDecorator(
            apiService.Object, pipelineProvider.Object);

        // act
        var dataObject = await decorator.GetByIdAsync(id: default, ct: default);

        // assert
        dataObject.Should().BeEquivalentTo(response);
        apiService
            .Verify(
                x => x.GetByIdAsync(
                    It.IsAny<int>(),
                    It.IsAny<CancellationToken>()),
                Times.Exactly(retryCount));
    }

    [Theory]
    [InlineData(5, 1)]
    [InlineData(100, 50)]
    [InlineData(60, 60)]
    [InlineData(10, 11)]
    [InlineData(20, 40)]
    [InlineData(30, 100)]
    public async Task GetByIdAsync_IfRpsRateLimitExceeded_ThenExceptionIsThrown(int rps, int amount)
    {
        // arrange
        var apiService = new Mock<IDataObjectExternalApiService>();
        apiService
            .Setup(
                x => x.GetByIdAsync(
                    It.IsAny<int>(),
                    It.IsAny<CancellationToken>()))
            .ReturnsAsync(new DataObject(Content: string.Empty));

        var pipelineProvider = new Mock<ResiliencePipelineProvider<string>>();
        pipelineProvider
            .Setup(
                x => x.GetPipeline<DataObject>(
                    nameof(DataObjectServiceRateLimiterDecorator)))
            .Returns(
                new ResiliencePipelineBuilder<DataObject>()
                    .AddRateLimiter(
                        new FixedWindowRateLimiter(
                            new FixedWindowRateLimiterOptions
                            {
                                PermitLimit = rps,
                                Window = TimeSpan.FromSeconds(1)
                            }))
                    .Build());

        var decorator = new DataObjectServiceRateLimiterDecorator(
            apiService.Object, pipelineProvider.Object);

        // act
        var tasks = Enumerable.Range(0, amount)
            .Select(id => decorator.GetByIdAsync(id, ct: default));

        var ex = await Record.ExceptionAsync(() => Task.WhenAll(tasks));

        // assert
        if (amount > rps)
            ex.Should().BeOfType<RateLimiterRejectedException>();
        else
            ex.Should().BeNull();
    }

    [Fact]
    public async Task GetByIdAsync_HappyPath()
    {
        // arrange
        var apiService = new Mock<IDataObjectExternalApiService>();
        apiService
            .Setup(
                x => x.GetByIdAsync(
                    It.IsAny<int>(),
                    It.IsAny<CancellationToken>()))
            .ReturnsAsync(new DataObject(Content: Guid.NewGuid().ToString()));

        var pipelineProvider = new Mock<ResiliencePipelineProvider<string>>();
        pipelineProvider
            .Setup(
                x => x.GetPipeline<DataObject>(
                    nameof(DataObjectServiceRateLimiterDecorator)))
            .Returns(
                new ResiliencePipelineBuilder<DataObject>()
                    .AddRetry(
                        new RetryStrategyOptions<DataObject>
                        {
                            MaxRetryAttempts = 5,
                            Delay = TimeSpan.FromSeconds(1)
                        })
                    .AddRateLimiter(
                        new FixedWindowRateLimiter(
                            new FixedWindowRateLimiterOptions
                            {
                                PermitLimit = 10,
                                Window = TimeSpan.FromSeconds(1)
                            }))
                    .Build());

        var decorator = new DataObjectServiceRateLimiterDecorator(
            apiService.Object, pipelineProvider.Object);

        // act
        var tasks = Enumerable.Range(0, 100)
            .Select(id => decorator.GetByIdAsync(id, ct: default));

        var result = await Task.WhenAll(tasks);

        // assert
        result.Length.Should().Be(100);
    }
}

Choosing a .NET Rate-Limiting Approach

For a small, local concurrency cap, SemaphoreSlim may be enough. Use System.Threading.RateLimiting when the rate-limiting algorithm itself should be explicit and configurable. Use a Polly pipeline when rate limiting must compose with retries, telemetry, and other resilience policies behind a testable service boundary.

A client-side limiter is still only one part of the contract. Multiple application instances do not share an in-memory quota, and the provider may change limits dynamically. Account for deployment topology, honor server feedback such as Retry-After, and decide explicitly whether excess work should wait, fail fast, or be dropped.

Related .NET Guides

Follow StepOne on GitHub for open-source C#/.NET projects, compiler experiments, production-focused examples, and new releases.