code-corner.dev

.NET 9 — ToList vs ToArray

2024-06-18T23:00:00.000Z

Last year I made an article comparing the performance of ToList versus ToArray when creating short lived collections that won’t be mutated, usually used to prevent multiple enumerations when iterating over a temporary LINQ transformation or to ensure mapping exceptions will be thrown inside the corresponding application layer.

The tests were performed with .NET Framework 4.8, .NET 7 and .NET 8, which concluded that ToArray is significantly faster and more memory efficient for almost all collection sizes, with the only exception with very large collections in .NET 8 were ToList was faster - but still uses more memory).

Assuming everything goes as planed, Microsoft should release .NET 9 by the end of 2024. This is the next major version of their most popular development framework that will bring a lot of new features (C# 13 is one of them) and performance improvements.

Since we already have .NET 9 preview 5 available, which contains an even more optimized SegmentedArrayBuilder that is used internally by ToArray, I think it is a good time to compare the performance of both these methods in .NET 9 while using .NET 8 as the baseline.

Performance Test

Once again, I’m going to use the well known C# library BenchmarkDotNet to run the tests and the environment will be the following:

BenchmarkDotNet v0.13.10, Windows 11 (10.0.22631.3737/23H2/2023Update/SunValley3)
AMD Ryzen 7 3700X, 1 CPU, 16 logical and 8 physical cores
.NET SDK 9.0.100-preview.5.24307.3
  [Host]               : .NET 8.0.6 (8.0.624.26715), X64 RyuJIT AVX2
  .NET 8.0             : .NET 8.0.6 (8.0.624.26715), X64 RyuJIT AVX2
  .NET 9.0             : .NET 9.0.0 (9.0.24.30607), X64 RyuJIT AVX2
  .NET Framework 4.8.1 : .NET Framework 4.8.1 (4.8.9241.0), X64 RyuJIT VectorSize=256

The test consists in the creation of a collection that will hold random integers with a size defined by a test parameter. To ensure the collection initialization doesn’t affect performance, it will be created and cached during test setup, but converted to a new IEnumerable before invoking either ToArray or ToList.

Keep in mind we want to test the performance of iterating over an IEnumerable and create either an array or a list so, to prevent .NET internal optimizations (like using a SelectArrayIterator), the method that converts the cached array to an IEnumerable will use the yield return keyword. This is different than the previous article were I was using the Select method which would return an optimized enumerable for arrays and I want to test the worst case scenario.

[SimpleJob(RuntimeMoniker.Net80, baseline: true)]
[SimpleJob(RuntimeMoniker.Net90)]
[MemoryDiagnoser]
public class ToListVsToArray
{
    [Params(10, 100, 1000, 10000, 100000)]
    public int Size;

    private int[] _items;

    [GlobalSetup]
    public void Setup()
    {
        var random = new Random(123);

        _items = Enumerable.Range(0, Size).Select(_ => random.Next()).ToArray();
    }

    [Benchmark]
    public int[] ToArray() => CreateItemsEnumerable().ToArray();

    [Benchmark]
    public List<int> ToList() => CreateItemsEnumerable().ToList();

    private IEnumerable<int> CreateItemsEnumerable()
    {
        foreach (var item in _items)
            yield return item;
    }
}

Performance results

Since this article is a continuation of my previous one, were I concluded using ToArray is faster and more memory efficient than ToList, let’s compare if that statement still holds true.

| Method  | Size   | Mean          | Error         | StdDev        | Gen0     | Gen1     | Gen2     | Allocated |
|-------- |------- |--------------:|--------------:|--------------:|---------:|---------:|---------:|----------:|
| ToArray | 10     |      70.39 ns |      0.366 ns |      0.342 ns |   0.0134 |        - |        - |     112 B |
| ToList  | 10     |      72.85 ns |      0.744 ns |      0.696 ns |   0.0315 |        - |        - |     264 B |
| ToArray | 100    |     322.65 ns |      1.816 ns |      1.610 ns |   0.0563 |        - |        - |     472 B |
| ToList  | 100    |     368.11 ns |      4.283 ns |      4.006 ns |   0.1469 |        - |        - |    1232 B |
| ToArray | 1000   |   2,451.62 ns |     19.687 ns |     16.439 ns |   0.4845 |        - |        - |    4072 B |
| ToList  | 1000   |   2,854.28 ns |     24.286 ns |     22.717 ns |   1.0109 |   0.0153 |        - |    8472 B |
| ToArray | 10000  |  22,275.27 ns |    163.363 ns |    152.810 ns |   4.7607 |        - |        - |   40072 B |
| ToList  | 10000  |  26,944.65 ns |    293.685 ns |    260.344 ns |  15.6250 |        - |        - |  131448 B |
| ToArray | 100000 | 328,160.90 ns |  1,874.673 ns |  1,753.570 ns | 124.5117 | 124.5117 | 124.5117 |  400156 B |
| ToList  | 100000 | 410,583.73 ns |  2,298.854 ns |  2,037.874 ns | 285.6445 | 285.6445 | 285.6445 | 1049120 B |

Using ToList as the baseline, we can see the ToArray method is, on average, 15% faster and uses 60% less memory.

Keep in mind that ToArray is a better choice than ToList even on larger collections, something that wasn’t true in .NET 8, were it was 4% slower despite using less memory.

The winner: .NET 9.0

.NET performance evolution

Because we also want to compare the performance of .NET 9 over .NET 8, let’s analyze each method individually on each framework and see if anything has changed.

ToArray

| Runtime  | Size   | Mean          | Error         | StdDev        | Ratio | RatioSD | Gen0     | Gen1     | Gen2     | Allocated | Alloc Ratio |
|----------|------- |--------------:|--------------:|--------------:|------:|--------:|---------:|---------:|---------:|----------:|------------:|
| .NET 8.0 | 10     |     107.51 ns |      1.585 ns |      1.238 ns |  1.00 |    0.00 |   0.0315 |        - |        - |     264 B |        1.00 |
| .NET 9.0 | 10     |      70.39 ns |      0.366 ns |      0.342 ns |  0.65 |    0.01 |   0.0134 |        - |        - |     112 B |        0.42 |
| .NET 8.0 | 100    |     442.33 ns |      3.788 ns |      3.543 ns |  1.00 |    0.00 |   0.1431 |        - |        - |    1200 B |        1.00 |
| .NET 9.0 | 100    |     322.65 ns |      1.816 ns |      1.610 ns |  0.73 |    0.01 |   0.0563 |        - |        - |     472 B |        0.39 |
| .NET 8.0 | 1000   |   3,186.13 ns |     31.530 ns |     29.493 ns |  1.00 |    0.00 |   1.0185 |        - |        - |    8544 B |        1.00 |
| .NET 9.0 | 1000   |   2,451.62 ns |     19.687 ns |     16.439 ns |  0.77 |    0.00 |   0.4845 |        - |        - |    4072 B |        0.48 |
| .NET 8.0 | 10000  |  30,659.83 ns |    292.167 ns |    273.293 ns |  1.00 |    0.00 |  12.6343 |        - |        - |  106232 B |        1.00 |
| .NET 9.0 | 10000  |  22,275.27 ns |    163.363 ns |    152.810 ns |  0.73 |    0.00 |   4.7607 |        - |        - |   40072 B |        0.38 |
| .NET 8.0 | 100000 | 482,397.96 ns |  1,499.949 ns |  1,403.053 ns |  1.00 |    0.00 | 249.5117 | 249.5117 | 249.5117 |  925140 B |        1.00 |
| .NET 9.0 | 100000 | 328,160.90 ns |  1,874.673 ns |  1,753.570 ns |  0.68 |    0.00 | 124.5117 | 124.5117 | 124.5117 |  400156 B |        0.43 |

Using .NET 8 as the baseline, we can see the ToArray method is, on average, 30% faster and uses 55% less memory on .NET 9.

The winner: .NET 9.0

ToList

| Runtime  | Size   | Mean          | Error         | StdDev        | Ratio | RatioSD | Gen0     | Gen1     | Gen2     | Allocated | Alloc Ratio |
|----------|------- |--------------:|--------------:|--------------:|------:|--------:|---------:|---------:|---------:|----------:|------------:|
| .NET 8.0 | 10     |      87.44 ns |      1.803 ns |      1.929 ns |  1.00 |    0.00 |   0.0315 |        - |        - |     264 B |        1.00 |
| .NET 9.0 | 10     |      72.85 ns |      0.744 ns |      0.696 ns |  0.84 |    0.02 |   0.0315 |        - |        - |     264 B |        1.00 |
| .NET 8.0 | 100    |     420.90 ns |      3.654 ns |      2.853 ns |  1.00 |    0.00 |   0.1469 |        - |        - |    1232 B |        1.00 |
| .NET 9.0 | 100    |     368.11 ns |      4.283 ns |      4.006 ns |  0.87 |    0.01 |   0.1469 |        - |        - |    1232 B |        1.00 |
| .NET 8.0 | 1000   |   3,448.37 ns |     67.905 ns |     78.199 ns |  1.00 |    0.00 |   1.0109 |   0.0153 |        - |    8472 B |        1.00 |
| .NET 9.0 | 1000   |   2,854.28 ns |     24.286 ns |     22.717 ns |  0.82 |    0.01 |   1.0109 |   0.0153 |        - |    8472 B |        1.00 |
| .NET 8.0 | 10000  |  35,650.35 ns |    707.370 ns |  1,537.764 ns |  1.00 |    0.00 |  15.6250 |        - |        - |  131448 B |        1.00 |
| .NET 9.0 | 10000  |  26,944.65 ns |    293.685 ns |    260.344 ns |  0.77 |    0.05 |  15.6250 |        - |        - |  131448 B |        1.00 |
| .NET 8.0 | 100000 | 462,317.72 ns |  1,686.365 ns |  1,577.427 ns |  1.00 |    0.00 | 285.6445 | 285.6445 | 285.6445 | 1049120 B |        1.00 |
| .NET 9.0 | 100000 | 410,583.73 ns |  2,298.854 ns |  2,037.874 ns |  0.89 |    0.01 | 285.6445 | 285.6445 | 285.6445 | 1049120 B |        1.00 |

Using .NET 8 as the baseline, we can see the ToList method is, on average, 15% faster while having exactly the same memory footprint on .NET 9.

The winner: .NET 9.0

Conclusion

In this article we compared the performance of ToArray versus ToList on .NET 9 and concluded, once again, if you need to create a temporary collection in memory to prevent multiple enumerations of an IEnumerable, using ToArray is more performant in all scenarios independent of collection size, something that wasn’t true in .NET 8.

This is also a clear statement that Microsoft made a good decision to introduce classes and structures dedicated to performance, like ArrayPool or ReadOnlySpan, making it easier to share or reuse resources without constantly (de)allocating memory. This has been specially important for our performance tests since SegmentedArrayBuilder makes heavy use of these functionalities, now more than ever.

.NET — IAsyncEnumerable utility extensions

2024-05-24T23:00:00.000Z

With the introduction of async streams in .NET Core 3, represented by the interface IAsyncEnumerable<T>, and with a direct support in C# 8 to iterate using await foreach or easily implement a new asynchronous stream by defining async IAsyncEnumerable<T> as the method result and using yield return/yield break just like we did for IEnumerable<T>, Microsoft standardized the way .NET developers implement asynchronous streams.

Even if we don’t realize, we probably use async streams on a daily basis, from Entity Framework Core to ASP.NET Core, it has become an important part of .NET that is now widely adopted.
In this article I’m going to show some the most common scenarios I usually face when working directly with IAsyncEnumerable<T> and how I usually solve them.

Utility extensions for async streams

When implementing an extension for an async stream there are a few guidelines to keep in mind.

Firstly, don’t validate function inputs (like null checks) inside the async method, but create a wrapper method instead that validates and then calls an internal implementation. This will keep the stack trace more clean, easy to analyze and lightweight.

Secondly, your code will surely need a CancellationToken but don’t define it in the public method signature even if it has a default value. To make developers life easier, instead of passing a CancellationToken to every method, Microsoft provides the extension method WithCancellation that can be used on any IAsyncEnumerable and if you use the attribute EnumeratorCancellation in your methods signature, the compiler will automatically use the cancellation token passed to the WithCancellation method to all your methods. If you define it as a parameter in your public signature it will cause confusion to the developer using it.

Imagine you were creating a simple Where extension to filter an async stream, to follow the guidelines it would be implemented as follows:

public static IAsyncEnumerable<T> Where<T>(
    this IAsyncEnumerable<T> source,
    Func<T, bool> predicate
)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentNullException.ThrowIfNull(predicate);

    return Core(source, predicate);

    static async IAsyncEnumerable<T> Core(
        IAsyncEnumerable<T> source,
        Func<T, bool> predicate,
        [EnumeratorCancellation] CancellationToken ct = default
    )
    {
        await foreach (var item in source.WithCancellation(ct))
        {
            if (predicate(item))
                yield return item;
        }
    }
}

As you can see, the validations are done outside the actual implementation just like the CancellationToken is only defined internally.

I recommend giving a good look to the source code of System.Linq.Async, the officially supported LINQ extensions for async streams.

Let’s now drill down to some of my most used utility extensions.

Timeout between fetches

When receiving data from an IAsyncEnumerable we may not know how many items and how long in total it is going to take, but we may want to enforce a maximum timeout between receiving each item to ensure the application doesn’t wait indefinitely.

One very common scenario nowadays is the integration with Large Language Models (LLMs) APIs that use Server-Sent Events (SSE) to stream response tokens to be shown to the user in real time. Even with a loading somewhere, if some token response takes too long the user will probably think the application just stopped working.

The following code will link a CancellationTokenSource to the original CancellationToken and use it’s internal timer to automatically cancel after a given time as passed, throwing a TaskCanceledException when waiting for the next item.

public static IAsyncEnumerable<T> Timeout<T>(
    this IAsyncEnumerable<T> source,
    int millisecondsTimeout
)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentOutOfRangeException.ThrowIfLessThan(millisecondsTimeout, -1);

    return Core(source, millisecondsTimeout);

    static async IAsyncEnumerable<T> Core(
        IAsyncEnumerable<T> source,
        int millisecondsTimeout,
        [EnumeratorCancellation] CancellationToken ct = default
    )
    {
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
        cts.CancelAfter(millisecondsTimeout);

        await foreach (var element in source.WithCancellation(ct))
        {
            // disable the timer while the item is being processed
            cts.CancelAfter(-1);

            yield return element;

            // re-enable the timer before fetching the next item
            cts.CancelAfter(millisecondsTimeout);
        }
    }
}

I like this approach because it’s simple and, except for an extra allocation of a CancellationTokenSource and it’s internal Timer (which will be reused per item), there’s nothing much to be said making it a very efficient implementation. It can be use just like any LINQ method:

await foreach (var i in GetRandomIntegersAsync(20)
                   .Timeout(500)
                   .WithCancellation(ct))
{
    Console.WriteLine($"{DateTimeOffset.Now:O} -> {i}");
}

If you are like me an prefer to receive a TimeoutException, you can change the implementation by manually iterating over the enumerator instead of using await foreach and if a TaskCanceledException is thrown but the received CancellationToken isn’t cancelled, you can assume it was due to a timeout and throw a TimeoutException instead.

public static IAsyncEnumerable<T> Timeout<T>(
    this IAsyncEnumerable<T> source,
    int millisecondsTimeout
)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentOutOfRangeException.ThrowIfLessThan(millisecondsTimeout, -1);

    return Core(source, millisecondsTimeout);

    static async IAsyncEnumerable<T> Core(
        IAsyncEnumerable<T> source,
        int millisecondsTimeout,
        [EnumeratorCancellation] CancellationToken ct = default
    )
    {
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
        cts.CancelAfter(millisecondsTimeout);

        await using var enumerator = source.GetAsyncEnumerator(cts.Token);

        while (await MoveNextCheckTimeoutAsync(enumerator, ct))
        {
            cts.CancelAfter(-1);

            yield return enumerator.Current;

            cts.CancelAfter(millisecondsTimeout);
        }
    }

    static async ValueTask<bool> MoveNextCheckTimeoutAsync(
        IAsyncEnumerator<T> enumerator,
        CancellationToken ct
    )
    {
        try
        {
            return await enumerator.MoveNextAsync();
        }
        catch (TaskCanceledException e) when (!ct.IsCancellationRequested)
        {
            throw new TimeoutException("The next item took longer than expected to be received", e);
        }
    }
}

Batch with maximum waiting time

When receiving data from an IAsyncEnumerable to be persisted is some database, to reduce and optimize the insertion it may be a good idea to batch it instead of store item by item.

Imagine you are storing data into some relational table, if you receive 500 items, that’s 500 database accesses which may affect the performance of your overall application. If instead you create batches of 10 items it will mean 50 database accesses with more time in between, certainly reducing the overall database load.

If we use MoreLINQ Batch method as an example, we can easily convert it to an IAsyncEnumerable implementation.

public static IAsyncEnumerable<T[]> Batch<T>(
    this IAsyncEnumerable<T> source,
    int size
)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(size);

    return Core(source, size);

    static async IAsyncEnumerable<T[]> Core(
        IAsyncEnumerable<T> source,
        int size,
        [EnumeratorCancellation] CancellationToken ct = default
    )
    {
        T[] batch = null;
        var count = 0;
        await foreach (var item in source.WithCancellation(ct))
        {
            batch ??= new T[size];
            batch[count++] = item;

            if (count != size)
                continue;

            yield return batch;
            batch = null;
        }

        if (count > 0)
        {
            Array.Resize(ref batch, count);
            yield return batch;
        }
    }
}

Another common scenario when batching items is to support a timeout parameter that will either return a complete batch or, after a given time has passed, it will return whatever items have already been received.

This can be easily implemented by calculating the a timeout date and check if it has passed every time a item is received. If the given amount of time has passed, you simply resize the collection to the current size, return that batch and calculate again the next timeout date.

public static IAsyncEnumerable<T[]> Batch<T>(
    this IAsyncEnumerable<T> source,
    int size,
    int millisecondsTimeout
)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(size);
    ArgumentOutOfRangeException.ThrowIfNegative(millisecondsTimeout);

    return Core(source, size, millisecondsTimeout);

    static async IAsyncEnumerable<T[]> Core(
        IAsyncEnumerable<T> source,
        int size,
        int millisecondsTimeout,
        [EnumeratorCancellation] CancellationToken ct = default
    )
    {
        T[] batch = null;
        var count = 0;
        var timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsTimeout);
        await foreach (var item in source.WithCancellation(ct))
        {
            batch ??= new T[size];
            batch[count++] = item;

            if (count != size)
            {
                if (timeoutOn > DateTime.UtcNow) 
                    continue;

                Array.Resize(ref batch, count);
            }

            yield return batch;

            batch = null;
            timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsTimeout);
            count = 0;
        }

        if (count > 0)
        {
            Array.Resize(ref batch, count);
            yield return batch;
        }
    }
}

I like this approach because it is very simple to understand and efficient since it only allocates an extra DateTime over the initial batch method. The only downside is that it only timeouts after an item is received not while waiting. To solve that limitation, the implementation would require a timer and constant allocations of TaskCompletitionSource which, at least for my use cases, it isn’t worth the complexity and performance overload.

Again, this method can easily be used just like other LINQ extensions:

await foreach (var i in GetRandomIntegersAsync(20)
                   .Batch(5, 1000)
                   .Where(e => e.Length > 0)
                   .WithCancellation(ct))
{
    Console.WriteLine($"{DateTimeOffset.Now:O} -> {i.Length}");
}

Throttling

One last scenario I usually face is to apply some throttling to prevent overloading the application in case of a high throughput of items received from IAsyncEnumerable. It usually combines very well with the timeout Batch method to enforce a predictive cadence of data.

The implementation is very simple: you calculate the timeout date, fetch the next item, and if not enough time has passed, you just do a delay for the remaining time and repeat the process per each item.

public static IAsyncEnumerable<T> Throttling<T>(
    this IAsyncEnumerable<T> source,
    int millisecondsDelay
)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentOutOfRangeException.ThrowIfNegative(millisecondsDelay);

    return Core(source, millisecondsDelay);

    static async IAsyncEnumerable<T> Core(
        IAsyncEnumerable<T> source,
        int millisecondsDelay,
        [EnumeratorCancellation] CancellationToken ct = default
    )
    {
        var timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsDelay);
        await foreach (var item in source.WithCancellation(ct))
        {
            if (DateTime.UtcNow < timeoutOn) 
                await Task.Delay(timeoutOn - DateTime.UtcNow, ct);

            yield return item;

            timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsDelay);
        }
    }
}

Once again, use it just like other LINQ extensions:

await foreach (var i in GetRandomIntegersAsync(20)
                   .Throttling(5000)
                   .WithCancellation(ct))
{
    Console.WriteLine($"{DateTimeOffset.Now:O} -> {i}");
}

Conclusion

In this article I’ve shown some of the most common utility methods I use when working with IAsyncEnumerable, allowing to either implement timeouts while waiting for the next item, batching with a maximum wait time or enforcing throttling to prevent application overload.

Feel free to change them in ways that make sense to you, like creating overloads that receive a TimeSpan, or use them as an example for creating your own utility methods.

Here’s the full code sample so you can put it in your own projects.

namespace System.Collections.Generic;

public static class AsyncEnumerableExtensions
{
    public static IAsyncEnumerable<T> Timeout<T>(
        this IAsyncEnumerable<T> source,
        int millisecondsTimeout
    )
    {
        ArgumentNullException.ThrowIfNull(source);
        ArgumentOutOfRangeException.ThrowIfLessThan(millisecondsTimeout, -1);

        return Core(source, millisecondsTimeout);

        static async IAsyncEnumerable<T> Core(
            IAsyncEnumerable<T> source,
            int millisecondsTimeout,
            [EnumeratorCancellation] CancellationToken ct = default
        )
        {
            using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
            cts.CancelAfter(millisecondsTimeout);

            await using var enumerator = source.GetAsyncEnumerator(cts.Token);

            while (await MoveNextCheckTimeoutAsync(enumerator, ct))
            {
                cts.CancelAfter(-1);

                yield return enumerator.Current;

                cts.CancelAfter(millisecondsTimeout);
            }
        }

        static async ValueTask<bool> MoveNextCheckTimeoutAsync(
            IAsyncEnumerator<T> enumerator,
            CancellationToken ct
        )
        {
            try
            {
                return await enumerator.MoveNextAsync();
            }
            catch (TaskCanceledException e) when (!ct.IsCancellationRequested)
            {
                throw new TimeoutException("The next item took longer than expected to be received", e);
            }
        }
    }

    public static IAsyncEnumerable<T[]> Batch<T>(
        this IAsyncEnumerable<T> source,
        int size
    )
    {
        ArgumentNullException.ThrowIfNull(source);
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(size);

        return Core(source, size);

        static async IAsyncEnumerable<T[]> Core(
            IAsyncEnumerable<T> source,
            int size,
            [EnumeratorCancellation] CancellationToken ct = default
        )
        {
            T[] batch = null;
            var count = 0;
            await foreach (var item in source.WithCancellation(ct))
            {
                batch ??= new T[size];
                batch[count++] = item;

                if (count != size)
                    continue;

                yield return batch;
                batch = null;
            }

            if (count > 0)
            {
                Array.Resize(ref batch, count);
                yield return batch;
            }
        }
    }

    public static IAsyncEnumerable<T[]> Batch<T>(
        this IAsyncEnumerable<T> source,
        int size,
        int millisecondsTimeout
    )
    {
        ArgumentNullException.ThrowIfNull(source);
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(size);
        ArgumentOutOfRangeException.ThrowIfNegative(millisecondsTimeout);

        return Core(source, size, millisecondsTimeout);

        static async IAsyncEnumerable<T[]> Core(
            IAsyncEnumerable<T> source,
            int size,
            int millisecondsTimeout,
            [EnumeratorCancellation] CancellationToken ct = default
        )
        {
            T[] batch = null;
            var count = 0;
            var timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsTimeout);
            await foreach (var item in source.WithCancellation(ct))
            {
                batch ??= new T[size];
                batch[count++] = item;

                if (count != size)
                {
                    if (timeoutOn > DateTime.UtcNow) 
                        continue;

                    Array.Resize(ref batch, count);
                }

                yield return batch;

                batch = null;
                timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsTimeout);
                count = 0;
            }

            if (count > 0)
            {
                Array.Resize(ref batch, count);
                yield return batch;
            }
        }
    }

    public static IAsyncEnumerable<T> Throttling<T>(
        this IAsyncEnumerable<T> source,
        int millisecondsDelay
    )
    {
        ArgumentNullException.ThrowIfNull(source);
        ArgumentOutOfRangeException.ThrowIfNegative(millisecondsDelay);

        return Core(source, millisecondsDelay);

        static async IAsyncEnumerable<T> Core(
            IAsyncEnumerable<T> source,
            int millisecondsDelay,
            [EnumeratorCancellation] CancellationToken ct = default
        )
        {
            var timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsDelay);
            await foreach (var item in source.WithCancellation(ct))
            {
                if (DateTime.UtcNow < timeoutOn) 
                    await Task.Delay(timeoutOn - DateTime.UtcNow, ct);

                yield return item;

                timeoutOn = DateTime.UtcNow.AddMilliseconds(millisecondsDelay);
            }
        }
    }
}

.NET 9 — Exception handling performance

2024-04-13T23:00:00.000Z

Assuming everything goes as planed, by the end of 2024 Microsoft should release .NET 9, which is the next major version of their most popular development framework.

It will bring a lot of new features (C# 13 is one of them) but also a lot of performance improvements, which have been a major focus ever since Microsoft created the first version of .NET Core.

Even if an application doesn’t rely on exceptions to hard stop process flows, usually very important for high demanding applications, it certainly connects to a lot of external systems, like databases, message buses, caches and even HTTP endpoints, which may cause exceptions at any moment.

In this article I’m going to test how exception handling performance improved over the years by comparing how faster is .NET 9 over .NET 8.

I’m going to use the well known C# library BenchmarkDotNet to run the tests and the environment will be the following:

BenchmarkDotNet v0.13.12, Windows 11 (10.0.22631.3447/23H2/2023Update/SunValley3)
AMD Ryzen 7 3700X, 1 CPU, 16 logical and 8 physical cores
.NET SDK 9.0.100-preview.3.24204.13
  [Host]               : .NET 8.0.4 (8.0.424.16909), X64 RyuJIT AVX2
  .NET 8.0             : .NET 8.0.4 (8.0.424.16909), X64 RyuJIT AVX2
  .NET 9.0             : .NET 9.0.0 (9.0.24.17209), X64 RyuJIT AVX2
  .NET Framework 4.8.1 : .NET Framework 4.8.1 (4.8.9232.0), X64 RyuJIT VectorSize=256

Performance test

To test the performance of exception handling I’m going to define two simple scenarios:

Ignore exception — the simplest possible scenario to measure the performance of throwing and catching an exception;
Convert to string — the most common scenario when working with logging frameworks which usually use the ToString method to get a text representation containing both the message and stack trace;

Because asynchronous code with async/await has become very common and it directly affects the complexity of stack trace information, I’m also going to test both scenarios asynchronously.

[SimpleJob(RuntimeMoniker.Net481)]
[SimpleJob(RuntimeMoniker.Net80, baseline: true)]
[SimpleJob(RuntimeMoniker.Net90)]
[MemoryDiagnoser]
public class ThrowExceptionPerfTest
{
    [Benchmark]
    public void Catch_Ignore()
    {
        try
        {
            ThrowException();
        }
        catch
        {

        }
    }

    [Benchmark]
    public string Catch_ToString()
    {
        try
        {
            ThrowException();
            return null;
        }
        catch (Exception e)
        {
            return e.ToString();
        }
    }

    private static void ThrowException() => throw new Exception("test exception");

    [Benchmark]
    public async ValueTask Catch_Ignore_Async()
    {
        try
        {
            await ThrowExceptionAsync();
        }
        catch
        {

        }
    }

    [Benchmark]
    public async ValueTask<string> Catch_ToString_Async()
    {
        try
        {
            await ThrowExceptionAsync();
            return null;
        }
        catch (Exception e)
        {
            return e.ToString();
        }
    }

    private static async ValueTask ThrowExceptionAsync()
    {
        await Task.Yield();

        throw new Exception("test exception");
    }
}

Performance results

I’m going to use .NET 8 as the baseline since it is the most recent and performant version currently available, but I’m also including .NET Framework 4.8.1 so we can also compare how .NET in general have improved over the years.

| Method               | Runtime              | Mean      | Error     | StdDev    | Ratio | RatioSD | Gen0   | Gen1   | Allocated | Alloc Ratio |
|--------------------- |--------------------- |----------:|----------:|----------:|------:|--------:|-------:|-------:|----------:|------------:|
| Catch_Ignore         | .NET 8.0             |  6.130 us | 0.0738 us | 0.0654 us |  1.00 |    0.00 | 0.0381 |      - |     344 B |        1.00 |
| Catch_Ignore         | .NET 9.0             |  3.059 us | 0.0219 us | 0.0183 us |  0.50 |    0.01 | 0.0381 |      - |     344 B |        1.00 |
| Catch_Ignore         | .NET Framework 4.8.1 |  7.178 us | 0.0358 us | 0.0299 us |  1.17 |    0.01 | 0.0687 |      - |     433 B |        1.26 |
|                      |                      |           |           |           |       |         |        |        |           |             |
| Catch_ToString       | .NET 8.0             | 11.472 us | 0.0854 us | 0.0798 us |  1.00 |    0.00 | 0.6409 |      - |    5384 B |        1.00 |
| Catch_ToString       | .NET 9.0             |  7.849 us | 0.1512 us | 0.1263 us |  0.68 |    0.01 | 0.6409 |      - |    5384 B |        1.00 |
| Catch_ToString       | .NET Framework 4.8.1 | 14.393 us | 0.1046 us | 0.0874 us |  1.25 |    0.01 | 1.0376 |      - |    6604 B |        1.23 |
|                      |                      |           |           |           |       |         |        |        |           |             |
| Catch_Ignore_Async   | .NET 8.0             | 21.662 us | 0.4302 us | 1.0056 us |  1.00 |    0.00 | 0.1221 |      - |    1248 B |        1.00 |
| Catch_Ignore_Async   | .NET 9.0             | 11.690 us | 0.1647 us | 0.1375 us |  0.54 |    0.03 | 0.1373 |      - |    1243 B |        1.00 |
| Catch_Ignore_Async   | .NET Framework 4.8.1 | 23.139 us | 0.0875 us | 0.0775 us |  1.06 |    0.06 | 0.2441 |      - |    1663 B |        1.33 |
|                      |                      |           |           |           |       |         |        |        |           |             |
| Catch_ToString_Async | .NET 8.0             | 44.680 us | 0.7175 us | 0.5991 us |  1.00 |    0.00 | 1.0986 |      - |   10025 B |        1.00 |
| Catch_ToString_Async | .NET 9.0             | 36.583 us | 0.7125 us | 0.7623 us |  0.82 |    0.02 | 1.0986 |      - |   10105 B |        1.01 |
| Catch_ToString_Async | .NET Framework 4.8.1 | 45.369 us | 0.7617 us | 1.0924 us |  1.01 |    0.02 | 1.8921 | 0.0610 |   11999 B |        1.20 |

Let’s analyze each result individualy.

Catch and ignore

| Runtime              | Mean      | Error     | StdDev    | Ratio | RatioSD |
|--------------------- |----------:|----------:|----------:|------:|--------:|
| .NET 8.0             |  6.130 us | 0.0738 us | 0.0654 us |  1.00 |    0.00 |
| .NET 9.0             |  3.059 us | 0.0219 us | 0.0183 us |  0.50 |    0.01 |
| .NET Framework 4.8.1 |  7.178 us | 0.0358 us | 0.0299 us |  1.17 |    0.01 |

The simplest scenario shows .NET 9 with a 50% performance improvement over .NET 8, which was already 15% faster that .NET Framework 4.8.1.

Who’s the winner? .NET 9

Catch and convert to string

| Runtime              | Mean      | Error     | StdDev    | Ratio | RatioSD |
|--------------------- |----------:|----------:|----------:|------:|--------:|
| .NET 8.0             | 11.472 us | 0.0854 us | 0.0798 us |  1.00 |    0.00 |
| .NET 9.0             |  7.849 us | 0.1512 us | 0.1263 us |  0.68 |    0.01 |
| .NET Framework 4.8.1 | 14.393 us | 0.1046 us | 0.0874 us |  1.25 |    0.01 |

In this scenario, using the ToString method is 32% faster in .NET 9 than .NET 8, and about 45% faster than .NET Framework 4.8.1.

Who’s the winner? .NET 9

Catch and ignore (async)

| Runtime              | Mean      | Error     | StdDev    | Ratio | RatioSD |
|--------------------- |----------:|----------:|----------:|------:|--------:|
| .NET 8.0             | 21.662 us | 0.4302 us | 1.0056 us |  1.00 |    0.00 |
| .NET 9.0             | 11.690 us | 0.1647 us | 0.1375 us |  0.54 |    0.03 |
| .NET Framework 4.8.1 | 23.139 us | 0.0875 us | 0.0775 us |  1.06 |    0.06 |

In the simplest scenario, but with an asynchronous implementation, .NET 9 is 46% faster than .NET 8 and 50% faster than .NET Framework 4.8.1.

Who’s the winner? .NET 9

Catch and convert to string (async)

| Runtime              | Mean      | Error     | StdDev    | Ratio | RatioSD |
|--------------------- |----------:|----------:|----------:|------:|--------:|
| .NET 8.0             | 44.680 us | 0.7175 us | 0.5991 us |  1.00 |    0.00 |
| .NET 9.0             | 36.583 us | 0.7125 us | 0.7623 us |  0.82 |    0.02 |
| .NET Framework 4.8.1 | 45.369 us | 0.7617 us | 1.0924 us |  1.01 |    0.02 |

The catch and use the ToString method asynchronous implementation is 18% faster in .NET 9 than .NET 8 and 20% faster than .NET framework 4.8.1.

Who’s the winner? .NET 9

Conclusion

In this article we compared .NET 9, .NET 8 and .NET Framework 4.8.1 performance when throwing and handling exceptions, for both synchronous and asynchronous code, and concluded the future .NET release will come with significant improvements.

This will certainly be important for high demanding systems that usually integrate with a lot of external systems, like message queues, databases or HTTP endpoints. Even in less complex scenarios it is good to know a simple change from .NET 8 or older versions to .NET 9 will increase the overall performance.

Microsoft has been stepping in the right direction ever since they released .NET Core, and let’s hope they keep going.

.NET — Hangfire

2024-02-29T00:00:00.000Z

One common scenario when developing applications is the need to perform background processing than can either be run only once (like sending an email) or scheduled to be run multiple times within a given interval (like doing database housekeeping), usually defined by a cron expression.

When I need to implement such requirements my first choice for the last few years as always been Hangfire.

It integrates seamlessly with ASP.NET Core applications, it has a simple but very powerful dashboard to monitor and manually trigger recurring jobs and is open source and completely free for commercial use.

In this article I’m going to explain how to configure both Hangfire server and dashboard into an ASP.NET Core application and recurrently send requests to HTTP endpoints, which will be configured based on application settings without requiring a service restart to detect changes.

Why use Hangfire to trigger HTTP endpoints?

An extremely common approach I use when implementing schedulers that may run millions of jobs per day is to use Hangfire to trigger HTTP endpoints, offloading work to external APIs instead of in process.

By design, Hangfire is implemented to be easily distributed on different machines by orchestrating the job execution using a persistent data storage shared across all servers.

The problem comes when some jobs need more processing power than others or millions of executions per day. You’ll have to maintain multiple nodes looking at different queues, code changes must be properly distributed to the relevant nodes, the database will probably become a bottleneck - even if using some message bus or in-memory cache.

To attenuate this problem I usually prefer to keep Hangfire instances as simple as possible, by recurrently doing simple HTTP requests that can be configured either by settings files or database providers (like exemplified in this article I recently made). This allows to offload the heavy work to external APIs that can be more easily scaled, tested, distributed and monitored and ensuring you’ll need much fewer Hangfire instances to run millions of jobs per day while using the dashboard to keep track of job executions.

Solution setup

In this example, which I have available on GitHub, I’m going to setup an ASP.NET Core application with .NET 8 to host both Hangfire server and dashboard. For simplicity, the job storage will be in-memory but feel free to use any other of the supported ones (like SQL Server).

Start by creating an empty ASP.NET Core project and register the following NuGet packages:

Hangfire.AspNetCore - depends on Hangfire.NetCore, which is used to run the jobs server on Microsoft.Extensions.Hosting as a hosted service, but also brings a Web dashboard that can be used to manually trigger recurring jobs or check execution status;
Hangfire.InMemory - in-memory job storage but you can swap for any other of your preference, like Hangfire.SqlServer;

Open the Program.cs file, register both the server and dashboard services into the dependency injection container and configure the dashboard to listen on base address:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHangfire(config => config
    .UseInMemoryStorage()
);
builder.Services.AddHangfireServer();

var app = builder.Build();

app.MapHangfireDashboard("");

app.Run();

If you run the application, the Hangfire dashboard will be shown with a single server running but without recurring jobs.

As you can see, in just a few minutes you have Hangfire up and ready do run. As stated previously, this is one of the reasons I always use Hangfire for scheduling jobs, the simplicity of it!

HTTP job options

Now that we have both the server and dashboard running, let’s start by defining the recurring HTTP options that we’ll read from the application settings and dynamically configure endpoints to be recurrently triggered.

Let’s start by defining the options for requesting a single endpoint. To keep things simple, I’ll assume the need for an HTTP address, method, headers and a request timeout. It will also need a cron expression, so we can define the recurrency interval, and a flag to enable it so you can manage per environment which jobs are enabled.

public class HttpJobEndpointOptions
{
    public string Cron { get; init; }

    public bool Enabled { get; init; }

    public string Address { get; init; }

    public string Method { get; init; }

    public IReadOnlyDictionary<string, string> Headers { get; init; }

    public TimeSpan? Timeout { get; init; }

    public bool IgnoreInvalidStatusCode { get; init; }
}

We could now load a collection of HttpJobEndpointOptions from the application settings but let’s try to organize the endpoints into categories and also give a name for each. This will be handy later to have a more readable job name when looking at the Hangfire dashboard.

public class HttpJobOptions
{
    public TimeSpan DefaultTimeout { get; init; } = TimeSpan.FromSeconds(5);

    public IReadOnlyDictionary<
        string, 
        IReadOnlyDictionary<string, HttpJobEndpointOptions>
    > Endpoints { get; init; }
}

Open the appsettings.json file and configure an IsAlive job inside a Core category that’ll run every 5 minutes. This job will be used later for testing, so assume an HTTP request GET /api/is-alive to itself:

{
  "HttpJobs": {
    "DefaultTimeout": "00:00:05",
    "Endpoints": {
      "Core": {
        "IsAlive": {
          "Cron": "*/5 * * * *",
          "Enabled": true,
          "Address": "https://localhost:7076/api/is-alive",
          "Method": "GET",
          "Headers": {
            "accept": "application/json"
          },
          "Timeout": null,
          "IgnoreInvalidStatusCode": false
        }
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Open the Program.cs file and configure the HttpJobOptions from the HttpJobs section. Let’s also add the testing endpoint to be triggered later:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHangfire(config => config
    .UseInMemoryStorage()
);
builder.Services.AddHangfireServer();

builder.Services.Configure<HttpJobOptions>(
    builder.Configuration.GetSection("HttpJobs")
);

var app = builder.Build();

app.MapGet("/api/is-alive", () => "I'm alive!");

app.MapHangfireDashboard("");

app.Run();

HTTP job runner

Now that we have defined the job options, let’s create the class that will be recurrently executed by the Hangfire server.

The core idea of this class is to be responsible to do a single HTTP request by receiving both the category and endpoint names as a parameter, looking up for the configuration in the HttpJobOptions instance and doing the expected HTTP request. It will also receive a PerformContext instance which is a special (but optional) class provided by Hangfire to give context to your methods.

public class HttpJobRunner(
    ILogger<HttpJobRunner> logger,
    IOptionsMonitor<HttpJobOptions> options,
    IHttpClientFactory clientFactory
)
{
    private HttpJobOptions Options => options.CurrentValue;

    public async Task RunAsync(string category, string name, PerformContext ctx)
    {
        using var _ = logger.BeginScope(
            "Category:{Category} Name:{Name} JobId:{JobId}",
            category,
            name,
            ctx.BackgroundJob.Id
        );

        if (!Options.Endpoints.TryGetValue(category, out var endpoints))
        {
            logger.LogWarning("Configuration for category not found");
            return;
        }

        if (!endpoints.TryGetValue(name, out var endpoint))
        {
            logger.LogWarning("Configuration for endpoint not found");
            return;
        }

        if (!endpoint.Enabled)
        {
            logger.LogWarning("Endpoint was disabled while still scheduled, nothing will be done");
            return;
        }

        using var client = clientFactory.CreateClient(
            $"{nameof(HttpJobRunner)}.{category}.{name}"
        );

        client.Timeout = endpoint.Timeout ?? Options.DefaultTimeout;

        logger.LogDebug(
            "Starting HTTP request '{Method} {Address}' [Timeout:{Timeout}]",
            endpoint.Method,
            endpoint.Address,
            client.Timeout
        );

        using var request = new HttpRequestMessage(
            new HttpMethod(endpoint.Method),
            endpoint.Address
        );

        if (endpoint.Headers?.Count > 0)
        {
            foreach (var (key, value) in endpoint.Headers)
                request.Headers.Add(key, value);
        }

        var ct = ctx.CancellationToken.ShutdownToken;

        HttpResponseMessage response;
        try
        {
            response = await client.SendAsync(request, ct);
        }
        catch (TaskCanceledException e) when (!ct.IsCancellationRequested)
        {
            throw new TimeoutException("Request timed out", e);
        }

        using (response)
        {
            logger.LogInformation(
                "Completed HTTP request '{Method} {Address}' with status code {StatusCode}",
                endpoint.Method,
                endpoint.Address,
                response.StatusCode
            );

            if (!endpoint.IgnoreInvalidStatusCode)
                response.EnsureSuccessStatusCode();
        }
    }
}

Register into the DI container the HTTP client services (because we are using the IHttpClientFactory) and also this class as transient.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHangfire(config => config
    .UseInMemoryStorage()
);
builder.Services.AddHangfireServer();

builder.Services.Configure<HttpJobOptions>(
    builder.Configuration.GetSection("HttpJobs")
);

builder.Services.AddHttpClient();
builder.Services.AddTransient<HttpJobRunner>();

var app = builder.Build();

app.MapGet("/api/is-alive", () => "I'm alive!");

app.MapHangfireDashboard("");

app.Run();

HTTP hosted service

It is time to let Hangfire know that we have endpoints that must be requested on a recurrent basis.

To configure the class HttpJobRunner as a recurring job, we can use either the static method RecurringJob.AddOrUpdate or the equivalent methods provided by IRecurringJobManager.

A manual registration of the HTTP:Core:IsAlive job we defined in the application settings would be as follows:

// using static class RecurringJob
RecurringJob.AddOrUpdate<HttpJobRunner>(
    "HTTP:Core:IsAlive",
    runner => runner.RunAsync("Core", "IsAlive", null),
    "*/5 * * * *",
    new RecurringJobOptions
    {
        TimeZone = TimeZoneInfo.Utc
    }
);

// using IRecurringJobManager instance
jobManager.AddOrUpdate<HttpJobRunner>(
    "HTTP:Core:IsAlive",
    runner => runner.RunAsync("Core", "IsAlive", null),
    "*/5 * * * *",
    new RecurringJobOptions
    {
        TimeZone = TimeZoneInfo.Utc
    }
);

As you can see, we pass an expression to the AddOrUpdate method that will be used by Hangfire to build dynamic code to call the RunAsync method of our HttpJobRunner class, including the parameters we specify. As stated before, the PerformContext parameter is special and despite we are passing null when defining the expression, Hangfire will actually create a context each time the method is run.

With this simple yet effective approach, Hangfire doesn’t impose any interface or abstract class that must be implemented, making our life much easier.

This registration could be done at application startup but since we want do detect changes to the application settings without restarting the server, let’s create a hosted service that will be running in the background and either add or remove scheduler jobs. As a note, since Hangfire doesn’t provide a way to get currently registered jobs so we can remove inexistent, we’ll register the hosted service as a singleton and have a collection in-memory to track registered job ids.

public class HttpJobHostedService(
    ILogger<HttpJobHostedService> logger,
    IOptionsMonitor<HttpJobOptions> options,
    IRecurringJobManager jobManager
) : IHostedService
{
    private readonly HashSet<string> _jobIds = new();
    private IDisposable _onOptionsChange;

    public Task StartAsync(CancellationToken ct)
    {
        _onOptionsChange = options.OnChange(jobOptions =>
        {
            logger.LogDebug("Configuration changed, scheduling jobs");
            ScheduleJobs(jobOptions);
        });

        logger.LogDebug("Initial configuration, scheduling jobs");
        ScheduleJobs(options.CurrentValue);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken ct)
    {
        _onOptionsChange?.Dispose();

        return Task.CompletedTask;
    }

    private void ScheduleJobs(HttpJobOptions options)
    {
        var currentJobIds = new HashSet<string>();

        if (options.Endpoints is { Count: > 0 })
        {
            foreach (var (category, endpoints) in options.Endpoints)
            {
                if (endpoints is not { Count: > 0 })
                    continue;

                foreach (var (name, endpoint) in endpoints)
                {
                    if (!endpoint.Enabled)
                        continue;

                    var jobId = $"HTTP:{category}:{name}";

                    jobManager.AddOrUpdate<HttpJobRunner>(
                        jobId,
                        runner => runner.RunAsync(category, name, null),
                        endpoint.Cron,
                        new RecurringJobOptions
                        {
                            TimeZone = TimeZoneInfo.Utc
                        }
                    );

                    currentJobIds.Add(jobId);
                }
            }
        }

        _jobIds.RemoveWhere(jobId => currentJobIds.Contains(jobId));

        foreach (var jobId in _jobIds) 
            jobManager.RemoveIfExists(jobId);

        _jobIds.Clear();

        foreach (var jobId in currentJobIds)
            _jobIds.Add(jobId);
    }
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHangfire(config => config
    .UseInMemoryStorage()
);
builder.Services.AddHangfireServer();

builder.Services.Configure<HttpJobOptions>(
    builder.Configuration.GetSection("HttpJobs")
);

builder.Services.AddHttpClient();
builder.Services.AddTransient<HttpJobRunner>();

builder.Services.AddHostedService<HttpJobHostedService>();

var app = builder.Build();

app.MapGet("/api/is-alive", () => "I'm alive!");

app.MapHangfireDashboard("");

app.Run();

If you now run the application, the Hangfire dashboard will show the HTTP:Core:IsAlive recurring job to be run every 5 minutes.

Try to change the application settings while the application is running, like changing the cron expression, disabling, removing or creating jobs, so you can see the recurring job list to change accordingly.

If you wait for the jobs to run (or manually trigger) and go to the Jobs tab, open the Succeeded status and you’ll see the list of all jobs that have run successfully.

If you open one of the jobs, you’ll see details about it’s execution, like the parameters that were passed, the execution time and, if it was failed, the exception details.

Job filters

The code is looking nice and simple and seems to work very well but there’s still three problems that I think should be solved:

If you have multiple HTTP endpoints you can’t tell just looking at the list which one was called without checking execution details. In this case every job is called HttpJobRunner.RunAsync, independently the endpoint;
Since this is a recurring and stateless job so, when it fails, there’s no point in keeping it in the failed state to be retried, we can move it to the deleted stated that would be automatically housekept by Hangfire;
If for some reason a job for a given endpoint takes more time to run than its cron interval, multiple executions will overlap and cause requests to happen concurrently, which may not be the expected behavior;

To solve these problems we are going to use Hangfire filters, which are attributes that can be used to annotate methods (or registered globally) to add custom behavior when running a job, working similarly to ASP.NET Core MVC filters.

We are going to use the JobDisplayName filter to define the job name in the dashboard, the AutomaticRetry filter to mark the job as deleted when failed, and create a custom filter than will lock job executions per endpoint until the previous one has completed.

Starting by the custom filter, we must extend the JobFilterAttribute and because it’s changing the behavior of a job execution, it must also implement the IServerFilter interface. We are going to use both the category and endpoint name parameters to create a unique identifier per endpoint execution and use an Hangfire distributed lock feature to ensure a job for the same endpoint only runs after the lock is disposed by a previous execution.

public class EnableDistributedMutexAttribute : JobFilterAttribute, IServerFilter
{
    private const string Key = nameof(EnableDistributedMutexAttribute);

    private readonly string _nameFormat;
    private readonly TimeSpan _timeout;

    public EnableDistributedMutexAttribute(string nameFormat, int timeoutInSeconds)
    {
        ArgumentNullException.ThrowIfNull(nameFormat);
        ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(timeoutInSeconds, 0);

        _nameFormat = nameFormat;
        _timeout = TimeSpan.FromSeconds(timeoutInSeconds);
    }

    public void OnPerforming(PerformingContext ctx)
    {
        var distributedLockName = string.Format(
            _nameFormat,
            ctx.BackgroundJob.Job.Args.ToArray()
        );

        var distributedLock = ctx.Connection.AcquireDistributedLock(
            distributedLockName,
            _timeout
        );

        ctx.Items[Key] = distributedLock;
    }

    public void OnPerformed(PerformedContext ctx)
    {
        if (!ctx.Items.TryGetValue(Key, out var distributedLock))
            throw new InvalidOperationException("Can not release a distributed lock: it was not acquired.");

        ((IDisposable)distributedLock).Dispose();
    }
}

Open the HttpJobRunner class and annotate the RunAsync method with a JobDisplayName, EnableDistributedMutex and AutomaticRetry attributes.

public class HttpJobRunner(
    ILogger<HttpJobRunner> logger,
    IOptionsMonitor<HttpJobOptions> options,
    IHttpClientFactory clientFactory
)
{
    private HttpJobOptions Options => options.CurrentValue;

    [JobDisplayName("HTTP:{0}:{1}")]
    [EnableDistributedMutex("HTTP:{0}:{1}", 15)]
    [AutomaticRetry(OnAttemptsExceeded = AttemptsExceededAction.Delete, Attempts = 0)]
    public async Task RunAsync(string category, string name, PerformContext ctx)
    {
        // ...
    }
}

If you now run the application and wait or manually trigger the HTTP:Core:IsAlive job you’ll see the new display name in the dashboard.

Feel free to also force some exceptions to see the job in the deleted state instead of failed, or delaying the job execution for more time than the defined cron interval to see jobs waiting for the previous ones to complete.

Conclusion

In this article I explained how easy it is to configure the Hangfire server to run recurring jobs in the background of an ASP.NET Core application, and use its dashboard to manage and monitor job executions.

For simplicity we used the in-memory job storage and created the base architecture for jobs that recurrently trigger HTTP endpoints, everything configured using application settings.

As a reminder, this example is available on GitHub so feel free to give it a look.

.NET — LinkedList vs ToArray

2024-02-05T00:00:00.000Z

Some weeks ago I created an article comparing the performance of ToList versus ToArray when creating short lived collections that won’t be mutated, usually used to prevent multiple enumerations when iterating over a temporary LINQ transformation or to ensure mapping exceptions will be thrown inside the corresponding application layer.

In that article I concluded ToArray is faster and more memory efficient than ToList for almost any collection sizes and in any .NET version — tests were conducted on .NET Framework 4.8, .NET 7 and .NET 8.

But then I began to wonder: If I’m creating a temporary collection of unknown size just to force enumeration, wouldn’t LinkedList be a more efficient collection since I’m only appending items to the end, which is O(1), instead of constantly allocating new arrays like ToArray does?

I believe that’s a valid point so I decided to do a performance comparison between the two, assuming ToArray as the baseline and try to give a detailed explanation for the observed results.

Performance test

The test consists in the creation of a collection that holds random integers, being the size defined by a parameter. To ensure the randomness does not affect the results, the values are cached into an array and, before invoking either ToArray or creating the LinkedList, they are converted into a new IEnumerable, not just a cast that could lead to internal optimizations.

This time I decided to do the performance comparison only on .NET Framework 4.8 and .NET 8.

[SimpleJob(RuntimeMoniker.Net48)]
[SimpleJob(RuntimeMoniker.Net80)]
[MemoryDiagnoser]
public class LinkedListVsToArray
{
    [Params(10, 100, 1000, 10000, 100000)]
    public int Size;

    private int[] _items;

    [GlobalSetup]
    public void Setup()
    {
        var random = new Random(123);

        _items = Enumerable.Range(0, Size).Select(_ => random.Next()).ToArray();
    }

    [Benchmark(Baseline = true)]
    public int[] ToArray()
    {
        var items = CreateItemsEnumerable();
        return items.ToArray();
    }

    [Benchmark]
    public LinkedList<int> ToLinkedList()
    {
        var items = CreateItemsEnumerable();
        return new LinkedList<int>(items);
    }

    private IEnumerable<int> CreateItemsEnumerable()
    {
        foreach (var item in _items)
            yield return item;
    }
}

Performance results

Because we want to decide, for a given application, between ToArray or LinkedList based on performance, let’s analyze the results for each framework version.

.NET Framework 4.8

| Method       | Size   | Mean           | Error        | StdDev       | Median         | Ratio | RatioSD | Gen0     | Gen1     | Gen2     | Allocated | Alloc Ratio |
|------------- |------- |---------------:|-------------:|-------------:|---------------:|------:|--------:|---------:|---------:|---------:|----------:|------------:|
| ToArray      | 10     |       143.4 ns |      2.82 ns |      2.64 ns |       143.5 ns |  1.00 |    0.00 |   0.0470 |        - |        - |     297 B |        1.00 |
| ToLinkedList | 10     |       175.4 ns |      1.57 ns |      1.39 ns |       175.6 ns |  1.23 |    0.02 |   0.0918 |        - |        - |     578 B |        1.95 |
| ToArray      | 100    |       891.6 ns |     17.68 ns |     27.00 ns |       883.8 ns |  1.00 |    0.00 |   0.2584 |        - |        - |    1629 B |        1.00 |
| ToLinkedList | 100    |     1,464.8 ns |     14.96 ns |     13.26 ns |     1,467.8 ns |  1.63 |    0.04 |   0.7801 |   0.0134 |        - |    4910 B |        3.01 |
| ToArray      | 1000   |     7,867.5 ns |    156.18 ns |    223.99 ns |     7,896.2 ns |  1.00 |    0.00 |   1.9836 |   0.0153 |        - |   12504 B |        1.00 |
| ToLinkedList | 1000   |    14,881.8 ns |    283.19 ns |    290.82 ns |    14,892.3 ns |  1.92 |    0.06 |   7.6599 |   1.0834 |        - |   48238 B |        3.86 |
| ToArray      | 10000  |    78,138.5 ns |  1,547.95 ns |  2,363.88 ns |    78,993.1 ns |  1.00 |    0.00 |  26.9775 |   5.3711 |        - |  171755 B |        1.00 |
| ToLinkedList | 10000  |   158,728.7 ns |  2,151.48 ns |  1,907.23 ns |   158,243.9 ns |  2.03 |    0.07 |  76.4160 |  12.4512 |        - |  481511 B |        2.80 |
| ToArray      | 100000 |   805,445.4 ns |  9,463.82 ns |  8,852.47 ns |   804,730.5 ns |  1.00 |    0.00 | 399.4141 | 399.4141 | 399.4141 | 1452144 B |        1.00 |
| ToLinkedList | 100000 | 3,632,195.6 ns | 49,765.42 ns | 46,550.60 ns | 3,633,088.3 ns |  4.51 |    0.08 | 757.8125 | 375.0000 |        - | 4814292 B |        3.32 |

The ToArray method is significantly faster and more memory efficient than creating a new LinkedList. Still, it does allocate more Gen2 memory for larger collections which may be something to consider.

.NET 8

| Method       | Size   | Mean           | Error        | StdDev       | Median         | Ratio | RatioSD | Gen0     | Gen1     | Gen2     | Allocated | Alloc Ratio |
|------------- |------- |---------------:|-------------:|-------------:|---------------:|------:|--------:|---------:|---------:|---------:|----------:|------------:|
| ToArray      | 10     |       108.8 ns |      2.14 ns |      2.99 ns |       109.0 ns |  1.00 |    0.00 |   0.0315 |        - |        - |     264 B |        1.00 |
| ToLinkedList | 10     |       125.7 ns |      2.57 ns |      7.25 ns |       125.9 ns |  1.13 |    0.06 |   0.0677 |        - |        - |     568 B |        2.15 |
| ToArray      | 100    |       433.3 ns |      7.93 ns |      7.03 ns |       434.0 ns |  1.00 |    0.00 |   0.1431 |        - |        - |    1200 B |        1.00 |
| ToLinkedList | 100    |       979.2 ns |     19.54 ns |     40.79 ns |       977.9 ns |  2.34 |    0.09 |   0.5836 |   0.0095 |        - |    4888 B |        4.07 |
| ToArray      | 1000   |     3,100.4 ns |     34.14 ns |     28.51 ns |     3,090.9 ns |  1.00 |    0.00 |   1.0185 |        - |        - |    8544 B |        1.00 |
| ToLinkedList | 1000   |     9,135.9 ns |    179.58 ns |    345.98 ns |     9,205.1 ns |  3.03 |    0.08 |   5.7373 |   0.8850 |        - |   48088 B |        5.63 |
| ToArray      | 10000  |    31,587.6 ns |    604.95 ns |  1,437.72 ns |    31,129.4 ns |  1.00 |    0.00 |  12.6343 |        - |        - |  106232 B |        1.00 |
| ToLinkedList | 10000  |   109,454.7 ns |  2,152.65 ns |  4,198.57 ns |   107,653.8 ns |  3.43 |    0.11 |  57.3730 |  32.9590 |        - |  480088 B |        4.52 |
| ToArray      | 100000 |   531,028.2 ns |  3,515.73 ns |  3,288.62 ns |   531,061.8 ns |  1.00 |    0.00 | 249.0234 | 249.0234 | 249.0234 |  925140 B |        1.00 |
| ToLinkedList | 100000 | 2,295,939.2 ns | 44,598.15 ns | 62,520.38 ns | 2,288,468.0 ns |  4.33 |    0.13 | 570.3125 | 535.1563 |        - | 4800090 B |        5.19 |

Same behavior as .NET Framework 4.8, being the ToArray method much faster and memory efficient while still allocating more Gen2 memory on larger collections.

.NET performance evolution

Since in my previous article I already covered the performance evolution of ToArray over the years, let’s just compare how initializing a LinkedList from an IEnumerable have changed for different frameworks.

| Runtime            | Size   | Mean           | Error        | StdDev       | Median         | RatioSD | Gen0     | Gen1     | Gen2     | Allocated |
|------------------- |------- |---------------:|-------------:|-------------:|---------------:|--------:|---------:|---------:|---------:|----------:|
| .NET 8.0           | 10     |       125.7 ns |      2.57 ns |      7.25 ns |       125.9 ns |    0.06 |   0.0677 |        - |        - |     568 B |
| .NET Framework 4.8 | 10     |       175.4 ns |      1.57 ns |      1.39 ns |       175.6 ns |    0.02 |   0.0918 |        - |        - |     578 B |
| .NET 8.0           | 100    |       979.2 ns |     19.54 ns |     40.79 ns |       977.9 ns |    0.09 |   0.5836 |   0.0095 |        - |    4888 B |
| .NET Framework 4.8 | 100    |     1,464.8 ns |     14.96 ns |     13.26 ns |     1,467.8 ns |    0.04 |   0.7801 |   0.0134 |        - |    4910 B |
| .NET 8.0           | 1000   |     9,135.9 ns |    179.58 ns |    345.98 ns |     9,205.1 ns |    0.08 |   5.7373 |   0.8850 |        - |   48088 B |
| .NET Framework 4.8 | 1000   |    14,881.8 ns |    283.19 ns |    290.82 ns |    14,892.3 ns |    0.06 |   7.6599 |   1.0834 |        - |   48238 B |
| .NET 8.0           | 10000  |   109,454.7 ns |  2,152.65 ns |  4,198.57 ns |   107,653.8 ns |    0.11 |  57.3730 |  32.9590 |        - |  480088 B |
| .NET Framework 4.8 | 10000  |   158,728.7 ns |  2,151.48 ns |  1,907.23 ns |   158,243.9 ns |    0.07 |  76.4160 |  12.4512 |        - |  481511 B |
| .NET 8.0           | 100000 | 2,295,939.2 ns | 44,598.15 ns | 62,520.38 ns | 2,288,468.0 ns |    0.13 | 570.3125 | 535.1563 |        - | 4800090 B |
| .NET Framework 4.8 | 100000 | 3,632,195.6 ns | 49,765.42 ns | 46,550.60 ns | 3,633,088.3 ns |    0.08 | 757.8125 | 375.0000 |        - | 4814292 B |

On average, .NET 8 is 51% faster than .NET Framework 4.8, a clear demonstration how performance has improved over the years.

Analyzing the results

Now that we have the results you are probably questioning why does a LinkedList use more memory and is slower than ToArray? Since we don’t know the collection size, shouldn’t the constant allocation of new arrays and then a final copy to a trimmed one be slower and take more memory?

Using more memory could actually be expectable since a LinkedList, for each item, creates a class that holds a reference for the previous and next node, but why is it slower since adding an item is always a O(1) operation?

Based on personal experience, most developers I questioned about the ToArray implementation assume the following code (I actually believe this Stack Overflow response is to blame):

static T[] ToArray<T>(IEnumerable<T> items)
{
    const int sizeIncrease = 8; // some arbitrary size increase

    var current = new T[sizeIncrease];
    var count = 0;
    
    foreach (var item in items)
    {
        if (count == current.Length)
        {
            var previous = current;
            current = new T[previous.Length + sizeIncrease];
            previous.CopyTo(current, 0);
        }

        current[count++] = item;
    }

    if (count is 0)
        return Array.Empty<T>();

    Array.Resize(ref current, count);
    return current;
}

It assumes the ToArray method behaves similar to a List, creating a bigger one every time the current is full and doing a copy, and in the end it trims the excess.

In reality, the implementation is more similar to this:

static T[] ToArray<T>(IEnumerable<T> items)
{
    const int sizeIncrease = 8; // some arbitrary size increase

    var arrayBuffer = new Queue<T[]>();

    var current = new T[sizeIncrease];
    var count = 0;
    var idx = 0;

    foreach (var item in items)
    {
        if (idx == sizeIncrease)
        {
            arrayBuffer.Enqueue(current);
            current = new T[sizeIncrease];
            idx = 0;
        }

        current[idx++] = item;
        ++count;
    }

    if (count is 0)
        return Array.Empty<T>();

    var currentIdx = idx;

    idx = 0;
    var final = new T[count];
    while (arrayBuffer.Count > 0)
    {
        var previous = arrayBuffer.Dequeue();
        previous.CopyTo(final, idx);
        idx += previous.Length;
    }

    Array.Copy(current, 0, final, idx, currentIdx);

    return final;
}

Instead of creating a bigger array every time it’s full and copying all items, it actually creates a buffer that stores the previously allocated arrays and when the iteration finishes it copies everything in sequence to the final array that has the expected size.

The actual ToArray method implementation as a lot of optimizations, for example, when an ICollection is received they can initialize a new array with the collection size and just call CopyTo. It also doesn’t use a Queue to keep track of previous initialized arrays but instead a simple version of a LinkedList concept.

Give a look to the internal classes EnumerableHelpers and ArrayBuilder for more implementation details.

Conclusion

In this article we compared the performance of initializing a LinkedList versus using ToArray and concluded that, on theory, LinkedList looked like a good fit when creating short lived collections were enumeration must be forced because of its O(1) nature when appending values, but due to internal optimizations of ToArray and since indexing is just faster while using less memory it significantly compensates having to allocate multiple arrays and copying their content.

Keep in mind that LinkedList still has its place, specially when storing collections too big to be stored into a single memory section and it’s nice to see that .NET keeps improving its performance.

.NET — TaskCompletionSource and CancellationTokenSource

2024-01-19T00:00:00.000Z

When Microsoft released .NET Framework 4.0 in April 2010, the Task Parallel Library (TPL) was introduced to help developers replace the previously used Asynchronous Programming Model (APM) pattern for a Task-based asynchronous programming.

Before the introduction of Tasks, when implementing asynchronous code, developers had to define two variations of the same method: one to begin the operation execution (convention: BeginOperationName), that would receive an optional callback to be invoked when completed, and another to wait for the operation to complete (convention: EndOperationName) and get the result or an exception, usually used inside the callback to prevent the main thread to be blocked.

As an example, imagine a repository of cars with an asynchronous method for getting one by a given plate number, implemented using the APM pattern:

public interface ICarRepository
{
    IAsyncResult BeginGetByPlateNumber(
        string plateNumber,
        AsyncCallback callback,
        object state
    );

    Car EndGetByPlateNumber(IAsyncResult ar);
}

// non-blocking usage
carRepository.BeginGetByPlateNumber(plateNumber, ar =>
{
    var car = carRepository.EndGetByPlateNumber(ar);
}, null);

// blocking usage
var ar = carRepository.BeginGetByPlateNumber(plateNumber, null, null);
var car = carRepository.EndGetByPlateNumber(ar);

As you can see, creating two methods per operation is one of the most obvious and annoying disadvantages of the APM pattern, while the other is the need to implement your own wrapper for IAsyncResult so you can trigger the WaitHandle and invoke the callbacks when the operation completes.

Another disadvantage was the cancellation of running operations. If it was supported — and that’s a big if — there wasn’t a standardized pattern for developers to follow. Some would create another method for canceling (i.e. CancelOperationName) that receives an IAsyncResult, others would provide a method directly into the IAsyncResult and either return their own interface or require a cast, and others would simply ignore this feature due to sheer complexity.

Because Microsoft knew asynchronous programming was very important for the future of .NET, it decided to solve these problems by introducing the Task Parallel Library, making it easier for developers to add parallelism and concurrency to applications.

The Task Parallel Library has two central pieces:

The CancellationToken is a structure commonly used in asynchronous methods and enables developers to register a callback that will be invoked if a cancellation is requested. This provides a standardized approach for implementing asynchronous operations that can be canceled mid execution by simply receiving a CancellationToken as a method parameter.
The Task and Task<T> are classes that merge both IAsyncResult and AsyncCallback concepts. Developers can return a Task and the caller would either register a callback with ContinueWith, for a non-blocking approach, or use the method Wait/Result and block the main thread until the Task was completed. This removes the need to have callback parameters and only a single method is needed instead of BeginX/EndX methods.
If we change the previous car repository example from APM pattern to use TPL, it would be much simpler:

public interface ICarRepository
{
    Task<Car> GetByPlateNumberAsync(
        string plateNumber,
        CancellationToken ct
    );
}

// non-blocking usage
carRepository.GetByPlateNumberAsync(
    plateNumber,
    CancellationToken.None
).ContinueWith(t =>
{
    var car = t.Result;
});

// blocking usage
var car = carRepository.GetByPlateNumberAsync(
    plateNumber,
    CancellationToken.None
).Result;

Now that we have an idea about Task, Task<T>, CancellationToken and some of the reasons why Microsoft created the Task Parallel Library, let’s analyze two other important classes that aren’t commonly used but make all of this possible — TaskCompletionSource and CancellationTokenSource.

TaskCompletionSource

The class TaskCompletionSource is used to create a Task and provides methods to mark it as completed in one from three possible states:

RanToCompletion — the methods SetResult or TrySetResult complete the task successfully and, in case of a Task<T>, the result can be retrieved;
Canceled — the methods SetCanceled or TrySetCanceled mark the task as cancelled mid-execution. Waiting or retrieving the result will throw a TaskCanceledException;
Faulted — the methods SetException or TrySetException mark the task as faulted and waiting or retrieving the result will throw the exception.

With this class developers can easily implement Task-based asynchronous programming. On later versions of the .NET Framework it was widely used to convert classes implementing the APM pattern and, with an increase adoption of tasks, developers also started to migrate their own libs.

Let’s imagine the car repository was still implemented using the APM pattern and we wanted to create some extension methods for developers that prefer to use tasks.

public interface ICarRepository
{
    IAsyncResult BeginGetByPlateNumber(
        string plateNumber,
        AsyncCallback callback,
        object state
    );

    Car EndGetByPlateNumber(IAsyncResult ar);
}

public static class CarRepositoryExtensions
{
    public static Task<Car> GetByPlateNumberAsync(
        this ICarRepository repository,
        string plateNumber
    )
    {
        var tcs = new TaskCompletionSource<Car>();

        // use callback for non-blocking approach
        repository.BeginGetByPlateNumber(plateNumber, ar =>
        {
            try
            {
                var car = repository.EndGetByPlateNumber(ar);

                // no exception thrown, mark the task as completed successfully
                tcs.SetResult(car);
            }
            catch (Exception e)
            {
                // exception thrown, mark the task as faulted
                tcs.SetException(e);
            }
        }, null);

        return tcs.Task;
    }
}

As you can see, we just converted BeginX/EndX methods to tasks in just a few lines without blocking the caller thread.

The TaskCompletionSource is also perfect to convert Event-based Asynchronous Pattern (EAP). Imagine you have a class that represents a message queue and it provides two events — OnMessageReceived and OnErrorReceived — and a non-blocking method to send a message.

public interface IMessageQueue
{
    event Action<object, OnMessageReceivedEventArgs> OnMessageReceived;

    event Action<object, OnErrorReceivedEventArgs> OnErrorReceived;

    void Send(Guid correlationId, JObject content);
}

public class OnMessageReceivedEventArgs : EventArgs
{
    public Guid CorrelationId { get; init; }

    public JObject Content { get; init; }
}

public class OnErrorReceivedEventArgs : EventArgs
{
    public Guid CorrelationId { get; init; }

    public Exception Exception { get; init; }
}

Let’s say we wanted to create an extension method that sends a message and, without blocking the current thread, waits for a correlated response or exception to be received.

public static class MessageQueueExtensions
{
    public static async Task<JObject> SendAsync(
        this IMessageQueue queue,
        Guid correlationId,
        JObject content
    )
    {
        var tcs = new TaskCompletionSource<JObject>();

        // register the events before sending the message
        queue.OnMessageReceived += OnMessageReceived;
        queue.OnErrorReceived += OnErrorReceived;
        try
        {
            queue.Send(correlationId, content);

            return await tcs.Task;
        }
        finally
        {
            // ensure events registration is always cleaned up
            queue.OnMessageReceived -= OnMessageReceived;
            queue.OnErrorReceived -= OnErrorReceived;
        }

        void OnMessageReceived(object _, OnMessageReceivedEventArgs args)
        {
            if (args.CorrelationId == correlationId) 
                tcs.TrySetResult(args.Content);
        }

        void OnErrorReceived(object _, OnErrorReceivedEventArgs args)
        {
            if (args.CorrelationId == correlationId) 
                tcs.TrySetException(args.Exception);
        }
    }
}

The approach is very similar to the APM pattern. We do a temporary registration into the relevant events, then invoke the action that can trigger those events and change the task state when callbacks are invoked. Just be sure registrations are properly cleaned up or else a memory leak will happen.

CancellationTokenSource

The class CancellationTokenSource is used to create a CancellationToken that can be manually marked as canceled using the method Cancel or, to support timeout implementations, the CancelAfter methods that will schedule a cancellation after the specified time as passed.

Using the previously defined GetByPlateNumberAsync extension method, let’s change it first to support cancellation using a CancellationToken. Please note that some performance improvements could be made when detecting for cancellation, but this implementation is for simplicity:

public static class CarRepositoryExtensions
{
    public static async Task<Car> GetByPlateNumberAsync(
        this ICarRepository repository,
        string plateNumber,
        CancellationToken ct
    )
    {
        var tcs = new TaskCompletionSource<Car>();

        await using var _ = ct.Register(() =>
        {
            // if the cancellation is triggered we try to cancel the task
            tcs.TrySetCanceled(ct);
        });

        // use callback for non-blocking approach
        repository.BeginGetByPlateNumber(plateNumber, ar =>
        {
            try
            {
                var car = repository.EndGetByPlateNumber(ar);

                // because the task may have been cancelled first we
                // must try to set a result or an exception will be thrown
                tcs.TrySetResult(car);
            }
            catch (Exception e)
            {
                // same, task may have been cancelled first so we try
                // to set an exception and mark it as faulted
                tcs.TrySetException(e);
            }
        }, null);

        return await tcs.Task;
    }
}

Now that GetByPlateNumberAsync supports cancellation, if we wanted to limit the waiting for a response to a maximum of 5 seconds, a CancellationTokenSource could be used:

using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(5));

var ct = cts.Token;

// if this operation takes more than 5 seconds to run
// a TaskCanceledException will be thrown
await carRepository.GetByPlateNumberAsync(plateNumber, ct);

The CancellationTokenSource also supports to be linked to an existing CancellationToken meaning that the underlying token can either be cancelled manually or by the linked token. This is usually useful to implement methods that offer some kind of timeout parameter without the caller having to use a CancellationTokenSource directly.

Let’s change the previously defined SendAsync extension method to support both cancellation using a token or a timeout parameter that will throw a TimeoutException if the waiting time is exceeded:

public static class MessageQueueExtensions
{
    public static async Task<JObject> SendAsync(
        this IMessageQueue queue,
        Guid correlationId,
        JObject content,
        TimeSpan timeout,
        CancellationToken ct
    )
    {
        var tcs = new TaskCompletionSource<JObject>();

        using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
        cts.CancelAfter(timeout);

        await using var _ = cts.Token.Register(() =>
        {
            if (ct.IsCancellationRequested)
            {
                // if ct was cancelled we want to throw a TaskCanceledException
                tcs.TrySetCanceled(ct);
                return;
            }

            // if ct wasn't cancelled but the cts token was triggered
            // it can only mean the timeout parameter was exceeded
            tcs.TrySetException(new TimeoutException(
                $"The queue took more than '{timeout}' to return a message"
            ));
        });

        queue.OnMessageReceived += OnMessageReceived;
        queue.OnErrorReceived += OnErrorReceived;
        try
        {
            queue.Send(correlationId, content);

            return await tcs.Task;
        }
        finally
        {
            queue.OnMessageReceived -= OnMessageReceived;
            queue.OnErrorReceived -= OnErrorReceived;
        }

        void OnMessageReceived(object _, OnMessageReceivedEventArgs args)
        {
            if (args.CorrelationId == correlationId) 
                tcs.TrySetResult(args.Content);
        }

        void OnErrorReceived(object _, OnErrorReceivedEventArgs args)
        {
            if (args.CorrelationId == correlationId) 
                tcs.TrySetException(args.Exception);
        }
    }
}

In this case, we now use the method CreateLinkedTokenSource to ensure the CancellationTokenSource token will be cancelled if the ct parameter is cancelled or if a given timeout has passed. Because we are listening for the linked cts token, inside the callback we must check if the ct parameter was the cause of cancellation so we can either mark the task as canceled or faulted with a TimeoutException.

Conclusion

In this article I explained some of the reasons why Microsoft decided to replace the Asynchronous Programming Model (APM) pattern for the Task-based Asynchronous Programming, which is possible by using classes from the Task Parallel Library (TPL).

I also demonstrated how the classes TaskCompletionSource and CancellationTokenSource could be used to convert any asynchronous implementation to tasks, even if based on Event-based Asynchronous Pattern (EAP), ensuring threads won’t be blocked waiting for responses and even supporting the cancellation of running operations.

Dispose pattern in .NET

2024-01-08T00:00:00.000Z

When working with .NET, you’ll often hear about the garbage collector and how it manages the allocation and release the application’s memory from the managed heap, making our life easier.

This is true for the majority of objects but sometimes we have to work with unmanaged resources — files, network or database connections — that we must explicitly release since the garbage collector doesn’t know how to do the cleanup for us, despite being able to track the object that encapsulates the unmanaged resource.

To help preventing memory leaks, .NET provides a simple and standard way to cleanup unmanaged resources called dispose pattern, which consists in implementing the IDisposable interface and calling Dispose method when resources aren’t needed, which is usually done via the using keyword.

using (var file = File.OpenText(filePath))
{
    var fileContent = file.ReadToEnd();
}

// equivalent code
var file = File.OpenText(filePath)
try
{
    var fileContent = file.ReadToEnd();
}
finally
{
    file.Dispose();
}

When .NET Core 3.0 was released, Microsoft introduced the interface IAsyncDisposable to allow for asynchronous cleanup operations by calling the DisposeAsync method, usually done with await using keywords.

await using (var x = new SomeAsyncDisposableClass())
{
    // do stuff
}

// equivalent code
var x = new SomeAsyncDisposableClass();
try
{
    // do stuff
}
finally
{
    await x.DisposeAsync();
}

If a class implements IAsyncDisposable it’s usually a good practice to also implement IDisposable despite not being a requirement. Not all code runs asynchronously, so this ensures the class is ready for both scenarios.

In this article I’m going to demonstrate and explain step by step how to properly implement the dispose pattern using both IDisposable and IAsyncDisposable interfaces.

Example scenario

To use as an example, we are going to implement a class that wraps SQL Server connections and uses Dapper to simplify mappings and every time someone queries the database it will write the SQL instruction to the log. This provides a simple example of a class that holds both managed and unmanaged resources that can also be disposed asynchronously — SQL Server network connection.

The class without any disposable implementations:

public class SqlServerQueryRunner
{
    private ILogger<SqlServerQueryRunner> _logger;
    private SqlConnection _connection;

    public SqlServerQueryRunner(
        ILogger<SqlServerQueryRunner> logger,
        string connectionString
    )
    {
        ArgumentNullException.ThrowIfNull(logger);
        ArgumentNullException.ThrowIfNull(connectionString);

        _logger = logger;
        _connection = new SqlConnection(connectionString);
    }

    public async ValueTask<IEnumerable<T>> QueryAsync<T>(CancellationToken ct, string sql, object parameters = null)
    {
        _logger.LogDebug("Querying database: {Sql}", sql);

        // using Dapper for simplicity
        return await _connection.QueryAsync<T>(new CommandDefinition(
            sql,
            parameters,
            cancellationToken: ct
        ));
    }
}

As you can see, this class receives a connection string and creates a SQL Server connection. Because this class is the owner of the SqlConnection instance, it must dispose it or else resources won’t be released.

IDisposable interface

Implement the IDisposable interface by disposing unmanaged resources inside the Dispose method, in this case the SQL Server connection:

public class SqlServerQueryRunner : IDisposable
{
    private ILogger<SqlServerQueryRunner> _logger;
    private SqlConnection _connection;

    // ...

    public void Dispose()
    {
        _connection.Dispose();
    }

    // ...
}

This code looks good and will work as expected, but there are some scenarios to consider:

Will the class be sealed? If not, we must provide a way for extenders to cleanup their unmanaged resources, if any;
Do I want to a safeguard from forgetting to dispose? If yes, we must implement a class finalizer that will try to cleanup resources when garbage collected;

Both scenarios are solved by creating a virtual Dispose method, to be overridden by extenders, that receives a flag to indicate if it’s being called from a dispose or finalizer.

This usually means resources are explicitly disposed only when disposing, otherwise references are cleared and we assume unmanaged resources also have finalizers.

public class SqlServerQueryRunner : IDisposable
{
    private ILogger<SqlServerQueryRunner> _logger;
    private SqlConnection _connection;

    // ...

    ~SqlServerQueryRunner() => Dispose(false);

    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (disposing)
            _connection?.Dispose();

        _connection = null;
        _logger = null;
    }

    // ...
}

You now may be asking: But if we have finalizers that will be triggered when the class is garbage collected, why implement IDisposable?

That’s a fair question with a simple answer: You want garbage collection to be as fast as possible because it is a synchronous operation that stops all processes while it’s running.

This also means unmanaged resources wouldn’t be released until garbage collection happened, which may take some time — imagine a reference to a file that you didn’t need but the process would still be locking it, now you want to open it again but can’t, because the garbage collector haven’t run yet.

If you look at the Dispose method, you’ll realize there’s a call to GC.SuppressFinalize, which is a method that actually tells the garbage collector: look, this class has a finalizer but you can ignore it because it is irrelevant, the developer already released resources using the dispose pattern.

IAsyncDisposable interface

Implementing the IAsyncDisposable interface is very similar to IDisposable with a small difference, we call Dispose(false) inside the method DisposeAsync to keep functional equivalence with the synchronous dispose pattern and further ensuring that finalizer code paths are still invoked. There’s no need to dispose resources synchronously if they were already disposed asynchronously.

public class SqlServerQueryRunner : IDisposable, IAsyncDisposable
{
    private ILogger<SqlServerQueryRunner> _logger;
    private SqlConnection _connection;

    // ...
    public async ValueTask DisposeAsync()
    {
        await DisposeAsyncCore().ConfigureAwait(false);

        Dispose(false);
        GC.SuppressFinalize(this);
    }

    protected virtual async ValueTask DisposeAsyncCore()
    {
        if(_connection is not null)
            await _connection.DisposeAsync().ConfigureAwait(false);
    }

    // ...
}

As a small note, if the class was sealed, the method DisposeAsyncCore wouldn’t be needed and all code could be inside the DisposeAsync method.

ObjectDisposedException

When implementing a disposable class it’s also a good practice to throw an ObjectDisposedException when it’s been disposed but some code is still trying to use it.

This usually is as simple as creating a flag to be set by the Dispose(bool) method and checking for it on all methods that may apply.

public class SqlServerQueryRunner : IDisposable, IAsyncDisposable
{
    private ILogger<SqlServerQueryRunner> _logger;
    private SqlConnection _connection;
    private bool _disposed;

    // ...

    protected virtual void Dispose(bool disposing)
    {
        if(_disposed)
            return;

        if (disposing)
            _connection?.Dispose();

        _connection = null;
        _logger = null;

        _disposed = true;
    }

    // ...

    public async ValueTask<IEnumerable<T>> QueryAsync<T>(CancellationToken ct, string sql, object parameters = null)
    {
        ObjectDisposedException.ThrowIf(_disposed, this);

        _logger.LogDebug("Querying database: {Sql}", sql);

        // using Dapper for simplicity
        return await _connection.QueryAsync<T>(new CommandDefinition(
            sql,
            parameters,
            cancellationToken: ct
        ));
    }
}

Conclusion

In this article I explained the dispose pattern in .NET, which is used to cleanup and release unmanaged resources from memory, either synchronously by implementing the IDisposable interface, or asynchronously with IAsyncDisposable.

For the example we used a simple wrapper for SqlConnection that holds references to both unmanaged and managed resources, making sure both were properly cleared and an ObjectDisposedException was thrown if the class was used after being disposed.

public class SqlServerQueryRunner : IDisposable, IAsyncDisposable
{
    private ILogger<SqlServerQueryRunner> _logger;
    private SqlConnection _connection;
    private bool _disposed;

    public SqlServerQueryRunner(
        ILogger<SqlServerQueryRunner> logger,
        string connectionString
    )
    {
        ArgumentNullException.ThrowIfNull(logger);
        ArgumentNullException.ThrowIfNull(connectionString);

        _logger = logger;
        _connection = new SqlConnection(connectionString);
    }

    #region IDisposable

    ~SqlServerQueryRunner() => Dispose(false);

    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if(_disposed)
            return;

        if (disposing)
            _connection?.Dispose();

        _connection = null;
        _logger = null;

        _disposed = true;
    }

    #endregion

    #region IAsyncDisposable

    public async ValueTask DisposeAsync()
    {
        await DisposeAsyncCore().ConfigureAwait(false);

        Dispose(false);
        GC.SuppressFinalize(this);
    }

    protected virtual async ValueTask DisposeAsyncCore()
    {
        if (_disposed)
            return;

        if (_connection is not null)
            await _connection.DisposeAsync().ConfigureAwait(false);
    }

    #endregion

    public async ValueTask<IEnumerable<T>> QueryAsync<T>(CancellationToken ct, string sql, object parameters = null)
    {
        ObjectDisposedException.ThrowIf(_disposed, this);

        _logger.LogDebug("Querying database: {Sql}", sql);

        // using Dapper for simplicity
        return await _connection.QueryAsync<T>(new CommandDefinition(
            sql,
            parameters,
            cancellationToken: ct
        ));
    }
}

Syntax sugar we don’t even think about in C#

2023-12-28T00:00:00.000Z

When I finished my university degree, back in November 2010 (yes, I’m getting old), Microsoft wasn’t as open as it is today, but because they had a lot of education protocols we had access to a lot of their development tools for free — Visual Studio, SQL Server, Team Foundation Server, just to name a few.

Because of this, C# was actually the language used to teach Object-Oriented Programming (OOP), design patterns and even deeper runtime concepts like garbage collection (an ode to the amazing book “CLR via C#” from Jeffrey Richter — I learned so much).

At the time, we also used a lot of Java, C, C++, LISP, and even Assembly, but C# earned a place in my heart.

Every time I had to create something from scratch that could be run on Windows, C# and .NET Framework was always my first choice. I’m not sure if it was the language or how good Visual Studio was as an IDE compared to Eclipse or NetBeans, but I always found C# to be the most productive programming language I ever used.

And this was between 2006 and 2010, a period were Microsoft released C# versions 3.0 and 4.0 which, in my opinion, completely overthrown their direct competition — Java.

We had auto-implemented properties, extension methods, LINQ, implicit typed variables, anonymous types, query and lambda expressions, just to name a few.

This changes aimed to keep developers focused in implementing business requirements instead of writing boilerplate code. Some may disagree, but for me it was the start of a new era in terms of programming productivity.

If we look back, C# as come a long way, introducing new features every version and I think we can all agree C# 11.0 is an extremely mature and powerful language, suitable both for enterprise or simple applications.

Everyone now knows how much I love everything about C# — almost :) — and since we are starting a new year, I’m feeling nostalgic and I think it is a good time to show how far we’ve come and how much syntax sugar we use nowadays without thinking how much time it really saves us.

Auto-Properties (with initializers)

Ever since C# 1.0 we have properties, which behave like fields from a class or struct, but they are a special case of methods that can implement custom logic, not just get or set the field value.

If we were to create a class Car in C# 1.0 to hold some information like brand, model, license plate and even the number of doors, with a default of 4, it would look like this:

public class Car
{
    private string _brand;
    private string _model;
    private string _licensePlate;
    private int _doors = 4;

    public string Brand
    {
        get
        {
            return _brand;
        }
        set
        {
            _brand = value;
        }
    }

    public string Model
    {
        get
        {
            return _model;
        }
        set
        {
            _model = value;
        }
    }

    public string LicensePlate
    {
        get
        {
            return _licensePlate;
        }
        set
        {
            _licensePlate = value;
        }
    }

    public int Doors
    {
        get
        {
            return _doors;
        }
        set
        {
            _doors = value;
        }
    }
}

With the introduction of auto-properties in C# 3.0 and initializers in C# 6.0, we can make the code much more compact and readable.

public class Car
{
    public string Brand { get; set; }

    public string Model { get; set; }

    public string LicensePlate { get; set; }

    public int Doors { get; set; } = 4;
}

Using statement (and declaration)

The using statement ensures that instances implementing IDisposable are properly disposed.

using (IDisposable x = CreateSomeDisposable())
{
    // do stuff
}

Without the using statement, developers would need to always write a try-finally block and check for null to prevent exceptions.

IDisposable x = CreateSomeDisposable();
try
{
    // do stuff
}
finally
{
    if (!ReferenceEquals(x, null)) 
        x.Dispose();
}

With the release of C# 8.0 we can now use the using declaration, which simplifies even more the code, removing the need for brackets, disposing the instance at the end of the current scope.

1
2
3

using IDisposable x = CreateSomeDisposable();

// do stuff

Foreach loop

The foreach keyword makes it easier to iterate over an IEnumerable but did you know that, before C# 1.2, developers had to iterate over the enumerator and explicitly call the dispose method?

IEnumerable cars = GetAllCars();
IEnumerator carsEnumerator = cars.GetEnumerator();
try
{
    while (carsEnumerator.MoveNext())
    {
        Car car = (Car)carsEnumerator.Current;

        // do stuff
    }
}
finally
{
    IDisposable disposable = carsEnumerator as IDisposable;
    if (!ReferenceEquals(disposable, null))
        disposable.Dispose();
}

With the release of C# 2.0, Microsoft introduced generics and iterators as a first-class part of the language which nowadays means that iterating over any collection is just a simple use of the foreach keyword:

IEnumerable<Car> cars = GetAllCars();
foreach (Car car in cars)
{
    // do stuff
}

Object and collection initializers

Before C# 3.0, when initializing a new object you had to invoke the constructor followed by lines of assignment statements. Same with collections, were method Add or indexers were used.

Car car = new Car();
car.Brand = "Audi";
car.Model = "A8";
car.LicensePlate = "ABCD-1234";
car.Doors = 2;

Car[] cars = new Car[1];
cars[0] = car;

With object and collection initializers the code is more compact and scoped using brackets.

Car car = new Car
{
    Brand = "Audi",
    Model = "A8",
    LicensePlate = "ABCD-1234",
    Doors = 2
};

Car[] cars = new Car[]
{
    car
};

Implicitly typed variables (and anonymous types)

The release of C# 3.0 introduced some features, being one the possibility of creating anonymous types which are usually used to store read-only data into a temporary instance, being the class generated internally by the compiler.

Because developers don’t know the class name since it will be generated at compile time, Microsoft had to provide a way to define the variable type, so they created the var keyword that will tell the compiler it should infer the type.

var person = new
{
    GivenName = "John",
    Surname = "Doe"
};

Because var can be used with anything, not just anonymous classes, some developers disagree it improves code legibility despite reducing the code that must be written, specially when defining generic variables.

I personally believe that var is an improvement to code legibility as long as the surrounding code is properly implemented, like giving proper names to variables and methods.

var car = new Car
{
    Brand = "Audi",
    Model = "A8",
    LicensePlate = "ABCD-1234",
    Doors = 2
};

var cars = new[]
{
    car
};

Lambda expressions (and Action/Func)

To create anonymous functions that can be implicitly converted to delegates as long as the signature matches, Microsoft added the lambda declaration operator => and provided into the framework pre-existing delegate types like Action for void results, or Func<T> if a result was returned, with multiple overloads for variable input parameters.

Before C# 3.0 developers had to define their own delegate classes and invokers had to be explicit by using the delegate keyword.

static IEnumerable<string> Filter(IEnumerable<string> values, FilterString filter)
{
    var result = new List<string>();
    
    foreach (var value in values)
    {
        if(filter(value))
            result.Add(value);
    }

    return result;
}

public delegate bool FilterString(string value);

// usage
var filterValues = Filter(values, delegate(string s)
{
    return s.Contains('1');
});

Using lambda expressions and pre-defined delegates, we don’t need to define our own and the code invoking Filter is much compacter.

static IEnumerable<string> Filter(IEnumerable<string> values, Func<string, bool> filter)
{
    var result = new List<string>();
    
    foreach (var value in values)
    {
        if(filter(value))
            result.Add(value);
    }

    return result;
}

// usage
var filterValues = Filter(values, s => s.Contains('1'));

Extension methods

The release of C# 3.0 also introduced extension methods, an extremely powerful feature that allows to “add” methods to existing classes without modifying, extending or recompiling the class. They look like instance methods but are actually static methods that receive the instance as the first parameter and the compiler does the magic for us.

public static class StringExtensions
{
    public static int? ToNullableInt(this string value)
    {
        if(value is null)
            return null;
        return value.ToInt();
    }

    public static int ToInt(this string value)
    {
        return int.Parse(value, NumberStyles.None);
    }
}

// usage
var convertedValue = "12345".ToNullableInt();
Without extension methods the code would be more verbose:

public static class StringExtensions
{
    public static int? ToNullableInt(string value)
    {
        if(value is null)
            return null;
        return ToInt(value);
    }

    public static int ToInt(string value)
    {
        return int.Parse(value, NumberStyles.None);
    }
}

// usage
var convertedValue = StringExtensions.ToNullableInt("12345");

LINQ — Language Integrated Query

I want to give a special note about LINQ, despite not being an integral part of the C# language but a framework library, it is a powerful demonstration of what can be done when using a lot of C# syntactic sugar features — the usage of generics, iterators, extension methods over IEnumerable, lambda expressions, anonymous types and implicit typed local variables.

Before C# 3.0, if we wanted to filter a collection cars with two doors and store a distinct collection of brands and models, we had to implement a class with an equality overload and use a HashSet to prevent duplicates.

public class CarBrandModelGroup : IEquatable<CarBrandModelGroup>
{
    public CarBrandModelGroup(
        string brand,
        string model
    )
    {
        Brand = brand;
        Model = model;
    }

    public string Brand { get; }

    public string Model { get; }

    public bool Equals(CarBrandModelGroup other)
    {
        if (ReferenceEquals(null, other)) return false;
        if (ReferenceEquals(this, other)) return true;
        return Brand == other.Brand && Model == other.Model;
    }

    public override bool Equals(object obj)
    {
        if (ReferenceEquals(null, obj)) return false;
        if (ReferenceEquals(this, obj)) return true;
        return obj.GetType() == GetType() && Equals((CarBrandModelGroup)obj);
    }

    public override int GetHashCode()
    {
        uint hc1;
        if (ReferenceEquals(Brand, null))
            hc1 = 0;
        else
        {
            hc1 = (uint)Brand.GetHashCode();
        }

        uint hc2;
        if (ReferenceEquals(Model, null))
            hc2 = 0;
        else
        {
            hc2 = (uint)Model.GetHashCode();
        }

        return (int)(hc1 ^ hc2);
    }
}

// the group by brand and model cars with doors == 2
var carBrandModelsWithTwoDoors = new HashSet<CarBrandModelGroup>();
foreach (var car in cars)
{
    if (car.Doors == 2)
    {
        carBrandModelsWithTwoDoors.Add(new CarBrandModelGroup(
            car.Brand,
            car.Model
        ));
    }
}

With the introduction of LINQ, the code will be a simple use of the available methods while keeping in mind anonymous classes implement the default comparer, so no need for a custom class for grouping.

var carBrandModelsWithTwoDoors = cars.Where(c => c.Doors == 2).DistinctBy(c => new
{
    c.Brand,
    c.Model
}).ToArray();

Conclusion

In this article I’ve shown how C# have evolved over the years to be a more productive and developer friendly language.

Funny enough, when I started to write this article I wanted to cover major features that have been added over the years but then I realized just how big this language is and a single article would be too much, so I ended focusing more on C# 3.0.

This clearly calls for more!

Configuration providers in .NET

2023-12-21T00:00:00.000Z

One interesting feature of the .NET ecosystem is the ability to configure the application using Microsoft.Extensions.Options library. It allows developers to easily manage and inject application settings from different sources, such as appsettings.json files, environment variables, command-line arguments, or even custom sources.

Using a SQL database as an example, in this article I’m going to explain how to create a custom provider for Microsoft.Extensions.Options that reads key-valued configurations from a table that also ensure values are refreshed in-memory if the table content changes.

If you want to use an approach for which you don’t have a provider available, like getting configurations from some custom API inside your company, you can easily use this example as a template to implement whatever requirements you may have.

Solution setup

For starters, we’ll need a SQL database with a table to store the application settings. In this example, which I have available on GitHub, I’m going to use SQL Server (feel free to use your favorite database) and create an ApplicationSettings table with two columns to store the keys and corresponding values.

create table ApplicationSettings(
  [Key] nvarchar(256) not null primary key,
  [Value] nvarchar(256) not null
)

To keep things simple, we are going to create a console application and use the NuGet Microsoft.Extensions.Hosting to setup the host (dependency injection, logging and configurations) but this code is fully compatible with any application using ASP.NET Core 2 or later.

Create a new console application and register the following NuGets:

Microsoft.Extensions.Hosting — for hosting setup;
Microsoft.data.SqlClient — to access our SQL Server database (or another provider if a different database);
Dapper — optional, just to make it easier to map SQL results to C# entities;

You can also configure the *.csproj file to include the application settings files when publishing.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <None Include="*.config;*.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Dapper" Version="2.1.24" />
    <PackageReference Include="Microsoft.Data.SqlClient" Version="5.1.2" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </ItemGroup>

</Project>

Add a new appsettings.json file to the project and include some options, like the connection string to the SQL Server database and some custom settings — in this example we are going to output a simple message to the console.

{
  "ConnectionStrings": {
    "ArticleDotNetConfiguration": "Data Source=localhost;Database=ArticleDotNetConfiguration;User Id=sa;Password=abcd1234;Encrypt=false;"
  },
  "Example": {
    "Message": "Hello world, from appsettings.json!"
  }
}

Create a class representing the example options.

public record ExampleOptions
{
    public string Message { get; init; }
}

Open the Program.cs file, create a host with pre-configured defaults, configure the ExampleOptions and output the message that was loaded from the appsettings.json file.

var builder = Host.CreateApplicationBuilder(args);

builder.Services.Configure<ExampleOptions>(
    builder.Configuration.GetSection("Example")
);

using var host = builder.Build();

var options = host.Services.GetRequiredService<IOptions<ExampleOptions>>().Value;
Console.WriteLine(options.Message);

Running the application, the message stored in the appsettings.json file should be displayed.

Configuration provider

To create a custom configuration provider you need to implement two interfaces:

IConfigurationSource — will be added to the configuration manager and is used to store options (like a connection string) and build provider instances.
IConfigurationProvider — knows how to load the application settings and has methods to get or set configuration values by a given key. Providers usually extend the class ConfigurationProvider which makes it easier to store settings in-memory.

Create a new class SqlServerConfigurationSource, add a property for the connection string and implement the interface IConfigurationSource without any logic, for now.

public class SqlServerConfigurationSource : IConfigurationSource
{
    public string ConnectionString { get; set; }

    public IConfigurationProvider Build(IConfigurationBuilder builder) => throw new NotImplementedException();
}

Create a new class SqlServerConfigurationProvider, passing the configuration source as a constructor parameter and extending the class ConfigurationProvider.

Override the Load method, reading application settings from the SQL table and store the results into the Data dictionary.

public class SqlServerConfigurationProvider(
    SqlServerConfigurationSource source
) : ConfigurationProvider
{
    public override void Load()
    {
        using var connection = new SqlConnection(source.ConnectionString);
        connection.Open();

        Data = connection.Query<(string Key, string Value)>(@"
select 
    [Key],
    [Value]
from ApplicationSettings").ToDictionary(e => e.Key, e => e.Value);
    }
}

Reopen the SqlServerConfigurationSource.cs file and implement the Build method, returning a new instance of the provider.

public class SqlServerConfigurationSource : IConfigurationSource
{
    public string ConnectionString { get; set; }

    public IConfigurationProvider Build(IConfigurationBuilder builder) => new SqlServerConfigurationProvider(this);
}

Open the Program.cs file and add the SQL Server configuration source to the host builder. Don’t forget to read the connection string from the existing sources.

var builder = Host.CreateApplicationBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("ArticleDotNetConfiguration");
builder.Configuration.Add<SqlServerConfigurationSource>(source =>
{
    source.ConnectionString = connectionString;
});

builder.Services.Configure<ExampleOptions>(
    builder.Configuration.GetSection("Example")
);

// ...

Since the SQL Server provider was the last source added to the configuration manager, it will have priority over the existing ones. Let’s try to override the message by adding the key Example:Message with a value like Hello world, from database!.

insert into ApplicationSettings values (
  'Example:Message',
  'Hello world, from database!'
)

Running the application, the message stored in the ApplicationSettings table should be displayed.

Reloading data

In our previous code, we were getting an IOptions from the container to get the application settings. This is fine but what if the developer is using an IOptionsMonitor to always get the latest configurations?

The current provider implementation never updates the Data property after the initial load, so we let’s change that.

There are multiple ways to detect data changes from a SQL Server database, but for simplicity we are going to implement a simple worker that will be constantly loading application settings, compare what’s in memory and if changes are detected, invoke the base method OnReload that will trigger a refresh in all listeners.

Let’s start by changing the Program.cs file and create a task that will be writing the message at intervals so we’ll see a different message when we update the table. Don’t forget to use an IOptionsMonitor instead of an IOptions.

var builder = Host.CreateApplicationBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("ArticleDotNetConfiguration");
builder.Configuration.Add<SqlServerConfigurationSource>(source =>
{
    source.ConnectionString = connectionString;
});

builder.Services.Configure<ExampleOptions>(
    builder.Configuration.GetSection("Example")
);

using var host = builder.Build();

var appOptions = host.Services.GetRequiredService<IOptionsMonitor<ExampleOptions>>();

await Task.Run(async () =>
{
    do
    {
        var options = appOptions.CurrentValue;

        Console.WriteLine(options.Message);
        await Task.Delay(5_000);
    } while (true);
});

Open the provider class and do the following changes:

Add a private CancellationTokenSource variable that will be used to cancel the worker execution;
Add a private Task variable that will be the responsible to refresh the application settings when they change;
Extract the logic that loads the data into a private method, so both Load method and worker can use that logic — change it to asynchronous code and do a comparison with previous loaded data, so method OnReload can be triggered;
Change the Load method to use the extracted logic and create a worker that will refresh data at intervals — don’t forget to add some exception handling code;
Implement the disposable pattern to release unmanaged resources;

The SqlServerConfigurationProvider should now be as follows:

public class SqlServerConfigurationProvider(
    SqlServerConfigurationSource source
) : ConfigurationProvider, IDisposable
{
    private CancellationTokenSource _cts;
    private Task _refreshWorker;

    #region IDisposable

    ~SqlServerConfigurationProvider() => Dispose(false);

    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (disposing)
        {
            _cts?.Cancel();

            if (_refreshWorker is not null)
            {
                try
                {
                    _refreshWorker.ConfigureAwait(false)
                        .GetAwaiter().GetResult();
                }
                catch (OperationCanceledException)
                {
                    // expected exception due to cancellation
                }
                catch (Exception e)
                {
                    Debug.WriteLine($"Unhandled exception when waiting for the worker to stop: {e}");
                }
            }

            _cts?.Dispose();
        }

        _refreshWorker = null;
        _cts = null;
    }

    #endregion

    public override void Load()
    {
        LoadAsync(CancellationToken.None).ConfigureAwait(false)
            .GetAwaiter().GetResult();

        if (_cts is not null) 
            return;

        _cts = new CancellationTokenSource();

        var ct = _cts.Token;
        _refreshWorker ??= Task.Run(async () =>
        {
            do
            {
                await Task.Delay(15_000, ct);
                try
                {
                    await LoadAsync(ct);
                }
                catch (Exception e)
                {
                    Debug.WriteLine($"Unhandled exception when refreshing database settings: {e}");
                }
            } while (!ct.IsCancellationRequested);
        }, ct);
    }

    private async Task LoadAsync(CancellationToken ct)
    {
        Dictionary<string, string> currentData;
        await using (var connection = new SqlConnection(source.ConnectionString))
        {
            await connection.OpenAsync(ct);

            currentData = (await connection.QueryAsync<(string Key, string Value)>(new CommandDefinition(@"
select 
    [Key],
    [Value]
from ApplicationSettings", cancellationToken: ct))).ToDictionary(e => e.Key, e => e.Value);
        }

        if (HasSameData(currentData))
            return;

        Data = currentData;

        OnReload();
    }

    private bool HasSameData(Dictionary<string, string> currentData)
    {
        if (Data.Count != currentData.Count)
            return false;

        foreach (var (key, value) in currentData)
        {
            if (!Data.TryGetValue(key, out var previousValue) || previousValue != value)
                return false;
        }

        return true;
    }
}

If you now start the application and update or delete the value while running, you should see the task writing different messages.

-- update the settings
update ApplicationSettings
set
  [Value] = 'Hello world, from DB!'
where
  [Key] = 'Example:Message';

-- or delete them
delete ApplicationSettings
where
  [Key] = 'Example:Message';

Reusing the provider

We now have a provider ready to read application settings from a SQL Server database, but I’m sure you are thinking it clearly could be more generic and just work with any SQL database.

Your line of thought is correct, we can easily do that just by changing the options from a connection string to having a connection factory, adding a property for the SQL code and even a TimeSpan for refresh interval. We should also add an exception handling callback (instead of writing into the debugger) and create extension methods to make registration into the configuration manager more readable.

The final code, which is available on GitHub, could be the as follows:

public class SqlExceptionContext
{
    public Exception Exception { get; set; }

    public SqlConfigurationProvider Provider { get; set; }
}

public static class SqlConfigurationBuilderExtensions
{
    private const string SqlExceptionHandlerKey = "SqlExceptionHandler";

    public static IConfigurationBuilder AddSql(
        this IConfigurationBuilder builder,
        Func<DbConnection> connectionFactory,
        string sql = null,
        TimeSpan? refreshInterval = null
    )
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(connectionFactory);

        return builder.Add<SqlConfigurationSource>(source =>
        {
            source.ConnectionFactory = connectionFactory;

            if(sql is not null)
                source.Sql = sql;

            if (refreshInterval is not null)
                source.RefreshInterval = refreshInterval.Value;
        });
    }

    public static IConfigurationBuilder SetSqlExceptionHandler(
        this IConfigurationBuilder builder,
        Action<SqlExceptionContext> handler
    )
    {
        ArgumentNullException.ThrowIfNull(builder);

        builder.Properties[SqlExceptionHandlerKey] = handler;

        return builder;
    }

    public static Action<SqlExceptionContext> GetSqlExceptionHandler(this IConfigurationBuilder builder)
    {
        ArgumentNullException.ThrowIfNull(builder);

        return builder.Properties.TryGetValue(SqlExceptionHandlerKey, out var value)
            ? value as Action<SqlExceptionContext>
            : null;
    }
}

public class SqlConfigurationSource : IConfigurationSource
{
    public Func<DbConnection> ConnectionFactory { get; set; }

    public string Sql { get; set; } = @"
select 
    [Key],
    [Value]
from ApplicationSettings";

    public TimeSpan RefreshInterval { get; set; } = TimeSpan.FromSeconds(15);

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        var exceptionHandler = builder.GetSqlExceptionHandler() ?? (ctx =>
        {
            Debug.WriteLine($"Unhandled SQL exception: {ctx.Exception}");
        });
        return new SqlConfigurationProvider(this, exceptionHandler);
    }
}

public class SqlConfigurationProvider(
    SqlConfigurationSource source,
    Action<SqlExceptionContext> exceptionHandler
) : ConfigurationProvider, IDisposable
{
    private CancellationTokenSource _cts;
    private Task _refreshWorker;

    #region IDisposable

    ~SqlConfigurationProvider() => Dispose(false);

    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (disposing)
        {
            _cts?.Cancel();

            if (_refreshWorker is not null)
            {
                try
                {
                    _refreshWorker.ConfigureAwait(false)
                        .GetAwaiter().GetResult();
                }
                catch (OperationCanceledException)
                {
                    // expected exception due to cancellation
                }
                catch (Exception e)
                {
                    exceptionHandler(new SqlExceptionContext
                    {
                        Exception = e,
                        Provider = this
                    });
                }
            }

            _cts?.Dispose();
        }

        _refreshWorker = null;
        _cts = null;
    }

    #endregion

    public override void Load()
    {
        LoadAsync(CancellationToken.None).ConfigureAwait(false)
            .GetAwaiter().GetResult();

        if (_cts is not null)
            return;

        _cts = new CancellationTokenSource();

        var ct = _cts.Token;
        _refreshWorker ??= Task.Run(async () =>
        {
            do
            {
                await Task.Delay(source.RefreshInterval, ct);
                try
                {
                    await LoadAsync(ct);
                }
                catch (Exception e)
                {
                    exceptionHandler(new SqlExceptionContext
                    {
                        Exception = e,
                        Provider = this
                    });
                }
            } while (!ct.IsCancellationRequested);
        }, ct);
    }

    private async Task LoadAsync(CancellationToken ct)
    {
        Dictionary<string, string> currentData;
        await using (var connection = source.ConnectionFactory())
        {
            await connection.OpenAsync(ct);

            currentData = (await connection.QueryAsync<(string Key, string Value)>(
                new CommandDefinition(source.Sql, cancellationToken: ct)
            )).ToDictionary(e => e.Key, e => e.Value);
        }

        if (HasSameData(currentData))
            return;

        Data = currentData;

        OnReload();
    }

    private bool HasSameData(Dictionary<string, string> currentData)
    {
        if (Data.Count != currentData.Count)
            return false;

        foreach (var (key, value) in currentData)
        {
            if (!Data.TryGetValue(key, out var previousValue) || previousValue != value)
                return false;
        }

        return true;
    }
}

Conclusion

In this article I explained how to create a custom configuration provider for the Microsoft.Extensions.Options library, that could be used in any .NET application that uses Microsoft.Extensions.Hosting, including ASP.NET Core applications.

I used a SQL Server database as an example, but could be easily anything, like getting settings from an internal API and even Windows registry.

C# ‘is null’ vs ‘== null’

2023-12-14T00:00:00.000Z

When C# 7.0 was officially released in March 2017 it introduced several new features to make the life of developers easier, like tuples and deconstruction, local functions, expression body definitions and, the focus of this article, pattern matching.

One of the advantages of pattern matching is a more concise syntax for testing expressions and taking actions when there’s a match, increasing the readability and correctness of your code.

Checking for nulls is one of the most common usages. Before C# 7.0, if a developer wanted to check if a given value was null, usually the equality comparison would be used.

public static class PersonExtensions
{
    public static string FullName(this Person person)
    {
        if (person == null) throw new ArgumentNullException(nameof(person));

        return $"{person.GivenName} {person.Surname}";
    }
}

With pattern matching, the extension method would be using the is operator and the null constant to check if the person variable is null.

public static class PersonExtensions
{
    public static string FullName(this Person person)
    {
        if (person is null) throw new ArgumentNullException(nameof(person));

        return $"{person.GivenName} {person.Surname}";
    }
}

The change is so small that you are probably questioning if changing the way you code is really worthy for such a small readability improvement, to have the same results?

And you are right in thinking that way since that’s probably true for 99% of use cases (if not 99.999%) but what if you really want to be sure it works every time?

You see, reference types can overload the == operator and, if the developer decides to always return false when comparing to null, the first example would throw a NullReferenceException.

Let’s test that by overloading the == operator to always return false, whatever the parameters received:

public class Person
{
    public string GivenName { get; set; }

    public string Surname { get; set; }

    public static bool operator ==(Person left, Person right) => false;

    public static bool operator !=(Person left, Person right) => !(left == right);
}

public static class PersonExtensions
{
    public static string FullName(this Person person)
    {
        if (person == null) throw new ArgumentNullException(nameof(person));

        return $"{person.GivenName} {person.Surname}";
    }
}

If we now call the extension method FullName with a null argument a NullReferenceException will be thrown instead of the expected ArgumentNullException. This happens because the compiler knows there’s an equality overload, calls it and gets false, so if won’t enter the if statement.

If you look at the generated IL Code, you’ll see the Person equality operator being called.

// [36 5 - 36 6]
IL_0000: nop

// [37 9 - 37 28]
IL_0001: ldarg.0      // person
IL_0002: ldnull
IL_0003: call         bool Person::op_Equality(class Person, class Person)
IL_0008: stloc.0      // V_0

// [37 29 - 37 77]
IL_0009: ldloc.0      // V_0
IL_000a: brfalse.s    IL_0017
IL_000c: ldstr        "person"
IL_0011: newobj       instance void [System.Runtime]System.ArgumentNullException::.ctor(string)
IL_0016: throw
IL_0017: ldarg.0      // person
IL_0018: callvirt     instance string Person::get_GivenName()
IL_001d: ldstr        " "
IL_0022: ldarg.0      // person
IL_0023: callvirt     instance string Person::get_Surname()
IL_0028: call         string [System.Runtime]System.String::Concat(string, string, string)

// [40 5 - 40 6]
IL_002d: stloc.1      // V_1
IL_002e: br.s         IL_0030
IL_0030: ldloc.1      // V_1
IL_0031: ret

Before C# 7.0 if you wanted to be sure the == operator overload was ignored, you had to use object.ReferenceEquals to compare the object reference to null.

public static class PersonExtensions
{
    public static string FullName(this Person person)
    {
        if (ReferenceEquals(person, null)) throw new ArgumentNullException(nameof(person));

        return $"{person.GivenName} {person.Surname}";
    }
}

But when using pattern matching the compiler always generates code that compares to null, ignoring any == operator overload. This means you have the same behavior as using the object.ReferenceEquals method without writing so much code.

public class Person
{
    public string GivenName { get; set; }

    public string Surname { get; set; }

    public static bool operator ==(Person left, Person right) => false;

    public static bool operator !=(Person left, Person right) => !(left == right);
}

public static class PersonExtensions
{
    public static string FullName(this Person person)
    {
        if (person is null) throw new ArgumentNullException(nameof(person));

        return $"{person.GivenName} {person.Surname}";
    }
}

This ensures the method FullName always throws ArgumentNullException when a null reference is received.

Looking at the generated IL Code, we can see the person reference is being compared to null using the ceq instruction (this is exactly the same code if object.ReferenceEquals was being used — it would be inlined).

// [36 5 - 36 6]
IL_0000: nop

// [37 9 - 37 43]
IL_0001: ldarg.0      // person
IL_0002: ldnull
IL_0003: ceq
IL_0005: stloc.0      // V_0

IL_0006: ldloc.0      // V_0
IL_0007: brfalse.s    IL_0014

// [37 44 - 37 92]
IL_0009: ldstr        "person"
IL_000e: newobj       instance void [System.Runtime]System.ArgumentNullException::.ctor(string)
IL_0013: throw

// [39 9 - 39 55]
IL_0014: ldarg.0      // person
IL_0015: callvirt     instance string Person::get_GivenName()
IL_001a: ldstr        " "
IL_001f: ldarg.0      // person
IL_0020: callvirt     instance string Person::get_Surname()
IL_0025: call         string [System.Runtime]System.String::Concat(string, string, string)
IL_002a: stloc.1      // V_1
IL_002b: br.s         IL_002d

// [40 5 - 40 6]
IL_002d: ldloc.1      // V_1
IL_002e: ret

Conclusion

In this article I explained why using pattern matching for null checks is preferred to using the equality operator.

Not only it’s a small readability improvement but it also ensures the object reference is always compared to null even if the class has overloaded the == operator (same behavior as using the object.ReferenceEquals method but without writing so much code).

Even if the equality operator overload is properly implemented, we can also consider this a small performance increase because executing the ceq operation is faster that a call to the class equality operator.

As stated before, this may not affect 99% of your use cases, but for such small a small change in the way you code, why not?

.NET — DevOps and Entity Framework Core

2023-12-04T00:00:00.000Z

Most .NET developers either have used Entity Framework Core or eventually will, because it is one of the most known and flexible ORM frameworks to access databases in the .NET ecosystem, directly supported by Microsoft and the Open Source community.

In this article I’m going to explain how you can create a console application that will check if migrations are missing from the database and apply them accordingly. This is an approach I’ve been using ever since Microsoft released .NET Core 1 RC 1 (at the time I even created an open-source library to facilitate console hosting, now deprecated because we can use Microsoft.Extensions.Hosting).

Ever since its inception, one of the main features supported by Entity Framework is the concept of database migrations in code-first scenarios which, in a simplified way, work as follows:

Model entities representing tables are mapped into the DbContext, were table and column names, data sizes, foreign keys, indexes, and so on, are defined;
Entity Framework tools are installed into the project (either the .NET Core CLI tools for cross platform or Package Manager Console tools for Visual Studio integration);
A class implementing IDesignTimeDbContextFactory is created and will configure the DbContext when Entity Framework tools are run — provider to use, connection string, etc. This reduces the number of parameters that need to be passed when using the CLI/PMC tools.
When adding a new migration, the tools are going to use the factory to create the DbContext, compare the mappings to the current database schema, see what’s different and create a migration class with a bunch of C# operations that will change the schema accordingly (like creating a new index, adding a new column, dropping a table). The migration will also have a method for the inverse operations (drop the index, remove the column, recreate the table) that can be used to revert changes;
The tools can also be run to update the database schema, either to the most recent or revert to an older version, ensuring missing migrations are run sequentially in the required order.

This is a very powerful feature offered by EF Core because it speeds up the development and evolution of the database schemas while ensuring a historic change log is kept and version controlled near the C# entity models. The application may have been developed for 10 years but any new team member can setup a local version of the database in just a few steps.

But you are probably thinking: this seems nice and all, but he’s talking about DevOps and I’m not sure how I can use this to evolve my production schemas? The company I work for does not allow any developer to connect to production databases and even if it did, certainly the user wouldn’t have permissions to change the database schema! I can’t run EF Core tools from my computer to do this!

Why an installer for EF Core migrations?

Having a console application that applies migrations to a database has some advantages that will probably benefit the DevOps process your company currently implements:

For cloud solutions, you can add steps into the Continuous Delivery pipeline that run the console before distributing the APIs or Websites, which may even require the approval of specific DevOps team members. Because the pipeline is tightly controlled, the production connection strings that can execute DDL instructions are properly secured. Even if you don’t have a DevOps team but the access to production is secured by the Infrastructure team, the console can be provided as a standalone executable and they decide how and where it should be run, manually or not.
For on-prem solutions, the console can be packed with the application installer to be run every time a new version is released. If it fails, the installation process can either be halted or database changes reverted to a previous state by restoring a backup made at the start of the installation.

In both scenarios this process is more reliable than, lets say, executing SQL scripts which are harder to read, maintain and debug in case of problems. If the console application has been configured with a good logging library (either to a file or command line output) there’s no reason someone can’t analyze what is happening.

The use case scenario
To keep things simple and focusing in the migrations executable, let’s assume we are maintaining an API that manages a warehouse. This API is responsible for storing product information and stock movements and is implemented using a typical three-layer architecture, using Entity Framework Core to store and retrieve data from a SQL Server database.

In this hypothetical scenario, we decided to improve our DevOps process by creating a console application to apply migrations into the database. This tool will be called migrator, which is a new console project inside the database layer.

It will have a direct dependency from the database implementation, which holds the Entity Framework Core mappings for the database entities, defined in the database contracts layer.

The diagram for projects and their dependencies inside the solution, after creating the migrator executable project, could look like this:

Since this API only manages products and stock movements, the database model could be represented by the following entity contracts (navigation properties won’t be used for simplicity):

public class ProductEntity
{
    public long Id { get; set; }

    public string Code { get; set; }

    public string Name { get; set; }
}

public class StockMovementEntity
{
    public long Id { get; set; }

    public long ProductId { get; set; }

    public int Quantity { get; set; }

    public DateTimeOffset OccurredOn { get; set; }
}

The Entity Framework Core database context could be mapped as follows:

        .HasMaxLength(8);
            cfg.Property(e => e.Name)
                .IsRequired()
                .HasMaxLength(128);
        });

        modelBuilder.Entity<StockMovementEntity>(cfg =>
        {
            cfg.ToTable("StockMovements");

            cfg.HasKey(e => e.Id);

            cfg.Property(e => e.Id)
                .IsRequired()
                .ValueGeneratedOnAdd();
            cfg.HasOne<ProductEntity>()
                .WithMany()
                .HasForeignKey(e => e.ProductId)
                .IsRequired();
            cfg.Property(e => e.Quantity)
                .IsRequired();
            cfg.Property(e => e.OccurredOn)
                .IsRequired();
        });
    }
}

As I said before, nothing fancy here, just a simple use-case with a database model we will use for creating our migrations and apply them using our console application.

I have a working example showcasing this scenario on GitHub (only the database layer), so feel free to give it a good look. I’m using .NET 8, but any previous .NET version will work without any code changes. If for some reason you need to support older framework versions like .NET Core App 2+ or .NET Framework 4.6.2+, just downgrade the nuggets to a previous versions that supports .NET Standard 2.0, like versions 2.x or 3.x, and do some small tweaks into the hosting setup.

Console application setup

Now that we have defined both models and mappings, let’s setup the console application, which is going to use Microsoft.Extensions.Hosting for an easier setup of logging, dependency injection and application settings configuration.

Start by creating a console application project and create a Program.cs file with a simple “hello world!” output.

Add a project reference to the database implementation and add both Microsoft.Extensions.Hosting and Microsoft.EntityFrameworkCore.Tools packages (we are going to use Visual Studio Package Manager Console for creating the migrations, but feel free to use .NET Core CLI tools).

Inside the database layer, the projects should be similar to this:

Migrations setup

To prepare the project for creating EF Core migrations, start by adding an appsettings.json file with a connection string to an empty SQL Server database and, to be used in the future by the host, you can already make some logging configurations.

{
  "ConnectionStrings": {
    "ArticleDevOpsEfCore": "Data Source=localhost;Database=ArticleDevOpsEfCore;User Id=sa;Password=abcd1234;Encrypt=false;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Trace",
      "Microsoft": "Information"
    },
    "Console": {
      "IncludeScopes": true
    },
    "Debug": {
      "IncludeScopes": true
    },
    "EventSource": {
      "IncludeScopes": true
    }
  }
}

Remember to tell the application that, when publishing, the configuration files must be copied to the output folder. This is done by adding an include property to the csproj file.

1
2
3

<ItemGroup>
  <None Include="*.config;*.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Create a new class implementing IDesignTimeDbContextFactory. This class will be responsible for creating and configuring the database contexts when managing migrations via .NET Core CLI tools or Visual Studio Package Manager Console.

To know which connection string must be used, we are going to use a ConfigurationBuilder to read the settings file and then register a SQL Server provider with a small detail — we must specify that the migrations are stored in the console application executable, not where the context is defined.

public class DesignTimeDbContextFactory : IDesignTimeDbContextFactory<DatabaseContext>
{
    public DatabaseContext CreateDbContext(string[] args)
    {
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json", false)
            .Build();

        var options = new DbContextOptionsBuilder<DatabaseContext>().UseSqlServer(
            configuration.GetConnectionString("ArticleDevOpsEfCore"),
            o => o.MigrationsAssembly(typeof(Program).Assembly.FullName)
        ).Options;

        return new DatabaseContext(options);
    }
}

Let’s test the setup and see if we can create some migrations. Open the Package Manager Console and run the following command:

1	add-migration InitialModelSetup

If everything went as expected, a new Migrations folder was created with a InitialModelSetup migration class that will setup the database model. If your database schema is empty, it should look like this:

/// <inheritdoc />
public partial class InitialModelSetup : Migration
{
    /// <inheritdoc />
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.CreateTable(
            name: "Products",
            columns: table => new
            {
                Id = table.Column<long>(type: "bigint", nullable: false)
                    .Annotation("SqlServer:Identity", "1, 1"),
                Code = table.Column<string>(type: "nvarchar(8)", maxLength: 8, nullable: false),
                Name = table.Column<string>(type: "nvarchar(128)", maxLength: 128, nullable: false)
            },
            constraints: table =>
            {
                table.PrimaryKey("PK_Products", x => x.Id);
            });

        migrationBuilder.CreateTable(
            name: "StockMovements",
            columns: table => new
            {
                Id = table.Column<long>(type: "bigint", nullable: false)
                    .Annotation("SqlServer:Identity", "1, 1"),
                ProductId = table.Column<long>(type: "bigint", nullable: false),
                Quantity = table.Column<int>(type: "int", nullable: false),
                OccurredOn = table.Column<DateTimeOffset>(type: "datetimeoffset", nullable: false)
            },
            constraints: table =>
            {
                table.PrimaryKey("PK_StockMovements", x => x.Id);
                table.ForeignKey(
                    name: "FK_StockMovements_Products_ProductId",
                    column: x => x.ProductId,
                    principalTable: "Products",
                    principalColumn: "Id",
                    onDelete: ReferentialAction.Cascade);
            });

        migrationBuilder.CreateIndex(
            name: "IX_Products_Code",
            table: "Products",
            column: "Code",
            unique: true);

        migrationBuilder.CreateIndex(
            name: "IX_StockMovements_ProductId",
            table: "StockMovements",
            column: "ProductId");
    }

    /// <inheritdoc />
    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropTable(
            name: "StockMovements");

        migrationBuilder.DropTable(
            name: "Products");
    }
}

Hosting setup

Now that we know the project is ready to add or remove migrations based on our development database, let’s create all the required code to apply migrations when running the console.

Open the launch profile, and in the environment variables, add a new DOTNET_ENVIRONMENT with the value development. This will be used by the host to know your current environment — development, stagging or production (default) — when running the application which is useful for loading different settings or executing code based on the environment, like creating test data.

Open the Program.cs file and use Host.CreateApplicationBuilder to create a builder for setting up a new host. It will use pre-configured defaults, like loading settings from the appsettings.json file or from environment variables and output logging to console and debug windows, while supporting dependency injection.

You can use the builder to register other logging providers, like NLog or Serilog, and register the Entity Framework Core context into the dependency injection container using a SQL Server provider. Because the migrations are going to be run by a console application, the context can be shared as a singleton (by default it is scoped, useful for ASP.NET Core apps), otherwise you must create a scope explicitly. Once again, don’t forget to specify the assembly were migrations are stored.

var builder = Host.CreateApplicationBuilder(args);

ConfigureLogging(
    builder.Logging
);

ConfigureServices(
    builder.Services,
    builder.Configuration
);

using var host = builder.Build();

return;

static void ConfigureLogging(
    ILoggingBuilder logging
)
{
    // configure other logging providers, like NLog, Serilog or even Application Insights
}

static void ConfigureServices(
    IServiceCollection services,
    IConfiguration configuration
)
{
    var connectionString = configuration.GetConnectionString("ArticleDevOpsEfCore");
    services.AddDbContext<DatabaseContext>(options => options.UseSqlServer(
        connectionString,
        o => o.MigrationsAssembly(typeof(Program).Assembly.FullName)
    ), ServiceLifetime.Singleton);
}

Create a new class named Migrator with a RunAsync method (that will have the migrator implementation), register it as a singleton into the DI container and, after creating the host, resolve and run it. Because migrations can fail, it is also a good idea to implement some exception handling logic (because even host setup can fail, I also prefer to wrap it). Also, we should support the cancellation of this process when CTRL+C or exit is requested, so let’s use a CancellationTokenSource for that.

using var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, eventArgs) =>
{
    cts.Cancel();
    eventArgs.Cancel = true;
};

ILogger<Program> logger = null;
try
{
    var builder = Host.CreateApplicationBuilder(args);

    ConfigureLogging(
        builder.Logging
    );

    ConfigureServices(
        builder.Services,
        builder.Configuration
    );

    using var host = builder.Build();

    logger = host.Services.GetRequiredService<ILogger<Program>>();

    var migrator = host.Services.GetRequiredService<Migrator>();

    logger.LogDebug("Running migrator");
    await migrator.RunAsync(cts.Token);
    logger.LogInformation("Migrator run successfully");
}
catch (Exception e)
{
    if (logger is null)
    {
        await Console.Error.WriteLineAsync("Application failed with a fatal error");
        await Console.Error.WriteLineAsync(e.ToString());
    }
    else
        logger.LogCritical(e, "Application failed with a fatal error");

    throw;
}

return;

static void ConfigureLogging(
    ILoggingBuilder logging
)
{
    // configure other logging providers, like NLog, Serilog or even Application Insights
}

static void ConfigureServices(
    IServiceCollection services,
    IConfiguration configuration
)
{
    var connectionString = configuration.GetConnectionString("ArticleDevOpsEfCore");
    services.AddDbContext<DatabaseContext>(options => options.UseSqlServer(
        connectionString,
        o => o.MigrationsAssembly(typeof(Program).Assembly.FullName)
    ), ServiceLifetime.Singleton);

    services.AddSingleton<Migrator>();
}

Applying migrations

With the host fully configured and ready to run the migrator, let’s implement the migrations logic.

Open the Migrator.cs file and create a constructor receiving both a logger and a database context. Inside the RunAsync method add some helpful logging and use the ctx.Database.MigrateAsync to update the database schema to the latest available. Keep in mind this method will apply the missing migrations and it’s not the same as EnsureCreatedAsync, which just checks if the database exists and if it doesn’t, creates the database and schema without using any migration.

public class Migrator(
    ILogger<Migrator> _logger,
    DatabaseContext _context
)
{
    public async ValueTask RunAsync(CancellationToken ct)
    {
        _logger.LogDebug("Migrating database to the latest version");
        await _context.Database.MigrateAsync(ct);
        _logger.LogInformation("Database migrated to latest version");
    }
}

If you now run the console, you’ll see some output showing the DDL instructions that are being run and if everything went as expected the database should now list both the EF Core migration history (used to track which migrations are applied) and business tables.

Seeding data

Despite Entity Framework Core supporting data seeds when applying migrations, I think it is limited for production scenarios, like seeding different data based on environment or need to run some business logic, you will face limitations if using what EF Core offers.

To solve this problem I usually create a specialized interface for seeding data into the migrator project, so developers may implement how many seed logic they need and even decide the order by which they are run.

In the migrator project, create a new IDataSeed interface, inside a DataSeeds folder, with a SeedAsync method. As a small note, I like to pass arguments that can be used for auditing so I can use them on metadata columns, but they aren’t a requirement — just pass what makes sense to you.

public interface IDataSeed
{
    ValueTask SeedAsync(
        string seededBy,
        DateTimeOffset seededOn,
        CancellationToken ct
    );
}

Let’s change the migrator to run all registered seeds after applying the migrations. Open the Migrator.cs, pass a collection of data seeds to the constructor and then, inside a transaction, execute each seed one by one. I recommend to flush changes after each seed to be sure they all see the data created by each other, even if some have to execute native SQL code for performance reasons.

public class Migrator(
    ILogger<Migrator> _logger,
    DatabaseContext _context,
    IEnumerable<IDataSeed> _dataSeeds
)
{
    public async ValueTask RunAsync(CancellationToken ct)
    {
        _logger.LogDebug("Migrating database to the latest version");
        await _context.Database.MigrateAsync(ct);
        _logger.LogInformation("Database migrated to latest version");

        var seededOn = DateTimeOffset.UtcNow;
        await using var tx = await _context.Database.BeginTransactionAsync(ct);

        foreach (var dataSeed in _dataSeeds)
        {
            using var _ = _logger.BeginScope("DataSeed:{DataSeed}", dataSeed.GetType().Name);

            _logger.LogDebug("Seeding data");

            await dataSeed.SeedAsync(
                "Migrator",
                seededOn,
                ct
            );
            await _context.SaveChangesAsync(ct);

            _logger.LogInformation("Data was seeded");
        }

        await tx.CommitAsync(ct);
    }
}

To test the implemented data seed logic, let’s assume we wanted to create test products for development and staging environments, but not in production. Create a new TestProductsDataSeed inside the DataSeeds folder and implement the SeedAsync method creating a bunch of products if they don’t exist and the migrator isn’t running in production.

public class TestProductsDataSeed(
    ILogger<TestProductsDataSeed> _logger,
    IHostEnvironment _env,
    DatabaseContext _context
) : IDataSeed
{
    public async ValueTask SeedAsync(string seededBy, DateTimeOffset seededOn, CancellationToken ct)
    {
        if (_env.IsProduction())
        {
            _logger.LogInformation("Running in production, no test data will be seeded");
            return;
        }

        var productsSet = _context.Set<ProductEntity>();

        var testCodes = Enumerable.Range(0, 150).Select(i => i.ToString("D8", NumberFormatInfo.InvariantInfo)).ToArray();

        var existingCodes = await (
            from p in productsSet
            where
                testCodes.Contains(p.Code)
            select
                p.Code
        ).ToArrayAsync(ct);

        var nonExistingProducts = testCodes.Where(c => !existingCodes.Contains(c)).Select(c => new ProductEntity
        {
            Code = c,
            Name = $"Test product '{c}'"
        });

        await productsSet.AddRangeAsync(nonExistingProducts, ct);
    }
}

Now open the Program.cs file and register the TestProductsDataSeed as a singleton. As a note, you can scan the assembly for classes implementing IDataSeed (with Scrutor, for example) but the order or registration will define the order by which they are run, and I’m assuming that will matter, but feel free to use an approach that works for your scenario.

// ...

static void ConfigureServices(
    IServiceCollection services,
    IConfiguration configuration
)
{
    var connectionString = configuration.GetConnectionString("ArticleDevOpsEfCore");
    services.AddDbContext<DatabaseContext>(options => options.UseSqlServer(
        connectionString,
        o => o.MigrationsAssembly(typeof(Program).Assembly.FullName)
    ), ServiceLifetime.Singleton);

    services.AddSingleton<Migrator>();

    services.AddSingleton<IDataSeed, TestProductsDataSeed>();
}

If we now run the migrator the products table should have test data.

Conclusion

In this article I explained how DevOps processes can be simplified by implementing a console application that knows how to apply Entity Framework Core migrations and seed initial data to a database, to be introduced into de Continuous Delivery pipeline.

The implementation using Microsoft.Extensions.Hosting is very straightforward and simple while providing a more tight integration against the model definitions and with improved logging, so it certainly is an approach to consider.

Even with small tweaks, in can be improved to whatever scenarios you may face, like forcing a backup before applying the migrations and reverting to it if something fails, perfect for on-prem solutions.

Once again, I have a working example on GitHub, so feel free to give it a good look.

.NET — ToList vs ToArray

2023-11-09T00:00:00.000Z

Ever since Microsoft introduced Language Integrated Query to the .NET framework (also known as LINQ) developers have been using it extensively to work with collections.

From a simple filter, to an aggregation, to a transformation, LINQ is the technology of choice to keep code clean and readable. We even have providers that convert LINQ instructions into SQL commands that will be run in some database.

In this article I’m going to compare the performance of ToList versus ToArray when creating short lived collections. I’m also going to execute the test in different versions of the framework (.NET Framework 4.8, .NET 7 and .NET 8) so we can also see how much the performance have improved over the years.

One of the coding guidelines for the applications I manage dictates the following:

Always use IReadOnlyCollection instead of IEnumerable when passing collections between application layers and ToArray should be used to force the enumeration.

Because we developers are curious by default and need to understand why things are implemented in a given way, every time we have a new team member, that coding guideline usually leads to the following conversation:

Q: Why do we use IReadOnlyCollection in POCOs instead of IEnumerable?
A: Well, because we want the contracts to clearly state the collection is in memory, hence no multiple enumerations will occur, and any mapping problems will happen in the corresponding layer.
Q: Fair enough, but why ToArray? That interface is implemented by arrays and lists, I could be using ToList and have the same result.
A: The result is the same, that’s a fact, but ToArray is usually faster and more memory efficient than ToList, and since it’s a short lived collection that won’t be mutated, the former is preferred.

I’m going to use the well known C# library BenchmarkDotNet to run the tests and the environment will be the following:

BenchmarkDotNet v0.13.10, Windows 11 (10.0.22621.2428/22H2/2022Update/SunValley2)
AMD Ryzen 7 3700X, 1 CPU, 16 logical and 8 physical cores
.NET SDK 8.0.100-rc.2.23502.2
  [Host]             : .NET 8.0.0 (8.0.23.47906), X64 RyuJIT AVX2
  .NET 5.0           : .NET 5.0.17 (5.0.1722.21314), X64 RyuJIT AVX2
  .NET 7.0           : .NET 7.0.11 (7.0.1123.42427), X64 RyuJIT AVX2
  .NET 8.0           : .NET 8.0.0 (8.0.23.47906), X64 RyuJIT AVX2
  .NET Framework 4.8 : .NET Framework 4.8.1 (4.8.9181.0), X64 RyuJIT VectorSize=256

Performance test

The test consists in the creation of a collection that holds random integers, being the size defined by a parameter. To ensure the randomness does not affect the results, the values are cached into an array and before invoking either ToArray or ToList it is converted into a new IEnumerable, not just a cast that could lead to internal optimizations.

[SimpleJob(RuntimeMoniker.Net48)]
[SimpleJob(RuntimeMoniker.Net70)]
[SimpleJob(RuntimeMoniker.Net80)]
[MemoryDiagnoser]
public class ToListVsToArray
{
    [Params(10, 100, 1000, 10000, 100000)]
    public int Size;

    private int[] _items;

    [GlobalSetup]
    public void Setup()
    {
        var random = new Random(123);

        _items = Enumerable.Range(0, Size).Select(_ => random.Next()).ToArray();
    }

    [Benchmark]
    public int[] ToArray() => CreateItemsEnumerable().ToArray();

    [Benchmark]
    public List<int> ToList() => CreateItemsEnumerable().ToList();

    private IEnumerable<int> CreateItemsEnumerable() => _items.Select(e => e);
}

Performance results

Because we want to decide, for a given application, between ToArray or ToList based on performance, let’s first analyze the results for each framework version.

.NET Framework 4.8

| Method  | Size   | Mean          | Error        | StdDev       | Gen0     | Gen1     | Gen2     | Allocated |
|-------- |------- |--------------:|-------------:|-------------:|---------:|---------:|---------:|----------:|
| ToArray | 10     |     166.31 ns |     1.013 ns |     0.947 ns |   0.0484 |        - |        - |     305 B |
| ToList  | 10     |     193.17 ns |     1.248 ns |     1.168 ns |   0.0446 |        - |        - |     281 B |
| ToArray | 100    |     965.26 ns |     8.436 ns |     7.479 ns |   0.2594 |        - |        - |    1637 B |
| ToList  | 100    |   1,032.99 ns |     4.144 ns |     3.876 ns |   0.1984 |        - |        - |    1252 B |
| ToArray | 1000   |   8,377.61 ns |    39.382 ns |    36.838 ns |   1.9836 |        - |        - |   12509 B |
| ToList  | 1000   |   8,665.62 ns |    57.777 ns |    54.045 ns |   1.3428 |   0.0153 |        - |    8514 B |
| ToArray | 10000  |  81,576.33 ns |   923.478 ns |   863.822 ns |  26.9775 |   5.3711 |        - |  171755 B |
| ToList  | 10000  |  83,476.64 ns |   410.694 ns |   342.948 ns |  20.7520 |   4.0283 |        - |  131606 B |
| ToArray | 100000 | 830,624.20 ns | 4,536.991 ns | 4,021.924 ns | 399.4141 | 399.4141 | 399.4141 | 1452144 B |
| ToList  | 100000 | 945,017.84 ns | 7,921.731 ns | 6,615.004 ns | 285.1563 | 285.1563 | 285.1563 | 1051184 B |

The ToArray method is, on average, 10% faster than ToList in .NET Framework 4.8.

.NET 7

| Method  | Size   | Mean          | Error        | StdDev       | Gen0     | Gen1     | Gen2     | Allocated |
|-------- |------- |--------------:|-------------:|-------------:|---------:|---------:|---------:|----------:|
| ToArray | 10     |      50.06 ns |     0.916 ns |     1.254 ns |   0.0134 |        - |        - |     112 B |
| ToList  | 10     |      56.20 ns |     1.022 ns |     0.906 ns |   0.0172 |        - |        - |     144 B |
| ToArray | 100    |     231.18 ns |     1.597 ns |     1.494 ns |   0.0563 |        - |        - |     472 B |
| ToList  | 100    |     261.38 ns |     2.523 ns |     2.236 ns |   0.0601 |        - |        - |     504 B |
| ToArray | 1000   |   2,029.47 ns |    28.534 ns |    25.295 ns |   0.4845 |        - |        - |    4072 B |
| ToList  | 1000   |   2,291.63 ns |    13.328 ns |    11.815 ns |   0.4883 |        - |        - |    4104 B |
| ToArray | 10000  |  17,322.99 ns |   176.548 ns |   165.143 ns |   4.7607 |        - |        - |   40072 B |
| ToList  | 10000  |  22,781.69 ns |   200.720 ns |   177.933 ns |   4.7607 |        - |        - |   40104 B |
| ToArray | 100000 | 306,976.29 ns | 2,525.016 ns | 2,361.901 ns | 124.5117 | 124.5117 | 124.5117 |  400114 B |
| ToList  | 100000 | 337,437.79 ns | 2,441.397 ns | 2,283.684 ns | 124.5117 | 124.5117 | 124.5117 |  400146 B |

The ToArray method is, on average, 13% faster than ToList in .NET 7.

.NET 8

| Method  | Size   | Mean          | Error        | StdDev       | Gen0     | Gen1     | Gen2     | Allocated |
|-------- |------- |--------------:|-------------:|-------------:|---------:|---------:|---------:|----------:|
| ToArray | 10     |      33.89 ns |     0.727 ns |     0.778 ns |   0.0134 |        - |        - |     112 B |
| ToList  | 10     |      40.17 ns |     0.668 ns |     0.625 ns |   0.0172 |        - |        - |     144 B |
| ToArray | 100    |      90.30 ns |     1.104 ns |     0.922 ns |   0.0564 |        - |        - |     472 B |
| ToList  | 100    |      97.87 ns |     1.257 ns |     1.176 ns |   0.0602 |        - |        - |     504 B |
| ToArray | 1000   |     615.97 ns |     6.819 ns |     5.695 ns |   0.4864 |        - |        - |    4072 B |
| ToList  | 1000   |     615.44 ns |     5.195 ns |     4.056 ns |   0.4902 |        - |        - |    4104 B |
| ToArray | 10000  |   5,335.01 ns |    86.179 ns |    76.395 ns |   4.7607 |        - |        - |   40072 B |
| ToList  | 10000  |   5,427.51 ns |    86.063 ns |    80.503 ns |   4.7836 |        - |        - |   40104 B |
| ToArray | 100000 | 169,711.96 ns | 2,405.080 ns | 2,249.713 ns | 124.7559 | 124.7559 | 124.7559 |  400114 B |
| ToList  | 100000 | 162,577.72 ns | 1,634.437 ns | 1,364.829 ns | 124.7559 | 124.7559 | 124.7559 |  400146 B |

The ToArray method is, by a small margin, faster than ToList in .NET 8, being 4% slower on larger collections.

.NET performance evolution

Because we have results for each framework version, let’s compare and see how .NET performance has evolved over the years.

ToArray

| Runtime            | Size   | Mean          | Error        | StdDev       | Gen0     | Gen1     | Gen2     | Allocated |
|------------------- |------- |--------------:|-------------:|-------------:|---------:|---------:|---------:|----------:|
| .NET Framework 4.8 | 10     |     166.31 ns |     1.013 ns |     0.947 ns |   0.0484 |        - |        - |     305 B |
| .NET 7.0           | 10     |      50.06 ns |     0.916 ns |     1.254 ns |   0.0134 |        - |        - |     112 B |
| .NET 8.0           | 10     |      33.89 ns |     0.727 ns |     0.778 ns |   0.0134 |        - |        - |     112 B |
| .NET Framework 4.8 | 100    |     965.26 ns |     8.436 ns |     7.479 ns |   0.2594 |        - |        - |    1637 B |
| .NET 7.0           | 100    |     231.18 ns |     1.597 ns |     1.494 ns |   0.0563 |        - |        - |     472 B |
| .NET 8.0           | 100    |      90.30 ns |     1.104 ns |     0.922 ns |   0.0564 |        - |        - |     472 B |
| .NET Framework 4.8 | 1000   |   8,377.61 ns |    39.382 ns |    36.838 ns |   1.9836 |        - |        - |   12509 B |
| .NET 7.0           | 1000   |   2,029.47 ns |    28.534 ns |    25.295 ns |   0.4845 |        - |        - |    4072 B |
| .NET 8.0           | 1000   |     615.97 ns |     6.819 ns |     5.695 ns |   0.4864 |        - |        - |    4072 B |
| .NET Framework 4.8 | 10000  |  81,576.33 ns |   923.478 ns |   863.822 ns |  26.9775 |   5.3711 |        - |  171755 B |
| .NET 7.0           | 10000  |  17,322.99 ns |   176.548 ns |   165.143 ns |   4.7607 |        - |        - |   40072 B |
| .NET 8.0           | 10000  |   5,335.01 ns |    86.179 ns |    76.395 ns |   4.7607 |        - |        - |   40072 B |
| .NET Framework 4.8 | 100000 | 830,624.20 ns | 4,536.991 ns | 4,021.924 ns | 399.4141 | 399.4141 | 399.4141 | 1452144 B |
| .NET 7.0           | 100000 | 306,976.29 ns | 2,525.016 ns | 2,361.901 ns | 124.5117 | 124.5117 | 124.5117 |  400114 B |
| .NET 8.0           | 100000 | 169,711.96 ns | 2,405.080 ns | 2,249.713 ns | 124.7559 | 124.7559 | 124.7559 |  400114 B |

In some cases being 90% faster than .NET Framework 4.8 and more than 50% faster than .NET 7 while allocating less memory, .NET 8 is a clear winner.

ToList

| Runtime            | Size   | Mean          | Error        | StdDev       | Gen0     | Gen1     | Gen2     | Allocated |
|------------------- |------- |--------------:|-------------:|-------------:|---------:|---------:|---------:|----------:|
| .NET Framework 4.8 | 10     |     193.17 ns |     1.248 ns |     1.168 ns |   0.0446 |        - |        - |     281 B |
| .NET 7.0           | 10     |      56.20 ns |     1.022 ns |     0.906 ns |   0.0172 |        - |        - |     144 B |
| .NET 8.0           | 10     |      40.17 ns |     0.668 ns |     0.625 ns |   0.0172 |        - |        - |     144 B |
| .NET Framework 4.8 | 100    |   1,032.99 ns |     4.144 ns |     3.876 ns |   0.1984 |        - |        - |    1252 B |
| .NET 7.0           | 100    |     261.38 ns |     2.523 ns |     2.236 ns |   0.0601 |        - |        - |     504 B |
| .NET 8.0           | 100    |      97.87 ns |     1.257 ns |     1.176 ns |   0.0602 |        - |        - |     504 B |
| .NET Framework 4.8 | 1000   |   8,665.62 ns |    57.777 ns |    54.045 ns |   1.3428 |   0.0153 |        - |    8514 B |
| .NET 7.0           | 1000   |   2,291.63 ns |    13.328 ns |    11.815 ns |   0.4883 |        - |        - |    4104 B |
| .NET 8.0           | 1000   |     615.44 ns |     5.195 ns |     4.056 ns |   0.4902 |        - |        - |    4104 B |
| .NET Framework 4.8 | 10000  |  83,476.64 ns |   410.694 ns |   342.948 ns |  20.7520 |   4.0283 |        - |  131606 B |
| .NET 7.0           | 10000  |  22,781.69 ns |   200.720 ns |   177.933 ns |   4.7607 |        - |        - |   40104 B |
| .NET 8.0           | 10000  |   5,427.51 ns |    86.063 ns |    80.503 ns |   4.7836 |        - |        - |   40104 B |
| .NET Framework 4.8 | 100000 | 945,017.84 ns | 7,921.731 ns | 6,615.004 ns | 285.1563 | 285.1563 | 285.1563 | 1051184 B |
| .NET 7.0           | 100000 | 337,437.79 ns | 2,441.397 ns | 2,283.684 ns | 124.5117 | 124.5117 | 124.5117 |  400146 B |
| .NET 8.0           | 100000 | 162,577.72 ns | 1,634.437 ns | 1,364.829 ns | 124.7559 | 124.7559 | 124.7559 |  400146 B |

Once again, .NET 8 takes the gold!

Conclusion

In this article we compared the performance of ToArray versus ToList and concluded the former performs better most of the time by being faster and more memory efficient, so consider using it when creating short lived collections were enumeration must be forced.

We also concluded that .NET 8, the version still to be released, will bring fantastic performance upgrades in this regards. Not only it is significantly faster than the older versions, it also brings ToArray and ToList so close that it’s almost indifferent which method should be used.

.NET 8 — FrozenDictionary performance

2023-11-08T00:00:00.000Z

Microsoft’s upcoming release of .NET 8 will introduce a lot of new features that will certainly be welcomed by the developer community, making it an even stronger framework for application development.

One of those features is the namespace System.Collections.Frozen that introduces two new collections: FrozenDictionary and FrozenSet. These new types, as stated by Microsoft, are focused in reducing the time of read operations at the expense of increasing initialization time of immutable collections. This makes them perfect for shared data that only needs to be populated a single time, like application configurations or cached data in-memory.

In this article I’m going to benchmark the performance gains that can be achieved by using a FrozenDictionary instead of a Dictionary or an ImmutableDictionary to store shared data.

I’m going to use the well known C# library BenchmarkDotNet to run the tests and the environment will be the following:

BenchmarkDotNet v0.13.10, Windows 11 (10.0.22621.2428/22H2/2022Update/SunValley2)
AMD Ryzen 7 3700X, 1 CPU, 16 logical and 8 physical cores
.NET SDK 8.0.100-rc.2.23502.2
  [Host]   : .NET 8.0.0 (8.0.23.47906), X64 RyuJIT AVX2
  .NET 8.0 : .NET 8.0.0 (8.0.23.47906), X64 RyuJIT AVX2

For the tests, I’m going to benchmark the method TryGetValue, with one for 100% key hits and another for 100% key misses, which should give the performance for both perfect and worse scenarios. The collections FrozenDictionary, ImmutableDictionary and Dictionary will be used with a parameter setting the size.

Scenario 1 — all keys are found

For this scenario I’m going to initialize a collection of unique keys, populate all three dictionaries accordingly and then run the TryGetValue for all keys returning the latest found using the Dictionary test as the baseline.

[SimpleJob(RuntimeMoniker.Net80)]
[MemoryDiagnoser]
public class TryGetValueAllKeysFound
{
    [Params(10, 100, 1000, 10000, 100000)]
    public int Size;

    private int[] _keys;

    private Dictionary<int, int> _dictionary;
    private ImmutableDictionary<int,int> _immutableDictionary;
    private FrozenDictionary<int, int> _frozenDictionary;

    [GlobalSetup]
    public void Setup()
    {
        var random = new Random(123);

        var uniqueKeys = new HashSet<int>(Size);
        for (var i = 0; i < Size; i++)
        {
            int key;
            do
            {
                key = random.Next();
            } while (uniqueKeys.Contains(key));

            uniqueKeys.Add(key);
        }

        _dictionary = uniqueKeys.Select((key, idx) => (key, idx)).ToDictionary(e => e.key, e => e.idx);
        _immutableDictionary = uniqueKeys.Select((key, idx) => (key, idx)).ToImmutableDictionary(e => e.key, e => e.idx);
        _frozenDictionary = uniqueKeys.Select((key, idx) => (key, idx)).ToFrozenDictionary(e => e.key, e => e.idx);

        _keys = uniqueKeys.ToArray();
    }

    [Benchmark(Baseline = true)]
    public int Dictionary()
    {
        var latestValue = -1;

        foreach (var key in _keys)
        {
            if (_dictionary.TryGetValue(key, out var value))
                latestValue = value;
        }

        return latestValue;
    }

    [Benchmark]
    public int ImmutableDictionary()
    {
        var latestValue = -1;

        foreach (var key in _keys)
        {
            if (_immutableDictionary.TryGetValue(key, out var value))
                latestValue = value;
        }

        return latestValue;
    }

    [Benchmark]
    public int FrozenDictionary()
    {
        var latestValue = -1;

        foreach (var key in _keys)
        {
            if (_frozenDictionary.TryGetValue(key, out var value))
                latestValue = value;
        }

        return latestValue;
    }
}

The benchmark results are the following:

| Method              | Size   | Mean             | Error          | StdDev        | Ratio | RatioSD | Allocated | Alloc Ratio |
|-------------------- |------- |-----------------:|---------------:|--------------:|------:|--------:|----------:|------------:|
| Dictionary          | 10     |         46.29 ns |       0.300 ns |      0.251 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 10     |         35.53 ns |       0.320 ns |      0.283 ns |  0.77 |    0.01 |         - |          NA |
| FrozenDictionary    | 10     |         85.47 ns |       1.779 ns |      5.244 ns |  1.86 |    0.13 |         - |          NA |
|                     |        |                  |                |               |       |         |           |             |
| Dictionary          | 100    |        470.00 ns |       2.253 ns |      2.108 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 100    |        736.28 ns |      14.637 ns |     31.820 ns |  1.57 |    0.07 |         - |          NA |
| FrozenDictionary    | 100    |        263.18 ns |       2.898 ns |      2.569 ns |  0.56 |    0.01 |         - |          NA |
|                     |        |                  |                |               |       |         |           |             |
| Dictionary          | 1000   |      4,993.04 ns |      27.440 ns |     22.913 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 1000   |     29,174.27 ns |     493.738 ns |    461.843 ns |  5.85 |    0.10 |         - |          NA |
| FrozenDictionary    | 1000   |      2,841.24 ns |      30.283 ns |     28.326 ns |  0.57 |    0.01 |         - |          NA |
|                     |        |                  |                |               |       |         |           |             |
| Dictionary          | 10000  |     77,394.04 ns |     295.972 ns |    247.150 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 10000  |    630,488.18 ns |   3,040.379 ns |  2,695.216 ns |  8.15 |    0.05 |       1 B |          NA |
| FrozenDictionary    | 10000  |     43,957.48 ns |     274.398 ns |    256.672 ns |  0.57 |    0.00 |         - |          NA |
|                     |        |                  |                |               |       |         |           |             |
| Dictionary          | 100000 |  1,126,207.11 ns |   5,941.069 ns |  5,266.603 ns |  1.00 |    0.00 |       1 B |        1.00 |
| ImmutableDictionary | 100000 | 11,194,516.67 ns | 106,626.230 ns | 99,738.242 ns |  9.94 |    0.12 |      12 B |       12.00 |
| FrozenDictionary    | 100000 |    806,004.77 ns |   5,670.946 ns |  5,304.606 ns |  0.72 |    0.01 |       1 B |        1.00 |

As you can see, except for very small collections, the FrozenDictionary is about 43% faster than using a Dictionary, much faster than an ImmutableDictionary, without allocating more memory.

Scenario 2 — no keys are found

For this scenario I’m going to initialize a collection of unique keys, populate all three dictionaries accordingly, convert all keys to negative numbers to ensure the lookups are all different but will never match, and then run the TryGetValue for all returning the latest found using the Dictionary test as the baseline.

[SimpleJob(RuntimeMoniker.Net80)]
[MemoryDiagnoser]
public class TryGetValueNoKeysFound
{
    [Params(10, 100, 1000, 10000, 100000)]
    public int Size;

    private int[] _keys;

    private Dictionary<int, int> _dictionary;
    private ImmutableDictionary<int,int> _immutableDictionary;
    private FrozenDictionary<int, int> _frozenDictionary;

    [GlobalSetup]
    public void Setup()
    {
        var random = new Random(123);

        var uniqueKeys = new HashSet<int>(Size);
        for (var i = 0; i < Size; i++)
        {
            int key;
            do
            {
                key = random.Next();
            } while (uniqueKeys.Contains(key));

            uniqueKeys.Add(key);
        }

        _dictionary = uniqueKeys.Select((key, idx) => (key, idx)).ToDictionary(e => e.key, e => e.idx);
        _immutableDictionary = uniqueKeys.Select((key, idx) => (key, idx)).ToImmutableDictionary(e => e.key, e => e.idx);
        _frozenDictionary = uniqueKeys.Select((key, idx) => (key, idx)).ToFrozenDictionary(e => e.key, e => e.idx);

        // convert all keys to negative numbers to ensure no matches
        _keys = uniqueKeys.Select(key => -key).ToArray();
    }

    [Benchmark(Baseline = true)]
    public int Dictionary()
    {
        var latestValue = -1;

        foreach (var key in _keys)
        {
            if (_dictionary.TryGetValue(key, out var value))
                latestValue = value;
        }

        return latestValue;
    }

    [Benchmark]
    public int ImmutableDictionary()
    {
        var latestValue = -1;

        foreach (var key in _keys)
        {
            if (_immutableDictionary.TryGetValue(key, out var value))
                latestValue = value;
        }

        return latestValue;
    }

    [Benchmark]
    public int FrozenDictionary()
    {
        var latestValue = -1;

        foreach (var key in _keys)
        {
            if (_frozenDictionary.TryGetValue(key, out var value))
                latestValue = value;
        }

        return latestValue;
    }
}

The benchmark results are the following:

| Method              | Size   | Mean            | Error        | StdDev       | Ratio | RatioSD | Allocated | Alloc Ratio |
|-------------------- |------- |----------------:|-------------:|-------------:|------:|--------:|----------:|------------:|
| Dictionary          | 10     |        37.13 ns |     0.740 ns |     0.823 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 10     |        33.81 ns |     0.629 ns |     0.588 ns |  0.91 |    0.03 |         - |          NA |
| FrozenDictionary    | 10     |        19.16 ns |     0.129 ns |     0.114 ns |  0.51 |    0.01 |         - |          NA |
|                     |        |                 |              |              |       |         |           |             |
| Dictionary          | 100    |       396.11 ns |     2.697 ns |     2.522 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 100    |       488.48 ns |     2.480 ns |     2.198 ns |  1.23 |    0.01 |         - |          NA |
| FrozenDictionary    | 100    |       218.70 ns |     1.530 ns |     1.431 ns |  0.55 |    0.00 |         - |          NA |
|                     |        |                 |              |              |       |         |           |             |
| Dictionary          | 1000   |     4,019.84 ns |    38.187 ns |    35.720 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 1000   |     6,708.41 ns |    14.893 ns |    13.931 ns |  1.67 |    0.02 |         - |          NA |
| FrozenDictionary    | 1000   |     2,372.01 ns |    15.113 ns |    13.398 ns |  0.59 |    0.00 |         - |          NA |
|                     |        |                 |              |              |       |         |           |             |
| Dictionary          | 10000  |    83,803.51 ns |   232.996 ns |   206.545 ns |  1.00 |    0.00 |         - |          NA |
| ImmutableDictionary | 10000  |    88,593.46 ns |   763.681 ns |   714.347 ns |  1.06 |    0.01 |         - |          NA |
| FrozenDictionary    | 10000  |    29,071.40 ns |    85.885 ns |    76.135 ns |  0.35 |    0.00 |         - |          NA |
|                     |        |                 |              |              |       |         |           |             |
| Dictionary          | 100000 | 1,293,765.26 ns | 3,587.916 ns | 3,356.139 ns |  1.00 |    0.00 |       1 B |        1.00 |
| ImmutableDictionary | 100000 | 1,145,366.16 ns | 4,726.433 ns | 4,421.108 ns |  0.89 |    0.00 |       1 B |        1.00 |
| FrozenDictionary    | 100000 |   475,573.09 ns | 2,445.081 ns | 2,167.501 ns |  0.37 |    0.00 |         - |        0.00 |

As you can see, the FrozenDictionary is on average 47% faster than a Dictionary for all sizes and even uses less memory for bigger collections. The ImmutableDictionary, once again, is the worse performer.

Conclusion

Microsoft with the release of .NET 8 is, once again, providing a lot of performance improvements that developers can use in their applications.

For this article in particular, if you are storing key-value reference data that is immutable, populated a single time and can be shared across your application, the FrozenDictionary may be a good option if performance is of concern.

Soon I’ll also do a benchmark for FrozenSet which I expect should demonstrate similar results.

Understanding Flag Enums in C#

2023-11-04T00:00:00.000Z

Enumeration types, also known as enum types, are widely used by C# developers to improve code readability and maintainability, by offering a standardized way to represent a set of related numeric constants. Good examples are days of the week, seasons, or a predefined range of colors.

In this article I’m going to talk about flag enums, which are a special case, that can be used to represent a combination of binary choices into a single value using bitwise operations.

Imagine you were creating a simple alarm application were you could set alarms for a given time and weekdays. If you were using a simple enum, the Alarm class would need a collection to store the selected days, ideally an hash set to prevent duplicates and faster lookups. It would look similar to this:

public enum Weekday
{
    None = 0,
    Sunday,
    Monday,
    Tuesday,
    Wednesday,
    Thursday,
    Friday,
    Saturday,
}

public class Alarm
{
    public ICollection<Weekday> Weekdays { get; } = new HashSet<Weekday>();

    public TimeOnly Time { get; set; }
}

An an example, if you needed to create an alarm to set off at 7 a.m. only during workdays and needed to execute some conditional logic depending your selection, the code could be as follows:

var alarm = new Alarm
{
    Time = new TimeOnly(07, 00, 00),
    Weekdays =
    {
        Weekday.Monday,
        Weekday.Tuesday,
        Weekday.Wednesday,
        Weekday.Thursday,
        Weekday.Friday,
        Weekday.Saturday,
    }
};

// disable a flag
alarm.Weekdays.Remove(Weekday.Saturday);

// check if a flag is enabled
if (alarm.Weekdays.Contains(Weekday.Monday))
{

}

// check if some flags are enabled
if (alarm.Weekdays.Any(e => e is Weekday.Saturday or Weekday.Sunday))
{

}

// check if a flag is disabled
if (!alarm.Weekdays.Contains(Weekday.Friday))
{

}

The code is relatively simple and easy to understand but it has two drawbacks — memory allocations of new collections and constant iterations to check for flags. How can we solve this?

Introducing flag enums

Flag enums were created to optimize both memory and CPU usage by providing a way to store multiple options into a single variable.

The core concept is the following: every variable is stored in memory as binary data and CPUs are very efficient at making bitwise operations so, if you ensure each enum value is represented by a single bit that doesn’t overlap another value, you can use binary operators (AND, OR, NOT and XOR) to store multiple options into a single primitive variable.

By default, enums are represented in memory as an integer, but can also be a short or a long value. If each bit represents a different enum value, this means you can have up to 64 possible values that must not overlap each other.

Lets change the previous example to use a flag enum instead:

[Flags]
public enum Weekday
{
    None        = 0,
    Sunday      = 1 << 0, // 0b_00000001 // 1
    Monday      = 1 << 1, // 0b_00000010 // 2
    Tuesday     = 1 << 2, // 0b_00000100 // 4
    Wednesday   = 1 << 3, // 0b_00001000 // 8
    Thursday    = 1 << 4, // 0b_00010000 // 16
    Friday      = 1 << 5, // 0b_00100000 // 32
    Saturday    = 1 << 6, // 0b_01000000 // 64
}

public class Alarm
{
    public Weekday Weekdays { get; set; }

    public TimeOnly Time { get; set; }
}

As you can see, some small changes were made:

Added the Flags attribute to the enum — not a requirement, but I’ll explain later why it should be used;
Defined the value of each option ensuring no bit was overlapped — in this case I used the shift left operator to make it easier and more readable;
Removed the collection and changed the property Weekdays to a simple Weekday enum;

You may now be asking: you removed the collection and changed it to a single Weekday value, how am I supposed to represent multiple options then?

Introducing bitwise operators

As I stated before, bitwise operators (AND, OR, XOR, NOT) allow us to execute logical computation between the bits of two integral operands.

This is relevant because if we use a bitwise OR (|) operator we can store the result as an aggregation of multiple active flags. Imagine you wanted a variable representing the weekend (setting Saturday and Sunday flags):

1
2
3

var weekend = Weekday.Saturday | Weekday.Sunday;
//          = 0b_01000000 | 0b_00000001
//          = 0b_01000001

As you can see in the comment showing the binary representation, both flags will be set.

On the other hand, if you want to check if a given flag is active you can simply use the bitwise AND (&) operator and compare the result to zero (or Weekday.None).

Lets check if Sunday is part of the weekend by checking a non zero result:

var hasSunday = (weekend & Weekday.Sunday) != Weekday.None;
//            = (0b_01000001 & 0b_00000001) != 0
//            = 0b_00000001 != 0
//            = true

If you want to check if a flag is disabled the operation result must be zero:

var noMonday = (weekend & Weekday.Monday) == Weekday.None;
//           = (0b_01000001 & 0b_00000010) == 0
//           = 0b_00000000 == 0
//           = true

And finally, if you want to disable a given flag just do a bitwise AND against a negated flag value:

var sunday = weekend & ~Weekday.Saturday;
//         = 0b_01000001 & ~0b_01000000
//         = 0b_01000001 & 0b_10111111
//         = 0b_00000001

Lets update the original example and use the bitwise operators we just learned (AND, OR, NOT):

var alarm = new Alarm
{
    Time = new TimeOnly(07, 00, 00),
    Weekdays = Weekday.Monday |
               Weekday.Tuesday |
               Weekday.Wednesday |
               Weekday.Thursday |
               Weekday.Friday |
               Weekday.Saturday,
    // Weekdays = (Weekday) 0b_01111110
};

// disable a flag
alarm.Weekdays &= ~Weekday.Saturday; // (Weekday) 0b_00111110

// check if a flag is enabled
if ((alarm.Weekdays & Weekday.Monday) != 0)
{

}

// check if some flags are enabled
if ((alarm.Weekdays & (Weekday.Saturday | Weekday.Sunday)) != Weekday.None)
{

}

// check if a flag is disabled
if ((alarm.Weekdays & Weekday.Friday) == Weekday.None)
{

}

Right now you must be thinking: sure, this code is more resource efficient and performant but it certainly is harder to read… not sure if I gained something… how can I improve this?

Well, because checking if a flag is active is a very common scenario, all enums have a method called HasFlag that can be used just for that. Lets rewrite the example in a much simpler and readable way:

var alarm = new Alarm
{
    Time = new TimeOnly(07, 00, 00),
    Weekdays = Weekday.Monday |
               Weekday.Tuesday |
               Weekday.Wednesday |
               Weekday.Thursday |
               Weekday.Friday |
               Weekday.Saturday,
};

alarm.Weekdays &= ~Weekday.Saturday;

if (alarm.Weekdays.HasFlag(Weekday.Monday))
{

}

if (alarm.Weekdays.HasFlag(Weekday.Saturday) || alarm.Weekdays.HasFlag(Weekday.Sunday))
{

}

if (!alarm.Weekdays.HasFlag(Weekday.Friday))
{

}

It would be nice to also have a method to disable a flag but none is provided by the framework, so you’ll have to stick with bitwise operators for that scenario.

Why the [Flags] attribute?

Earlier I said marking the enum with a Flags attribute is opcional (everything we talked about will still work) but still recommended because it helps the IDE to give you more detailed warnings or suggestions, but it’s specially important for debugging, parsing or converting to a string representation.

Imagine the weekend scenario were both Saturday and Sunday flags are set. If the enum doesn’t have the Flags attribute and you go inspect the variable, the IDE will show the value 65 (0b_01000001) because it isn’t defined in the enum. Same behavior for the ToString method, that will return "65":

If on the contrary the Flags attribute is used, both IDE and ToString method will show a proper representation of what flags are active:

Conclusion

I hope this article gave you a good idea on how to use flag enums and bitwise operations to store and check for active flags using a single field, making your application more resource efficient without losing code readability.

Immutability and Entity Framework Core

2022-08-12T23:00:00.000Z

Nowadays, when implementing a .NET application that works directly with a database (relational or not), most developers will chose Entity Framework Core to abstract their data layer and work directly with entity classes.

It has become an integral part of the .NET ecosystem, just like ASP.NET, and it is extremely rare finding someone that never worked with it. I’ve been using it myself ever since version 4 (along with other ORMs) and I must say that it aged like a fine wine.

Fully open sourced, with support for multiple databases (not just SQL Server) while offering relatively optimized and extensible conversion from LINQ to database queries, accessing data from a .NET application never been easier. And when it doesn’t support something, just integrate with some micro ORM and go crazy on that SQL!

One core feature is the implementation of the unit of work pattern by supporting, what is usually called, a first level cache. Load a bunch of entities from the database, that will be tracked in memory by the context, mutate or delete them, create new ones and then flush everything in a single database access.

The thing about this feature, despite working fine most of the time, is that it depends on managing internal state with mutable entities. After all, it was originally focused on C# developers that were used to work in a object-oriented way — get an entity, change some properties, request an update.

But what if you are a C# developer and prefer the advantages provided by immutability?

Lets look at the most used immutable class in the .NET world — the string.

We all know that working with text can be memory inefficient if badly managed, but imagine a world were you could initialize a string with the name “Bruce Wayne”, pass it as an argument to some method that was supposed to count how many words were in it, and when you realize, your original string contains the name “Peter Parker” because the strings were mutable and nothing could prevent that?

In this article I won’t enter into details about the advantages of immutable over mutable objects, and vice versa. There are great articles already explaining both visions and we all know no size fits all, so it kinda depends of your current needs.

But I’m going to explain how you can use immutable entities directly with Entity Framework Core so you know that not only it is possible but also a viable option.

Immutable entities in C#

Before C# 9 the only way to create an immutable entity was to define a class or structure with getter only properties that were initialized during object construction, ensuring nothing could be changed afterwards.

As an example, a PersonEntity would look like this:

public class PersonEntity
{
    public PersonEntity(string forename, string surname, string? middleNames = null, DateOnly? birthdate = null)
    {
        Forename = forename;
        Surname = surname;
        MiddleNames = middleNames;
        Birthdate = birthdate;
    }

    public string Forename { get; }

    public string Surname { get; }

    public string? MiddleNames { get; }

    public DateOnly? Birthdate { get; }
}

It works as expected but there is one major problem: just by looking at the code, the developer cannot tell which properties are being set unless argument names are used and, if it wants to change something, it must copy every property by hand.

var person = new PersonEntity(
    "Bruce",
    "Wayne"
);
person = new PersonEntity(
    person.Forename,
    person.Surname,
    "Thomas",
    new DateOnly(1972, 02, 19)
);

For small POCOs this may not be a problem, but for bigger ones the chances of someone making a mistake increases.

With this in mind, Microsoft implemented init only setters supporting object initializers while still preventing changes afterwards. Couple this with record types, and creating immutable entities has never been easier in C#.

The same PersonEntity, but now using both of these features:

public record PersonEntity
{
    public string Forename { get; init; }

    public string Surname { get; init; }

    public string? MiddleNames { get; init; }

    public DateOnly? Birthdate { get; init; }
}

Not only the syntax is more concise by using auto-implemented properties, you can now easily tell which properties are being set during initialization and have a much easier life copying data by using the keyword with and only state which properties must change.

var person = new PersonEntity
{
    Forename = "Bruce",
    Surname = "Wayne",
};
person = person with
{
    MiddleNames = "Thomas",
    Birthdate = new DateOnly(1972, 02, 19),
};

Change Tracking and immutability

Every developer that uses Entity Framework knows it provides a lot of database abstractions to enable working directly with .NET objects.

One core feature is the automatic detection of changes made to entities. This usually means interacting with the context to get an existing entity, change some properties and then invoke SaveChangesAsync which will generate a bunch of instructions and execute them into the database. Under the hood, when the entity is retrieved from the context it will keep a reference to the instance and original values from the database and when the developer requests the context to save changes, all properties of tracked entities will be compared and if anything changed, instructions will be generated and executed.

This works well for mutable entities but we are implementing immutability, and since no changes will be made to tracked entities, will this cause any issues?

Let’s imagine the following use case:

You retrieve our Bruce Wayne from the database using an EF Core context, which internally will keep a reference to it;
You want to change it’s birthdate, so you clone it while assigning a new date;
If you invoke SaveChangesAsync, nothing will happen because no changes happened to the original entity;
If you invoke Update, an InvalidOperationException will be thrown because the context is already tracking an entity with the same primary key;

Certainly invoking SaveChangesAsync and nothing happening was expected, after all we created a copy of the original instance, which EF Core knows nothing about and would never automatically detect changes, but why the exception when trying to attach the entity to the context?

This leads to another EF Core feature, called Identity Resolution, strongly correlated to our change tracking.

Identity Resolution ensures the same entity is retrieved for the same primary key while being tracked. This is a requirement when implementing the Unit of Work pattern because EF Core only flushes data when SaveChangesAsync is invoked.

Again, let’s imagine our PersonEntity was a mutable class:

You retrieve our Bruce Wayne from the database using an EF Core context, which internally will keep a reference to it, also identified by its primary key;
You change its birthdate;
You do some more work;
You try to get it again from the EF Core context but since that primary key its already being tracked, it returns the same instance instead of going to the database and returning old data for your Unit of Work operation;
You change more properties;
Invoke SaveChangesAsync, flushing changes and now both the instance and database have the same data;

As you can see, Identity Resolution is important for mutable entities, but not so much for our use case and it’s a problem we must solve.

The project

It seems the only thing preventing an immutable approach to database access while using EF Core is not relying on Change Tracking for mutations while preventing Identity Resolution problems.

Let’s create a C# console application that will use Entity Framework Core to store data into a SQLite database, using immutable record entities.

The source code is available on GitHub, feel free to give it a look.

Setup

Start by opening Visual Studio and creating a .NET 6.0 Console Application with a name at any location you prefer.

Install most recent versions of Entity Framework Core for SQLite and Microsoft hosting nugets:

Microsoft.Extensions.Hosting
Microsoft.EntityFrameworkCore.Sqlite

Create a ProgramHost class implementing IHostedService. This class will run our exemple code, but for now just inject a logger and write something inside the StartAsync method. We’ll do nothing in the StopAsync method, so just return a completed task.

public class ProgramHost : IHostedService
{
    private readonly ILogger<ProgramHost> _logger;

    public ProgramHost(
        ILogger<ProgramHost> logger
    )
    {
        _logger = logger;
    }

    public async Task StartAsync(CancellationToken ct)
    {
        _logger.LogInformation("I'm alive!");
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

Open the Program.cs file, build an host with our ProgramHost class registered as a hosted service.

using var host = Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddHostedService<ProgramHost>();
    })
    .Build();

await host.RunAsync();

If you configured everything correctly and run the application, you should see something like this:

The database model

For simplicity, we’ll have a single Persons table:

Id — identity column to uniquely identify the row (required);
Forename — stores the first name (text, required);
Surname — stores the last name (text, required);
MiddleNames — stores the middle names (text, optional);
Birthdate — stores the date of birth (date, optional);

When representing database entities, I always create a base class containing properties to be defined in all entities (like the unique identifier or some metadata columns), and for the rest I always use positional records syntax for required properties and auto-properties for optional ones, making clear to the developer which ones must be always provided (this also removes compiler warnings if the project is configured for nullable reference types).

/// <summary>
/// Base class for all database entities
/// </summary>
public abstract record Entity
{
    /// <summary>
    /// Unique identifier
    /// </summary>
    public long Id { get; init; }
}

/// <summary>
/// Representation of a person
/// </summary>
/// <param name="Forename">Person first name</param>
/// <param name="Surname">Person last name</param>
public record PersonEntity(
    string Forename,
    string Surname
) : Entity
{
    /// <summary>
    /// Person middle names, separated by spaces
    /// </summary>
    public string? MiddleNames { get; init; }

    /// <summary>
    /// Person date of birth
    /// </summary>
    public DateOnly? Birthdate { get; init; }
}

If you prefer to keep everything more compact, feel free to use positional records with default values for optional properties.

public record PersonEntity(
    string Forename,
    string Surname,
    string? MiddleNames = null,
    DateOnly? Birthdate = null
) : Entity;

This is the most compact syntax, but be careful when adding new optional properties if your are sharing records across multiple applications. It will also be considered a breaking change unless you define both constructors, effectively losing this compact syntax. That’s the reason I don’t use positional record syntax for everything, but it kinda depends on your needs.

Now, lets create our EF Core context with Persons table mappings.

public class SampleDbContext : DbContext
{
    public SampleDbContext(DbContextOptions<SampleDbContext> options)
        : base(options)
    {

    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);

        builder.Entity<PersonEntity>(cfg =>
        {
            cfg.ToTable("Persons");
            cfg.HasKey(e => e.Id);
            cfg.Property(e => e.Id)
                .IsRequired()
                .ValueGeneratedOnAdd();
            cfg.Property(e => e.Forename)
                .IsRequired()
                .HasMaxLength(64);
            cfg.Property(e => e.Surname)
                .IsRequired()
                .HasMaxLength(64);
            cfg.Property(e => e.MiddleNames)
                .HasMaxLength(256);
            cfg.Property(e => e.Birthdate);
        });
    }
}

Open the Program.cs file and register the EF Core context into the container. This is a test console, so I’ll use the temporary folder to store the SQLite file but feel free to use any other location and file name.

using var host = Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddDbContext<SampleDbContext>(options =>
        {
            var connectionString = new SqliteConnectionStringBuilder
            {
                DataSource = Path.Combine(
                    Path.GetTempPath(),
                    "efcore-immutability-sample.sqlite3"
                )
            }.ConnectionString;
            options.UseSqlite(connectionString);
        });
        services.AddHostedService<ProgramHost>();
    })
    .Build();

await host.RunAsync();

Now inject the context into the ProgramHost class and, since this is a test console and we want to freely modify our entities without much thought, change the StartAsync method to always drop and recreate the database on startup.

public class ProgramHost : IHostedService
{
    private readonly ILogger<ProgramHost> _logger;
    private readonly SampleDbContext _context;

    public ProgramHost(
        ILogger<ProgramHost> logger,
        SampleDbContext context
    )
    {
        _logger = logger;
        _context = context;
    }

    public async Task StartAsync(CancellationToken ct)
    {
        _logger.LogDebug("Ensuring database is in a clean state");
        await _context.Database.EnsureDeletedAsync(ct);
        await _context.Database.EnsureCreatedAsync(ct);
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

If you run the application and open the SQLite database file (using DB Browser for SQLite or equivalent), both a Persons and sqlite_sequence tables should be defined.

Configuring for immutability

Now that we have a working solution lets recall what we need to achieve to support immutability:

Not relying on Change Tracking to know which instructions must be executed when SaveChangesAsync is invoked;
Preventing Identity Resolution exceptions;

Because Change Tracking is such a core feature in Entity Framework Core, you can only disable it when querying for entities.

As stated in Microsoft documentation, we can disable it in three ways:

Using extension method AsNoTracking for each query;
Setting context property ChangeTracker.QueryTrackingBehavior to NoTracking;
Global configuration with method UseQueryTrackingBehavior;

Open Program.cs file and disable it globally, ensuring will never be tracked when queried from the database.

using var host = Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddDbContext<SampleDbContext>(options =>
        {
            var connectionString = new SqliteConnectionStringBuilder
            {
                DataSource = Path.Combine(
                    Path.GetTempPath(),
                    "efcore-immutability-sample.sqlite3"
                )
            }.ConnectionString;
            options.UseSqlite(connectionString)
                .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking);
        });
        services.AddHostedService<ProgramHost>();
    })
    .Build();

await host.RunAsync();

In theory, if you only made a single entity operation per unit of work, like getting a person by unique identifier, changing its middle names and doing an update, this configuration would be enough.

Sadly we all know development is far from perfect and more complex applications, due to business requirements, may lead to multiple updates to the same data in a single unit of work operation. That’s one of the major reasons behind Change Tracking in EF Core, to implement the unit of work pattern while not relying on database ACID implementations and reducing the time transactions stays open.

This means every time an entity is added, updated or removed using the context, an internal reference will be kept and Identity Resolution exceptions will be thrown if someone tries to attach an entity with the same id.

There are multiple ways to solve this problem but the easiest one is to enforce a transaction, flush changes to the database every time a create, update or delete is requested and then detach the entity.

Since this is a proof of concept application, I’m going to implementing this behavior with extension methods over DbContext instances, but feel free to wrap it into a repository pattern or any way you prefer.

Create a static class DbContextExtensions and implement a generic extension that will receive an entity and the state to be tracked, returning an updated entity.

public static class DbContextExtensions
{
    public static async Task<TEntity> SaveEntityStateAsync<TEntity>(
        this DbContext context,
        TEntity entity,
        EntityState state,
        CancellationToken ct
    ) where TEntity : Entity
    {
        if (context == null) throw new ArgumentNullException(nameof(context));
        if (entity == null) throw new ArgumentNullException(nameof(entity));

        var entry = context.Entry(entity);
        entry.State = state;

        await context.SaveChangesAsync(ct);

        entry.State = EntityState.Detached;

        return entry.Entity;
    }
}

The method creates an EntityEntry<TEntity>, changes the state to the one provided and immediately requests to flush changes. Because the context is now tracking the entity, it will execute a database instruction based on the entry state (Added|Modified|Deleted). Then, it detaches the entity right before returning to prevent Identity Resolution exceptions on future mutations and returns the entity with the most recent values (usefull to get values generated by the database, like an identity column).

Open the ProgramHost class and create some test code using the extension method and the immutable PersonEntity. In this case I’m creating Bruce Wayne and then updating both birthdate and middle name.

public class ProgramHost : IHostedService
{
    private readonly ILogger<ProgramHost> _logger;
    private readonly SampleDbContext _context;

    public ProgramHost(
        ILogger<ProgramHost> logger,
        SampleDbContext context
    )
    {
        _logger = logger;
        _context = context;
    }

    public async Task StartAsync(CancellationToken ct)
    {
        _logger.LogDebug("Setting database to a clean state");
        await _context.Database.EnsureDeletedAsync(ct);
        await _context.Database.EnsureCreatedAsync(ct);

        _logger.LogDebug("Creating an explicit database transaction");
        await using var tx = await _context.Database.BeginTransactionAsync(ct);

        _logger.LogDebug("Adding person");
        var person = await _context.SaveEntityStateAsync(new PersonEntity(
            Forename: "Bruce",
            Surname: "Wayne"
        ), EntityState.Added, ct);

        _logger.LogDebug("Updating person's birthdate");
        await _context.SaveEntityStateAsync(person with
        {
            MiddleNames = "Thomas",
            Birthdate = new DateOnly(1972, 02, 19)
        }, EntityState.Modified, ct);

        _logger.LogDebug("Commiting database transaction");
        await tx.CommitAsync(ct);
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

If you execute the code, you’ll see database instructions being sent to SQLite by Entity Framework Core to insert and then update the entity.

Open the SQLite file and you’ll see Bruce Wayne was both created and updated with a birthdate and middle name.

Certainly you don’t want to be writing EntityState.Added|Updated|Deleted every time an entity needs to be manipulated, so lets create dedicated extensions for each operation and update your test code.

Change the method to private and implement a CreateAsync, UpdateAsync and DeleteAsync extension methods that will reuse the existing one.

public static class DbContextExtensions
{
    public static async Task<TEntity> CreateAsync<TEntity>(
        this DbContext context,
        TEntity entity,
        CancellationToken ct
    ) where TEntity : Entity => await context.SaveEntityStateAsync(
        entity,
        EntityState.Added,
        ct
    );

    public static async Task<TEntity> UpdateAsync<TEntity>(
        this DbContext context,
        TEntity entity,
        CancellationToken ct
    ) where TEntity : Entity => await context.SaveEntityStateAsync(
        entity,
        EntityState.Modified,
        ct
    );

    public static async Task DeleteAsync<TEntity>(
        this DbContext context,
        TEntity entity,
        CancellationToken ct
    ) where TEntity : Entity => await context.SaveEntityStateAsync(
        entity,
        EntityState.Deleted,
        ct
    );

    private static async Task<TEntity> SaveEntityStateAsync<TEntity>(
        this DbContext context,
        TEntity entity,
        EntityState state,
        CancellationToken ct
    ) where TEntity : Entity
    {
        if (context == null) throw new ArgumentNullException(nameof(context));
        if (entity == null) throw new ArgumentNullException(nameof(entity));

        var entry = context.Entry(entity);
        entry.State = state;

        await context.SaveChangesAsync(ct);

        entry.State = EntityState.Detached;

        return entry.Entity;
    }

Use the new methods in our ProgramHost class.

public class ProgramHost : IHostedService
{
    private readonly ILogger<ProgramHost> _logger;
    private readonly SampleDbContext _context;

    public ProgramHost(
        ILogger<ProgramHost> logger,
        SampleDbContext context
    )
    {
        _logger = logger;
        _context = context;
    }

    public async Task StartAsync(CancellationToken ct)
    {
        _logger.LogDebug("Setting database to a clean state");
        await _context.Database.EnsureDeletedAsync(ct);
        await _context.Database.EnsureCreatedAsync(ct);

        _logger.LogDebug("Creating an explicit database transaction");
        await using var tx = await _context.Database.BeginTransactionAsync(ct);

        _logger.LogDebug("Adding person");
        var person = await _context.CreateAsync(new PersonEntity(
            Forename: "Bruce",
            Surname: "Wayne"
        ), ct);

        _logger.LogDebug("Updating person's birthdate");
        await _context.UpdateAsync(person with
        {
            MiddleNames = "Thomas",
            Birthdate = new DateOnly(1972, 02, 19)
        }, ct);

        _logger.LogDebug("Commiting database transaction");
        await tx.CommitAsync(ct);
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

Conclusion

I hope this article gave you a good idea on how to use Entity Framework Core to abstract your application from the database while still implementing the immutable design pattern to manage application state.

There are both advantages and disadvantages of using immutable entities over mutable ones, after all no size fits all, but I think its nice to know you have the option to use it without sacrificing productivity by having to implement database access yourself. As long you ensure Change Tracking is disabled for all queries and every code uses your abstractions to create, update or delete entities, everything will work just fine.

Just a small note about explicit database transactions. If you are implementing an ASP.NET Core application and using the mediator pattern, some time ago I created a bunch of articles and one of them provided an approach to manage Entity Framework Core transactions globally using a pipeline. I use that approach all the time, you may find it helpful too.

Integrating Dapper with Entity Framework Core

2021-03-09T00:00:00.000Z

Nowadays it is extremely rare to implement an application without using any sort of library for Object-Relational Mapping (ORM) to reduce development time by removing the need to implement a lot of boilerplate code to access a database. In the .NET world that usually means using Entity Framework Core or NHibernate both offering strong tooling for CRUD operations, data type conversions, strong typed queries using LINQ with IQueryable and so on.

Despite the pros of using an ORM there are also some cons that, while may not prevent them to be widely used inside an application, they may need to be replaced in some areas either for performance reasons or limitations. This usually means working directly with ADO.NET (oh hell no!) or use Micro ORM libraries, like Dapper, that are focused on performance and providing a simpler way to map database queries into objects.

In this article I’m going to demonstrate how Dapper can easily be integrated with Entity Framework Core (and probably with any other ORM) without using TransactionScope, while trying to keep the same contracts via extension methods to DbContext instances and ensuring the SQL is properly logged in a similar way to what EF Core usually does.

Dapper Requirements

To work with Dapper, the only requirements are a DbConnection, the SQL text, and some optional parameters, like a DbTransaction, command timeout, query parameters and so on. Sometimes is is also necessary to globally register some custom TypeHandler<T> for the when it can’t convert a given database type to its CLR representation.

Assuming we want to execute a simple SELECT @SomeParameter statement via Dapper, what code we must implement to get everything we need from a DbContext?

// get the underline DbConnection
var connection = context.Database.GetDbConnection();

// get the underline DbTransaction, if any
var transaction = context.Database.CurrentTransaction?.GetDbTransaction();

// get the currently configured command timeout
var commandTimeout = context.Database.GetCommandTimeout();

// create a Dapper CommandDefinition
var command = new CommandDefinition(
    "SELECT @SomeParameter",
    new
    {
        SomeParameter = 1
    },
    transaction,
    commandTimeout,
    cancellationToken: ct
);

var _ = await connection.QueryAsync<int>(command);

As shown, the database facade has everything we need to make Dapper work but there is a caveat that must be properly addressed:

Dapper always executes the SQL immediately into the database, which means it won’t detect changes made on tracked entities before SaveChanges is invoked and it won’t wait to flush changes either, so be very careful when managing database access.

My recommendation is to always open a transaction explicitly via context.Database.BeginTransactionAsync before running any mutation.

If you are using the mediator pattern, I recommend my previous article that explains how to create a mediator pipeline that enforces database transactions when handling commands.

With all of this in mind, lets implement an example project that showcases what we just talked about.

The project

The source code for this article can be found on GitHub.

Start by opening Visual Studio and creating an ASP.NET Core Web Application with a name and a location at your preference.

Choose an empty project since this is just a demo and we are going to setup only the required dependencies.

Install the Nuget Swashbuckle.AspNetCore:

Open the Startup.cs file and configure both MVC and Swagger so we can use its UI to test our endpoints more easily.


public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

        app.UseSwagger();

        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "EF Core with Dapper Example Api V1");
        });

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

The Web API

Since the objective of this article is to show how Dapper can be integrated with Entity Framework Core, we are going to create a simple endpoint to manage products:

GET /products — lists products, including their current price and last date when it has changed;
POST /products — creates a product with a given price;

The Database Model

We need a SQL database to run our queries so, to simplify our setup, we are going to use the SQLite provider for Entity Framework Core and configure it as an in-memory instance.

Install the Nuget Microsoft.EntityFrameworkCore.Sqlite:

Create a Database folder and inside create entities for products and price history, both mapped into an Entity Framework context:

public class ApiDbContext : DbContext
{
    public ApiDbContext(DbContextOptions<ApiDbContext> options) : base(options)
    {

    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);

        builder.Entity<ProductEntity>(cfg =>
        {
            cfg.ToTable("Product");
            cfg.HasKey(e => e.Id);
            cfg.HasAlternateKey(e => e.ExternalId);
            cfg.HasIndex(e => e.Code).IsUnique();
            cfg.Property(e => e.Id)
                .IsRequired()
                .ValueGeneratedOnAdd();
            cfg.Property(e => e.ExternalId)
                .IsRequired();
            cfg.Property(e => e.Code)
                .IsRequired()
                .HasMaxLength(8);
            cfg.Property(e => e.Name)
                .IsRequired()
                .HasMaxLength(128);
        });

        builder.Entity<PriceHistoryEntity>(cfg =>
        {
            cfg.ToTable("PriceHistory");
            cfg.HasKey(e => e.Id);
            cfg.HasIndex(e => e.CreatedOn);
            cfg.Property(e => e.Id)
                .IsRequired()
                .ValueGeneratedOnAdd();
            cfg.HasOne(e => e.Product)
                .WithMany(p => p.PricesHistory)
                .IsRequired();
            cfg.Property(e => e.Price)
                .IsRequired();
            cfg.Property(e => e.CreatedOn)
                .IsRequired();
        });
    }
}

public class ProductEntity
{
    public long Id { get; set; }
    public Guid ExternalId { get; set; }
    public string Code { get; set; }
    public string Name { get; set; }
    public virtual ICollection<PriceHistoryEntity> PricesHistory { get; set; }

    public ProductEntity()
    {
        PricesHistory = new HashSet<PriceHistoryEntity>();
    }
}

public class PriceHistoryEntity
{
    public long Id { get; set; }
    public virtual ProductEntity Product { get; set; }
    public decimal Price { get; set; }
    public DateTime CreatedOn { get; set; }
}

Open the Startup.cs file and add the database context to the container. Because the database is stored in-memory, we must ensure all tables are created when the application starts and at least one connection is always open so the SQLite provider won’t discard it from memory:

public class Startup
{
    private const string ConnectionString = "Data Source=EntityFrameworkCoreWithDapper;Mode=Memory;Cache=Shared";
    private static SqliteConnection _keepAliveConnection;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseSqlite(ConnectionString);
        });

        // ...
    }

    public void Configure(IApplicationBuilder app)
    {
        // this ensures at least one connection is open and the database is kept in-memory while the application is running
        _keepAliveConnection = new SqliteConnection(ConnectionString);
        keepAliveConnection.Open();

        using (var scope = app.ApplicationServices.GetRequiredService<IServiceScopeFactory>().CreateScope())
        {
            var ctx = scope.ServiceProvider.GetRequiredService<ApiDbContext>();
            ctx.Database.EnsureCreated();
        }

        // ...
    }
}

The Products Controller

Now that we have configured the database, create a Controllers folder, the ProductsController class and its models. For now, we are going to implement our logic using only the Entity Framework context.

[Route("products")]
public class ProductsController : ControllerBase
{
    private readonly ApiDbContext _context;

    public ProductsController(ApiDbContext context)
    {
        _context = context;
    }

    [HttpGet]
    public async Task<IEnumerable<ProductModel>> GetAllAsync([FromQuery] int? skip, [FromQuery] int? take, CancellationToken ct)
    {
        return await (
                from p in _context.Set<ProductEntity>()
                select new
                {
                    Id = p.ExternalId,
                    p.Code,
                    p.Name,
                    MostRecentPriceHistory = p
                        .PricesHistory
                        .OrderByDescending(ph => ph.CreatedOn)
                        .First()
                }
            )
            .OrderBy(p => p.Code)
            .Skip(skip ?? 0)
            .Take(take ?? 20)
            .Select(p => new ProductModel
            {
                Id = p.Id,
                Code = p.Code,
                Name = p.Name,
                Price = p.MostRecentPriceHistory.Price,
                PriceChangedOn = p.MostRecentPriceHistory.CreatedOn
            })
            .ToListAsync(ct);
    }

    [HttpPost]
    public async Task<CreateProductResultModel> CreateAsync([FromBody] CreateProductModel model, CancellationToken ct)
    {
        var externalId = Guid.NewGuid();
        
        await using var tx = await _context.Database.BeginTransactionAsync(ct);

        var product = new ProductEntity
        {
            ExternalId = externalId,
            Code = model.Code,
            Name = model.Name,
            PricesHistory =
            {
                new PriceHistoryEntity
                {
                    Price = model.Price,
                    CreatedOn = DateTime.UtcNow
                }
            }
        };

        await _context.Set<ProductEntity>().AddAsync(product, ct);

        await _context.SaveChangesAsync(ct);
        
        await tx.CommitAsync(ct);

        return new CreateProductResultModel
        {
            Id = externalId
        };
    }
}

public class CreateProductModel
{
    public string Code { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public DateTime PriceChangedOn { get; set; }
}

public class CreateProductResultModel
{
    public Guid Id { get; set; }
}

Right now, the project content should look as follows:

Dapper Integration

Now that we have a running API that manages products and their prices using Entity Framework Core, we can now integrate Dapper into the solution and apply what we learned at the start of this article.

Install the Nuget Dapper:

Since Dapper uses extension methods over IDbConnection and we can extract everything needed from a DbContext instance (even an ILogger to log our raw SQL), lets keep that philosophy and replicate those extension methods but this time to an Entity Framework Core context.

Inside the Database folder create a static DapperDbContextExtensions class, that will containing all the extension methods, and a DapperEFCoreCommand structure, used to wrap both logging and Dapper’s CommandDefinition.

For demo purposes we are only going to expose methods to query a collection of items and to execute commands but feel free to add your owns (like FirstAsync). I also put the CancellationToken at the start since all other parameters are optional and I have my fair share of cancellation tokens being passed as the object parameters, but change them in a way that makes more sense to you.

public static class DapperDbContextExtensions
{
    public static async Task<IEnumerable<T>> QueryAsync<T>(
        this DbContext context,
        CancellationToken ct,
        string text,
        object parameters = null,
        int? timeout = null,
        CommandType? type = null
    )
    {
        using var command = new DapperEFCoreCommand(
            context,
            text,
            parameters,
            timeout,
            type,
            ct
        );

        var connection = context.Database.GetDbConnection();
        return await connection.QueryAsync<T>(command.Definition);
    }

    public static async Task<int> ExecuteAsync(
        this DbContext context,
        CancellationToken ct,
        string text,
        object parameters = null,
        int? timeout = null,
        CommandType? type = null
    )
    {
        using var command = new DapperEFCoreCommand(
            context,
            text,
            parameters,
            timeout,
            type,
            ct
        );

        var connection = context.Database.GetDbConnection();
        return await connection.ExecuteAsync(command.Definition);
    }
}

public readonly struct DapperEFCoreCommand : IDisposable
{
    private readonly ILogger<DapperEFCoreCommand> _logger;

    public DapperEFCoreCommand(
        DbContext context,
        string text,
        object parameters,
        int? timeout,
        CommandType? type,
        CancellationToken ct
    )
    {
        _logger = context.GetService<ILogger<DapperEFCoreCommand>>();

        var transaction = context.Database.CurrentTransaction?.GetDbTransaction();
        var commandType = type ?? CommandType.Text;
        var commandTimeout = timeout ?? context.Database.GetCommandTimeout() ?? 30;

        Definition = new CommandDefinition(
            text,
            parameters,
            transaction,
            commandTimeout,
            commandType,
            cancellationToken: ct
        );

        if (_logger.IsEnabled(LogLevel.Debug))
        {
            _logger.LogDebug(
                @"Executing DbCommand [CommandType='{commandType}', CommandTimeout='{commandTimeout}']
{commandText}", Definition.CommandType, Definition.CommandTimeout, Definition.CommandText);
        }
    }

    public CommandDefinition Definition { get; }

    public void Dispose()
    {
        if (_logger.IsEnabled(LogLevel.Information))
        {
            _logger.LogInformation(
                @"Executed DbCommand [CommandType='{commandType}', CommandTimeout='{commandTimeout}']
{commandText}", Definition.CommandType, Definition.CommandTimeout, Definition.CommandText);
        }
    }
}

Since we are using Guid properties in our models but they are stored as TEXT and Dapper doesn’t know how to do the conversion when reading from a SQLite database, we also need to add a global type handler.

Open the Startup.cs file, create an inner class GuidTypeHandler, that will parse the string into a Guid, and register the handler on application startup:

public class Startup
{
    // ...

    public void ConfigureServices(IServiceCollection services)
    {
        SqlMapper.AddTypeHandler(new GuidTypeHandler());
        
        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseSqlite(ConnectionString);
        }).AddTransient<ApiDbSqlRunner>();

        // ...
    }

    // ...
    
    private class GuidTypeHandler : SqlMapper.TypeHandler<Guid>
    {
        public override void SetValue(IDbDataParameter parameter, Guid value) => parameter.Value = value;

        public override Guid Parse(object value) => Guid.Parse((string) value);
    }
}

Optimizations with Dapper

As stated before, Entity Framework will usually make it easier to access the database and remove some of the boilerplate code but, like most advanced frameworks, it has some drawbacks, specially performance degradation that sometimes can’t be ignored in critical paths.

Lets analyse each endpoint and see if we can improve both the generated SQL and the total of database interactions.

POST /products

This endpoint is responsible to create a product with a given initial price. Because prices are stored in a history table, being the most recent entry the current product price, this action has to insert both a line in the products and price history tables.

If we look at the logs we can see two commands being executed by the Entity Framework with a total of four operations:

info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (6ms) [Parameters=[@p0='?' (Size = 8), @p1='?', @p2='?' (Size = 16)], CommandType='Text', CommandTimeout='30']
      INSERT INTO "Product" ("Code", "ExternalId", "Name")
      VALUES (@p0, @p1, @p2);
      SELECT "Id"
      FROM "Product"
      WHERE changes() = 1 AND "rowid" = last_insert_rowid();
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (1ms) [Parameters=[@p3='?', @p4='?', @p5='?'], CommandType='Text', CommandTimeout='30']
      INSERT INTO "PriceHistory" ("CreatedOn", "Price", "ProductId")
      VALUES (@p3, @p4, @p5);
      SELECT "Id"
      FROM "PriceHistory"
      WHERE changes() = 1 AND "rowid" = last_insert_rowid();

This happens because Entity Framework and the SQLite provider don’t know what our code needs from each entity after an insert, so the only option is to execute a command that does the insert, selects database generated columns, and update properties of the tracked instances, in this case, the primary keys.

Since we know our code doesn’t need anything from the database, because we are only returning the product external id that was calculated inside the controller, we can execute a single SQL statement containing both inserts:

INSERT INTO Product (ExternalId, Code, Name)
VALUES (@ExternalId, @Code, @Name);
INSERT INTO PriceHistory (Price, CreatedOn, ProductId)
SELECT @Price, @CreatedOn, Id
FROM Product
WHERE
    rowid = last_insert_rowid();

Change the CreateAsync action to use the extension method ExecuteAsync with this statement, passing the arguments. Keep in mind that SQLite is case sensitive when parsing the parameter name, so you must ensure the anonymous object property names match with the ones inside the statement:

[Route("products")]
public class ProductsController : ControllerBase
{
    // ...

    [HttpPost]
    public async Task<CreateProductResultModel> CreateAsync([FromBody] CreateProductModel model, CancellationToken ct)
    {
        var externalId = Guid.NewGuid();
        
        await using var tx = await _context.Database.BeginTransactionAsync(ct);

        await _context.ExecuteAsync(ct, @"
INSERT INTO Product (ExternalId, Code, Name)
VALUES (@ExternalId, @Code, @Name);
INSERT INTO PriceHistory (Price, CreatedOn, ProductId)
SELECT @Price, @CreatedOn, Id
FROM Product
WHERE
    rowid = last_insert_rowid();", new
        {
            ExternalId = externalId,
            model.Code,
            model.Name,
            model.Price,
            CreatedOn = DateTime.UtcNow
        });
        
        await tx.CommitAsync(ct);

        return new CreateProductResultModel
        {
            Id = externalId
        };
    }

    // ...
}

Remember that, even if we are executing a single command in the database, it contains two instructions so it still must be wrapped by an explicit database transaction.

When creating a new product using the Swagger UI endpoint (https://localhost:44310/swagger/index.html), if you look at your Visual Studio output console, a log similar to the following should appear showing the custom SQL:

dbug: EntityFrameworkCoreWithDapper.Database.DapperEFCoreCommand[0]
      Executing DbCommand [CommandType='Text', CommandTimeout='30']
      
      INSERT INTO Product (ExternalId, Code, Name)
      VALUES (@ExternalId, @Code, @Name);
      
      INSERT INTO PriceHistory (Price, CreatedOn, ProductId)
      SELECT @Price, @CreatedOn, Id
      FROM Product
      WHERE
          rowid = last_insert_rowid();
info: EntityFrameworkCoreWithDapper.Database.DapperEFCoreCommand[0]
      Executed DbCommand [CommandType='Text', CommandTimeout='30']
      
      INSERT INTO Product (ExternalId, Code, Name)
      VALUES (@ExternalId, @Code, @Name);
      
      INSERT INTO PriceHistory (Price, CreatedOn, ProductId)
      SELECT @Price, @CreatedOn, Id
      FROM Product
      WHERE
          rowid = last_insert_rowid();

GET /products

This endpoint is responsible for returning a paginated collections of products with their current price and the timestamp when it was last updated, ordered by product code.

Lets extract the SQL statement generated by the Entity Framework Core from the logs:

info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (3ms) [Parameters=[@__p_1='?', @__p_0='?'], CommandType='Text', CommandTimeout='30']
      SELECT "p1"."ExternalId" AS "Id", "p1"."Code", "p1"."Name", (
          SELECT "p"."Price"
          FROM "PriceHistory" AS "p"
          WHERE "p1"."Id" = "p"."ProductId"
          ORDER BY "p"."CreatedOn" DESC
          LIMIT 1) AS "Price", (
          SELECT "p0"."CreatedOn"
          FROM "PriceHistory" AS "p0"
          WHERE "p1"."Id" = "p0"."ProductId"
          ORDER BY "p0"."CreatedOn" DESC
          LIMIT 1) AS "PriceChangedOn"
      FROM "Product" AS "p1"
      ORDER BY "p1"."Code"
      LIMIT @__p_1 OFFSET @__p_0

As we can see, because we need both the Price and CreatedOn columns from the most recent price history entry, the SQLite provider decided to create two sub-queries. The database engine is relatively smart to know how to optimize them but lets ensure the engine optimizes the access as follows:

1. order products by code
2. filter products by skip and take
3. join with latest price history entry, grouped by product, using the ROWID for fast access

SELECT p.ExternalId as Id, p.Code, p.Name, lph.Price, lph.CreatedOn as PriceChangedOn
FROM (
    SELECT Id, ExternalId, Code, Name, RowId
    FROM Product
    ORDER BY Code DESC
    LIMIT @Take OFFSET @Skip
) p
INNER JOIN (
    SELECT ph.ProductId, ph.Price, ph.CreatedOn
    FROM PriceHistory ph
    INNER JOIN (
        SELECT MAX(RowId) RowId
        FROM PriceHistory
        GROUP BY ProductId
    ) phLatest ON ph.RowId = phLatest.RowId
) lph ON p.Id = lph.ProductId

Note: this may not be the most optimized access but remember, this is for demo purposes.

Change the GetAllAsync action to use the QueryAsync<T> extension method, passing this SQL and both the skip and take as arguments.

[Route("products")]
public class ProductsController : ControllerBase
{
    // ...

    [HttpGet]
    public async Task<IEnumerable<ProductModel>> GetAllAsync([FromQuery] int? skip, [FromQuery] int? take, CancellationToken ct)
    {
        return await _context.QueryAsync<ProductModel>(ct, @"
SELECT p.ExternalId as Id, p.Code, p.Name, lph.Price, lph.CreatedOn as PriceChangedOn
FROM (
    SELECT Id, ExternalId, Code, Name, RowId
    FROM Product
    ORDER BY Code DESC
    LIMIT @Take OFFSET @Skip
) p
INNER JOIN (
    SELECT ph.ProductId, ph.Price, ph.CreatedOn
    FROM PriceHistory ph
    INNER JOIN (
        SELECT MAX(RowId) RowId
        FROM PriceHistory
        GROUP BY ProductId
    ) phLatest ON ph.RowId = phLatest.RowId
) lph ON p.Id = lph.ProductId", new
        {
            Skip = skip ?? 0,
            Take = take ?? 20
        });
    }

    // ...
}

Because we globally registered our GuidTypeHandler, Dapper will know how to convert the column ExternalId [TEXT] as a Guid so we can map our result directly as a ProductModel type.

Once again, if you invoke the endpoint using the Swagger UI, the folowing log should be visible:

dbug: EntityFrameworkCoreWithDapper.Database.DapperEFCoreCommand[0]
      Executing DbCommand [CommandType='Text', CommandTimeout='30']
      
      SELECT p.ExternalId as Id, p.Code, p.Name, lph.Price, lph.CreatedOn as PriceChangedOn
      FROM (
          SELECT Id, ExternalId, Code, Name, RowId
          FROM Product
          ORDER BY Code DESC
          LIMIT @Take OFFSET @Skip
      ) p
      INNER JOIN (
          SELECT ph.ProductId, ph.Price, ph.CreatedOn
          FROM PriceHistory ph
          INNER JOIN (
              SELECT MAX(RowId) RowId
              FROM PriceHistory
              GROUP BY ProductId
          ) phLatest ON ph.RowId = phLatest.RowId
      ) lph ON p.Id = lph.ProductId
info: EntityFrameworkCoreWithDapper.Database.DapperEFCoreCommand[0]
      Executed DbCommand [CommandType='Text', CommandTimeout='30']
      
      SELECT p.ExternalId as Id, p.Code, p.Name, lph.Price, lph.CreatedOn as PriceChangedOn
      FROM (
          SELECT Id, ExternalId, Code, Name, RowId
          FROM Product
          ORDER BY Code DESC
          LIMIT @Take OFFSET @Skip
      ) p
      INNER JOIN (
          SELECT ph.ProductId, ph.Price, ph.CreatedOn
          FROM PriceHistory ph
          INNER JOIN (
              SELECT MAX(RowId) RowId
              FROM PriceHistory
              GROUP BY ProductId
          ) phLatest ON ph.RowId = phLatest.RowId
      ) lph ON p.Id = lph.ProductId

Conclusion

I hope this article gave you a good idea on how to easily integrate Dapper with Entity Framework Core, either to optimize critical paths or to workaround limitations while removing the need to use TransactionScope, usually needed for these use cases.

Remember that I only implemented a few set of operations, but feel free to extend your own, like FirstOrDefaultAsync, SingleAsync and even their synchronous operations.

As an extended note, this approach can also be easily applied to any other ORM, like NHibernate, as long you can access the underline DbConnection and current DbTransaction from the context.

Auditing with Mediator Pipelines in ASP.NET Core

2020-11-25T00:00:00.000Z

When implementing a web application, it can be a good idea to enforce some kind of auditing to all of your client interactions, either to track their behavior over time, to ensure any security breach will be properly logged, or just to help analyze system bugs.

Previously we talked about using the mediator pattern to implement the Command Query Responsibility Segregation (CQRS) and Event Sourcing (ES) and how pipelines could be used to implement transversal behavior to your application.

Since commands are responsible to mutate the system state, in this article I’m going to demonstrate how you could implement an audit pipeline to ensure all commands will be stored into a table. Because a variable number of events can be broadcasted when the state changes, the pipeline will also store them into another table and with a reference to the command, ensuring any correlation can be analyzed.

The project

From my previous articles, were I explained how to use the mediator and implement transversal behavior with pipelines, we are going to continue and expand the source code to audit commands and store into the events table anything broadcasted by the mediator without having a specific handler for each event.

As a reminder, we implemented an endpoint to manage products with the following:

GET /products — search for products using some filters (SearchProductsQuery);
GET /products/{id} — get a product by its unique identifier (GetProductByIdQuery);
POST /products — create a product (CreateProductCommand and CreatedProductEvent);
PUT /products/{id} — update a product by its unique identifier (UpdateProductCommand and UpdatedProductEvent);
DELETE /products/{id} — delete a product by its unique identifier (DeleteProductCommand and DeletedProductEvent);

You can check them out here:

The source code is available on GitHub, feel free to give it a look.

Auditing

Since in this article we will only audit API actions that mutate state, we are going to intercept commands and store information we find relevant into a specific table:

ExternalId — the unique identifier for each command, available via Command.Id or Command<TResult>.Id;
Name — the command type name from typeof(TCommand).Name;
Payload — the command serialized as JSON;
Result — if available, the command result serialized as JSON;
CreatedOn — date and time when the command was sent into the mediator, available via Command.CreatedOn or Command<TResult>.CreatedOn;
CreatedBy — username from the current request user property, available via Command.CreatedBy or Command<TResult>.CreatedBy;
ExecutionTime — elapsed time the handler spent processing the command;

Because events are broadcasted by commands, which are now audited into the database, we are also going to extend the events table and introduce the foreign key CommandId, referencing the commands.

The Database Model

Inside the Database folder create a CommandEntity class and add the new CommandId property to the existing EventEntity:

public class CommandEntity
{
    public long Id { get; set; }
    public Guid ExternalId { get; set; }
    public string Name { get; set; }
    public string Payload { get; set; }
    public string Result { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
    public string CreatedBy { get; set; }
    public TimeSpan ExecutionTime { get; set; }
}

public class EventEntity
{
    public long Id { get; set; }
    public long CommandId { get; set; } // added property
    public Guid ExternalId { get; set; }
    public string Name { get; set; }
    public string Payload { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
    public string CreatedBy { get; set; }
}

Open the ApiDbContext file, configure the mappings for the CommandEntity and add a required one-to-many relation between this tables:

public class ApiDbContext : DbContext
{
    // ...

    protected override void OnModelCreating(ModelBuilder builder)
    {
        // ...

        builder.Entity<CommandEntity>(cfg =>
        {
            cfg.HasKey(e => e.Id);
            cfg.HasAlternateKey(e => e.ExternalId);
            cfg.HasIndex(e => e.CreatedOn);
            cfg.Property(e => e.Id)
                .IsRequired()
                .ValueGeneratedOnAdd();
            cfg.Property(e => e.ExternalId)
                .IsRequired();
            cfg.Property(e => e.Name)
                .IsRequired()
                .HasMaxLength(128);
            cfg.Property(e => e.Payload)
                .IsRequired();
            cfg.Property(e => e.Result);
            cfg.Property(e => e.CreatedOn)
                .IsRequired();
            cfg.Property(e => e.CreatedBy)
                .IsRequired()
                .HasMaxLength(128);
            cfg.Property(e => e.ExecutionTime)
                .IsRequired();
        });

        builder.Entity<EventEntity>(cfg =>
        {
            cfg.HasKey(e => e.Id);
            cfg.HasAlternateKey(e => e.ExternalId);
            cfg.HasIndex(e => e.CreatedOn);
            cfg.Property(e => e.Id)
                .IsRequired()
                .ValueGeneratedOnAdd();
            cfg.HasOne<CommandEntity>()
                .WithMany()
                .HasForeignKey(e => e.CommandId)
                .IsRequired();
            cfg.Property(e => e.ExternalId)
                .IsRequired();
            cfg.Property(e => e.Name)
                .IsRequired()
                .HasMaxLength(128);
            cfg.Property(e => e.Payload)
                .IsRequired();
            cfg.Property(e => e.CreatedOn)
                .IsRequired();
            cfg.Property(e => e.CreatedBy)
                .IsRequired()
                .HasMaxLength(128);
        });
    }
}

User Information

By design, all POCOs provided in this library are immutable and only provide a protected setter for the properties Id, CreatedOn and CreatedBy. This ensures the developer is free to decide either by immutable commands, queries and events, initializing all properties in the constructor, or to expose a public setter instead.

Since we haven’t made our POCOs immutable, and for demo purposes, we are going to expose a public setter for the CreatedBy property by implementing our own command, query and event classes.

Inside the Handlers folder create a Command.cs, Query.cs and Event.cs files and extend the corresponding Command, Command<TResult>, Query<TResult> and Event classes, creating a new setter ao getter for CreatedBy. Since your classes have the same name than the ones provided by Simplesoft.Mediator, your existing classes will automatically extend from them and expose the new setters without a single change:

public class Command : SimpleSoft.Mediator.Command
{
    public new string CreatedBy
    {
        get => base.CreatedBy;
        set => base.CreatedBy = value;
    }
}

public class Command<TResult> : SimpleSoft.Mediator.Command<TResult>
{
    public new string CreatedBy
    {
        get => base.CreatedBy;
        set => base.CreatedBy = value;
    }
}

public class Event : SimpleSoft.Mediator.Event
{
    public new string CreatedBy
    {
        get => base.CreatedBy;
        set => base.CreatedBy = value;
    }
}

public class Query<TResult> : SimpleSoft.Mediator.Query<TResult>
{
    public new string CreatedBy
    {
        get => base.CreatedBy;
        set => base.CreatedBy = value;
    }
}

The project solution should look like this:

Open your ProductsController.cs file and set the CreatedBy property of all the commands and queries with the property User.Identity.Name.

Please keep in your mind that, since we haven’t configured authentication in this API, the username value will always be null.

After changes, your controller actions should look as follows:

[Route("products")]
public class ProductsController : ControllerBase
{
    private readonly IMediator _mediator;

    public ProductsController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpGet]
    public async Task<IEnumerable<ProductModel>> SearchAsync([FromQuery] string filterQ, [FromQuery] int? skip, [FromQuery] int? take, CancellationToken ct)
    {
        var result = await _mediator.FetchAsync(new SearchProductsQuery
        {
            FilterQ = filterQ,
            Skip = skip,
            Take = take,
            CreatedBy = User.Identity.Name
        }, ct);

        return result.Select(r => new ProductModel
        {
            Id = r.Id,
            Code = r.Code,
            Name = r.Name,
            Price = r.Price
        });
    }

    [HttpGet("{id:guid}")]
    public async Task<ProductModel> GetByIdAsync([FromRoute] Guid id, CancellationToken ct)
    {
        var result = await _mediator.FetchAsync(new GetProductByIdQuery
        {
            ProductId = id,
            CreatedBy = User.Identity.Name
        }, ct);

        return new ProductModel
        {
            Id = result.Id,
            Code = result.Code,
            Name = result.Name,
            Price = result.Price
        };
    }

    [HttpPost]
    public async Task<CreateProductResultModel> CreateAsync([FromBody] CreateProductModel model, CancellationToken ct)
    {
        var result = await _mediator.SendAsync(new CreateProductCommand
        {
            Code = model.Code,
            Name = model.Name,
            Price = model.Price,
            CreatedBy = User.Identity.Name
        }, ct);

        return new CreateProductResultModel
        {
            Id = result.Id
        };
    }

    [HttpPut("{id:guid}")]
    public async Task UpdateAsync([FromRoute] Guid id, [FromBody] UpdateProductModel model, CancellationToken ct)
    {
        await _mediator.SendAsync(new UpdateProductCommand
        {
            ProductId = id,
            Code = model.Code,
            Name = model.Name,
            Price = model.Price,
            CreatedBy = User.Identity.Name
        }, ct);
    }

    [HttpDelete("{id:guid}")]
    public async Task DeleteAsync([FromRoute] Guid id, CancellationToken ct)
    {
        await _mediator.SendAsync(new DeleteProductCommand
        {
            ProductId = id,
            CreatedBy = User.Identity.Name
        }, ct);
    }
}

We also want to pass the same username to all of our events, so open the command handlers and set the event CreatedBy property with the same value from the command, as exemplified by the following handler:

public class CreateProductCommandHandler : ICommandHandler<CreateProductCommand, CreateProductResult>
{
    private readonly ApiDbContext _context;
    private readonly IMediator _mediator;

    public CreateProductCommandHandler(ApiDbContext context, IMediator mediator)
    {
        _context = context;
        _mediator = mediator;
    }

    public async Task<CreateProductResult> HandleAsync(CreateProductCommand cmd, CancellationToken ct)
    {
        var products = _context.Set<ProductEntity>();

        if (await products.AnyAsync(p => p.Code == cmd.Code, ct))
        {
            throw new InvalidOperationException($"Product code '{cmd.Code}' already exists");
        }

        var externalId = Guid.NewGuid();
        await products.AddAsync(new ProductEntity
        {
            ExternalId = externalId,
            Code = cmd.Code,
            Name = cmd.Name,
            Price = cmd.Price
        }, ct);

        await _mediator.BroadcastAsync(new CreatedProductEvent
        {
            ExternalId = externalId,
            Code = cmd.Code,
            Name = cmd.Name,
            Price = cmd.Price,
            CreatedBy = cmd.CreatedBy  // use the same value
        }, ct);

        return new CreateProductResult
        {
            Id = externalId
        };
    }
}

The Audit Pipeline

Now that we are passing the user information into the mediator we can create the audit pipeline that will have the following behavior when intercepting commands:

Serialize and insert a new entry into the commands table;
Add both the command and entry ids into an AsyncLocal<T> scope to be used if an event is broadcast;
Invoke the next pipe;
If available, serialize the result, calculate the execution time and update the table entry;

When intercepting events, which are sent by commands, it will do the following:

Get the command id from the current AsyncLocal<T> scope;
Serialize the event and insert a new entry into the events table, referencing the command entry;
Invoke the next pipe;

Inside the Pipelines folder, create an AuditPipeline class extending Pipeline. The implementation should be similar to the following:

public class AuditPipeline : Pipeline
{
    private readonly DbSet<CommandEntity> _commands;
    private readonly DbSet<EventEntity> _events;

    public AuditPipeline(ApiDbContext context)
    {
        _commands = context.Set<CommandEntity>();
        _events = context.Set<EventEntity>();
    }

    public override async Task OnCommandAsync<TCommand>(Func<TCommand, CancellationToken, Task> next, TCommand cmd, CancellationToken ct)
    {
        var command = (await _commands.AddAsync(new CommandEntity
        {
            ExternalId = cmd.Id,
            Name = typeof(TCommand).Name,
            Payload = JsonSerializer.Serialize(cmd),
            Result = null,
            CreatedOn = cmd.CreatedOn,
            CreatedBy = cmd.CreatedBy,
            ExecutionTime = TimeSpan.Zero
        }, ct)).Entity;

        using (CommandScope.Begin(command.ExternalId, command.Id))
        {
            await next(cmd, ct);
        }

        command.ExecutionTime = DateTimeOffset.UtcNow - cmd.CreatedOn;
    }

    public override async Task<TResult> OnCommandAsync<TCommand, TResult>(Func<TCommand, CancellationToken, Task<TResult>> next, TCommand cmd, CancellationToken ct)
    {
        var command = (await _commands.AddAsync(new CommandEntity
        {
            ExternalId = cmd.Id,
            Name = typeof(TCommand).Name,
            Payload = JsonSerializer.Serialize(cmd),
            Result = null,
            CreatedOn = cmd.CreatedOn,
            CreatedBy = cmd.CreatedBy,
            ExecutionTime = TimeSpan.Zero
        }, ct)).Entity;

        TResult result;

        using (CommandScope.Begin(command.ExternalId, command.Id))
        {
            result = await next(cmd, ct);
        }

        command.Result = result == null ? null : JsonSerializer.Serialize(result);
        command.ExecutionTime = DateTimeOffset.UtcNow - cmd.CreatedOn;

        return result;
    }

    public override async Task OnEventAsync<TEvent>(Func<TEvent, CancellationToken, Task> next, TEvent evt, CancellationToken ct)
    {
        await _events.AddAsync(new EventEntity
        {
            CommandId = CommandScope.Current.Id,
            ExternalId = evt.Id,
            Name = typeof(TEvent).Name,
            Payload = JsonSerializer.Serialize(evt),
            CreatedOn = evt.CreatedOn,
            CreatedBy = evt.CreatedBy,
        }, ct);

        await next(evt, ct);
    }

    private class CommandScope : IDisposable
    {
        private CommandScope(Guid externalId, long id)
        {
            ExternalId = externalId;
            Id = id;

            AsyncLocal.Value = this;
        }

        public Guid ExternalId { get; }

        public long Id { get; }

        public void Dispose()
        {
            AsyncLocal.Value = null;
        }

        private static readonly AsyncLocal<CommandScope> AsyncLocal = new AsyncLocal<CommandScope>();

        public static CommandScope Current => AsyncLocal.Value;

        public static IDisposable Begin(Guid externalId, long id) => new CommandScope(externalId, id);
    }
}

Open the Startup.cs file and register this pipeline to be run after all the existing ones, right before the commands or events are handled.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen();

        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseInMemoryDatabase("ApiDbContext").ConfigureWarnings(warn =>
            {
                // since InMemoryDatabase does not support transactions
                // for test purposes we are going to ignore this exception
                warn.Ignore(InMemoryEventId.TransactionIgnoredWarning);
            });
        });

        services.AddMediator(o =>
        {
            o.AddPipeline<LoggingPipeline>();
            o.AddPipeline<TimeoutPipeline>();
            o.AddPipeline<ValidationPipeline>();
            o.AddPipeline<TransactionPipeline>();
            o.AddPipeline<AuditPipeline>();
            foreach (var implementationType in typeof(Startup)
                .Assembly
                .ExportedTypes
                .Where(t => t.IsClass && !t.IsAbstract))
            {
                foreach (var serviceType in implementationType
                    .GetInterfaces()
                    .Where(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IValidator<>)))
                {
                    o.Services.Add(new ServiceDescriptor(serviceType, implementationType, ServiceLifetime.Transient));
                }
            }
            o.AddHandlersFromAssemblyOf<Startup>();
        });

        // or, if using the SimpleSoft.Mediator.Microsoft.Extensions.* pipelines
        //services.AddMediator(o =>
        //{
        //    o.AddPipelineForLogging(options =>
        //    {
        //        options.LogCommandResult = true;
        //        options.LogQueryResult = true;
        //    });
        //    o.AddPipeline<TimeoutPipeline>();
        //    o.AddPipelineForValidation(options =>
        //    {
        //        options.ValidateCommand = true;
        //        options.ValidateEvent = true;
        //    });
        //    o.AddPipelineForEFCoreTransaction<ApiDbContext>(options =>
        //    {
        //        options.BeginTransactionOnCommand = true;
        //    });
        //    o.AddPipeline<AuditPipeline>();

        //    o.AddValidatorsFromAssemblyOf<Startup>();
        //    o.AddHandlersFromAssemblyOf<Startup>();
        //});
    }

    // ...
}

Because this pipeline is also serializing all events, the existing handlers for CreatedProductEvent, DeletedProductEvent and UpdatedProductEvent can now either be deleted or stop storing their events into the table to prevent duplicated data:

public class CreatedProductEventHandler : IEventHandler<CreatedProductEvent>
{
    private readonly ApiDbContext _context;

    public CreatedProductEventHandler(ApiDbContext context)
    {
        _context = context;
    }

    public Task HandleAsync(CreatedProductEvent evt, CancellationToken ct)
    {
        //await _context.Set<EventEntity>().AddAsync(new EventEntity
        //{
        //    ExternalId = evt.Id,
        //    Name = nameof(CreatedProductEvent),
        //    Payload = JsonSerializer.Serialize(evt),
        //    CreatedOn = evt.CreatedOn,
        //    CreatedBy = evt.CreatedBy
        //}, ct);

        return Task.CompletedTask;
    }
}

AsyncLocal

When comparing the audit pipeline with the previous ones we implemented, the biggest difference is the usage of AsyncLocal<T> to store an instance of the CommandScope class holding both the command external id and the primary key value for the audit entry into the table.

If you aren’t familiar with this class, it is available since .NET Framework 4.6 and .NET standard 1.3, and was introduced to help sharing global flow state when implementing asynchronous code with Task Parallel Library (TPL). Because TPL relies on the thread pool and, by default, asynchronous code in ASP.NET Core applications can be resumed by any available thread, we can’t rely on mechanisms like the ThreadLocal class to store global state.

Simply put, the idea of AsyncLocal<T> is to create a static instance that can hold some T value and, as long you use the async and await keywords, the runtime will consider your code execution to be a logical flow, despite asynchronous, and will ensure the value is shared even if the flow has been resumed by a different thread.

Because we want to share data between the command and event interceptor code, the flow is asynchronous, and since only commands broadcast events, the AsyncLocal<T> class is an elegant solution to prevent changing all the events to include an CommandId property that has to be set on every broadcast.

As an example, this is usually the solution implemented by some logging frameworks to support the creation of scopes, enabling some information to be written on every log without having to pass it every time, like when the using Microsoft façade Logger.BeginScope("X:{x} Y:{y}", x, y).

For more details and examples, give a look to the AsyncLocal<T> class documentation.

Audits Controller

To make it easier to test and check our system audits, we are going to implement the following endpoint:

GET /audits — search for command audits using some filters (SearchAuditsQuery);
GET /audits/{id} — get a command audit by its unique identifier and all the associated events (GetAuditByIdQuery);

Inside the Handlers folder create an Audits folder and create the queries for searching or getting an audit by its external id:

public class SearchAuditsQueryHandler : IQueryHandler<SearchAuditsQuery, IEnumerable<AuditSearchItem>>
{
    private readonly IQueryable<CommandEntity> _commands;

    public SearchAuditsQueryHandler(ApiDbContext context)
    {
        _commands = context.Set<CommandEntity>();
    }

    public async Task<IEnumerable<AuditSearchItem>> HandleAsync(SearchAuditsQuery query, CancellationToken ct)
    {
        var filter = _commands;

        if (!string.IsNullOrWhiteSpace(query.FilterQ))
        {
            var filterQ = query.FilterQ.Trim();

            filter = filter.Where(p =>
                p.Name.Contains(filterQ)
            );
        }

        var skip = query.Skip ?? 0;
        var take = query.Take ?? 20;

        return await filter
            .OrderByDescending(c => c.CreatedOn)
            .ThenByDescending(c => c.Id)
            .Skip(skip)
            .Take(take)
            .Select(c => new AuditSearchItem
            {
                Id = c.ExternalId,
                Name = c.Name,
                CreatedOn = c.CreatedOn,
                CreatedBy = c.CreatedBy,
                ExecutionTimeInMs = (long) c.ExecutionTime.TotalMilliseconds
            }).ToListAsync(ct);
    }
}

public class SearchAuditsQuery : Query<IEnumerable<AuditSearchItem>>
{
    public string FilterQ { get; set; }
    public int? Skip { get; set; }
    public int? Take { get; set; }
}

public class AuditSearchItem
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
    public string CreatedBy { get; set; }
    public long ExecutionTimeInMs { get; set; }
}

public class GetAuditByIdQueryHandler : IQueryHandler<GetAuditByIdQuery, Audit>
{
    private readonly IQueryable<CommandEntity> _commands;
    private readonly IQueryable<EventEntity> _events;

    public GetAuditByIdQueryHandler(ApiDbContext context)
    {
        _commands = context.Set<CommandEntity>();
        _events = context.Set<EventEntity>();
    }

    public async Task<Audit> HandleAsync(GetAuditByIdQuery query, CancellationToken ct)
    {
        var command = await _commands.SingleOrDefaultAsync(c => c.ExternalId == query.AuditId, ct);

        if (command == null)
        {
            throw new InvalidOperationException($"Command audit '{query.AuditId}' not found");
        }

        var events = await _events.Where(e => e.CommandId == command.Id).ToListAsync(ct);

        return new Audit
        {
            Id = command.ExternalId,
            Name = command.Name,
            Payload = JsonSerializer.Deserialize<dynamic>(command.Payload),
            Result = string.IsNullOrWhiteSpace(command.Result)
                ? null
                : JsonSerializer.Deserialize<dynamic>(command.Result),
            CreatedOn = command.CreatedOn,
            CreatedBy = command.CreatedBy,
            ExecutionTimeInMs = (long) command.ExecutionTime.TotalMilliseconds,
            Events = events.Select(e => new AuditEvent
            {
                Id = e.ExternalId,
                Name = e.Name,
                Payload = JsonSerializer.Deserialize<dynamic>(e.Payload),
                CreatedOn = e.CreatedOn
            }).ToList()
        };
    }
}

public class GetAuditByIdQuery : Query<Audit>
{
    public Guid AuditId { get; set; }
}

public class Audit
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public object Payload { get; set; }
    public object Result { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
    public string CreatedBy { get; set; }
    public long ExecutionTimeInMs { get; set; }
    public IEnumerable<AuditEvent> Events { get; set; }
}

public class AuditEvent
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public object Payload { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
}

Inside the Controllers folder create an Audit folder and an AuditController that will use the previous queries:

[Route("audits")]
public class AuditsController : ControllerBase
{
    private readonly IMediator _mediator;

    public AuditsController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpGet]
    public async Task<IEnumerable<AuditSearchItemModel>> SearchAsync([FromQuery] string filterQ, [FromQuery] int? skip, [FromQuery] int? take, CancellationToken ct)
    {
        var result = await _mediator.FetchAsync(new SearchAuditsQuery
        {
            FilterQ = filterQ,
            Skip = skip,
            Take = take,
            CreatedBy = User.Identity.Name
        }, ct);

        return result.Select(r => new AuditSearchItemModel
        {
            Id = r.Id,
            Name = r.Name,
            CreatedOn = r.CreatedOn,
            CreatedBy = r.CreatedBy,
            ExecutionTimeInMs = r.ExecutionTimeInMs
        });
    }

    [HttpGet("{id:guid}")]
    public async Task<AuditModel> GetByIdAsync([FromRoute] Guid id, CancellationToken ct)
    {
        var result = await _mediator.FetchAsync(new GetAuditByIdQuery
        {
            AuditId = id,
            CreatedBy = User.Identity.Name
        }, ct);

        return new AuditModel
        {
            Id = result.Id,
            Name = result.Name,
            Payload = result.Payload,
            Result = result.Result,
            CreatedOn = result.CreatedOn,
            CreatedBy = result.CreatedBy,
            ExecutionTimeInMs = result.ExecutionTimeInMs,
            Events = result.Events.Select(e => new AuditEventModel
            {
                Id = e.Id,
                Name = e.Name,
                Payload = e.Payload,
                CreatedOn = e.CreatedOn
            })
        };
    }
}

public class AuditSearchItemModel
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
    public string CreatedBy { get; set; }
    public long ExecutionTimeInMs { get; set; }
}

public class AuditModel
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public object Payload { get; set; }
    public object Result { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
    public string CreatedBy { get; set; }
    public long ExecutionTimeInMs { get; set; }
    public IEnumerable<AuditEventModel> Events { get; set; }
}

public class AuditEventModel
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public object Payload { get; set; }
    public DateTimeOffset CreatedOn { get; set; }
}

The project structure should look as follows:

Open the Swagger endpoint (ex: https://localhost:44380/swagger) and you should see the audits endpoint:

Create, update or delete products with the help of Swagger UI and then check if all the commands and events have been properly audited:

And even get the details of a specific audit:

Conclusion

I hope this article gave you a good idea on how to use mediator pipelines to simplify the auditing of user actions without having to replicate code across all commands.

We also ensured events were always stored before being broadcasted and a reference to the command was kept without adding properties to our POCOs, providing a more clean approach.

Soon I’ll be explaining how we can inject more specialized interfaces, like the ISender<TCommand>, to make our dependencies more clearer and help with unit testing.

Transaction Management With Mediator Pipelines in ASP.NET Core

2020-11-07T00:00:00.000Z

When implementing a simplified CQRS service, which usually has a single database but still separates commands from queries, the mediator pipeline can be used to manage transactions when processing commands, ensuring changes will be implicitly committed unless an exception is thrown.

Implementing a pipeline for transactions has some key advantages even when using Entity Framework Core or other ORM that tracks and flushes changes at a single point in time.

Because the command handler is executing inside an implicit transaction, the developer is free to flush their changes as it sees fit knowing that any exception will rollback the changes. This is very helpful when it wants to cancel the flow when some business rules aren’t meet and could only be checked after changing the system state. Optimistic concurrency is a good example where you may want to flush your changes before leaving the handler so you know exactly what entity failed and can send a more detailed message to the user, which is the usual approach when implementing a dedicated Backend for Frontend service.

Also, ORMs are very good at abstracting database access but can’t solve more edge cases, specially when performance is a requirement. Being able to use a more lightweight library (e.g. Dapper) to do some bulk operations and using the ORM context connection inside the same transaction will remove the need to use the TransactionScope and reduce some application complexity.

Ensuring transactions are properly managed around the handler execution ensure the application architecture is be more robust and will be able to handle more edge cases.

The project

This article will be based on my previous ones that explained how to use the mediator and implement transversal behavior with pipelines. As a reminder, we implemented an endpoint to manage products with the following:

GET /products — search for products using some filters (SearchProductsQuery);
GET /products/{id} — get a product by its unique identifier (GetProductByIdQuery);
POST /products — create a product (CreateProductCommand and CreatedProductEvent);
PUT /products/{id} — update a product by its unique identifier (UpdateProductCommand and UpdatedProductEvent);
DELETE /products/{id} — delete a product by its unique identifier (DeleteProductCommand and DeletedProductEvent);

You can check them out here:

The source code is available on GitHub, feel free to give it a look.

Entity Framework Core transactions

Entity Framework Core has support for explicit transaction management, which works in a similar way to ADO.NET or the TransactionScope class.

You can get a disposable instance of IDbContextTransaction by invoking the method BeginTransactionAsync, available from the database property. The transaction can be either committed or rolled back, either by explicit invocation or by disposing the instance before any commit.

As stated before, this can be very helpful if SaveChanges must be invoked multiple times inside the unit of work operation and you want to ensure exceptions will rollback data changes.

await using var tx = await _context.Database.BeginTransactionAsync(ct);

var products = _context.Set<ProductEntity>();

await products.Where(p => p.Code.StartsWith('9')).ForEachAsync(product =>
{
    product.Name += " [DEPRECATED]";
}, ct);

await _context.SaveChangesAsync(ct);

await products.ForEachAsync(product =>
{
    product.Price /= 2;
}, ct);

await _context.SaveChangesAsync(ct);

await tx.CommitAsync(ct);

In the example above if an exception was thrown after the first SaveChangesAsync every changes would be reverted because the transaction would be disposed without an explicit call to commit.

We are going to leverage on this behavior to implement the pipeline.

The pipeline

Since only commands mutate system state, we are going to use the command pipeline to enforce a transaction for the next pipelines in the chain up until the handler.

The pipeline behavior will be:

Intercept any command;
Create a new IDbContextTransaction with BeginTransactionAsync;
Invoke the next pipeline inside the using scope;
If no exception is thrown, flush all changes and commit;
Dispose the transaction;

I’ll also include some commented code incase you want to be sure the queries never mutate the system state. Prevention is better than cure…

Inside the Pipelines folder create a TransactionPipeline class extending Pipeline (because we only need some of the methods):

public class TransactionPipeline : Pipeline
{
    private readonly ApiDbContext _context;

    public TransactionPipeline(ApiDbContext context)
    {
        _context = context;
    }

    public override async Task OnCommandAsync<TCommand>(Func<TCommand, CancellationToken, Task> next, TCommand cmd, CancellationToken ct)
    {
        await using var tx = await _context.Database.BeginTransactionAsync(ct);

        await next(cmd, ct);

        await _context.SaveChangesAsync(ct);
        await tx.CommitAsync(ct);
    }

    public override async Task<TResult> OnCommandAsync<TCommand, TResult>(Func<TCommand, CancellationToken, Task<TResult>> next, TCommand cmd, CancellationToken ct)
    {
        await using var tx = await _context.Database.BeginTransactionAsync(ct);

        var result = await next(cmd, ct);

        await _context.SaveChangesAsync(ct);
        await tx.CommitAsync(ct);

        return result;
    }

    //public override async Task<TResult> OnQueryAsync<TQuery, TResult>(Func<TQuery, CancellationToken, Task<TResult>> next, TQuery query, CancellationToken ct)
    //{
    //    await using var tx = await _context.Database.BeginTransactionAsync(ct);

    //    var result = await next(query, ct);

    //    await tx.RollbackAsync(ct);

    //    return result;
    //}
}

Open the Startup.cs file and add the TransactionPipeline after the ValidationPipeline, preventing the opening of transactions that could be immediately closed if the command had invalid data.

Since this examples are using the in-memory database provider for Entity Framework Core, which does not support explicit transactions, we are also going to ignore them for test purposes.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen();

        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseInMemoryDatabase("ApiDbContext").ConfigureWarnings(warn =>
            {
                warn.Ignore(InMemoryEventId.TransactionIgnoredWarning);
            });
        });

        services.AddMediator(o =>
        {
            o.AddPipeline<LoggingPipeline>();
            o.AddPipeline<TimeoutPipeline>();
            o.AddPipeline<ValidationPipeline>();
            o.AddPipeline<TransactionPipeline>();
            foreach (var implementationType in typeof(Startup)
                .Assembly
                .ExportedTypes
                .Where(t => t.IsClass && !t.IsAbstract))
            {
                foreach (var serviceType in implementationType
                    .GetInterfaces()
                    .Where(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IValidator<>)))
                {
                    o.Services.Add(new ServiceDescriptor(serviceType, implementationType, ServiceLifetime.Transient));
                }
            }
            o.AddHandlersFromAssemblyOf<Startup>();
        });
    }

    // ...
}

Now that we have a transversal behavior that manages transactions and flushes all context changes to the database, we can remove from all command handlers the explicit calls to SaveChangesAsync:

public class DeleteProductCommandHandler : ICommandHandler<DeleteProductCommand>
{
    private readonly ApiDbContext _context;
    private readonly IMediator _mediator;

    public DeleteProductCommandHandler(ApiDbContext context, IMediator mediator)
    {
        _context = context;
        _mediator = mediator;
    }

    public async Task HandleAsync(DeleteProductCommand cmd, CancellationToken ct)
    {
        var products = _context.Set<ProductEntity>();

        var product = await products.SingleOrDefaultAsync(p => p.ExternalId == cmd.ProductId, ct);

        if (product == null)
        {
            throw new InvalidOperationException($"Product '{cmd.ProductId}' not found");
        }

        products.Remove(product);

        //await _context.SaveChangesAsync(ct);

        await _mediator.BroadcastAsync(new DeletedProductEvent
        {
            ProductId = cmd.ProductId
        }, ct);
    }
}

Speeding things up!

Because this is a pipeline we use very often in most of our APIs, there is already a NuGet available that allows to open an explicit Entity Framework Core transaction for commands, events or queries, depending your needs.

To use it, just open the NuGet package manager and install the package SimpleSoft.Mediator.Microsoft.Extensions.EFCoreTransactionPipeline:

Open the Startup.cs file and register the pipeline with the extension method AddPipelineForEFCoreTransaction<TContext>. Explicit transactions are disabled by default, so you only need to enable them for commands.

When using all the NuGets mentioned on my previous articles, the Startup.cs file should be similar to this:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen();

        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseInMemoryDatabase("ApiDbContext").ConfigureWarnings(warn =>
            {
                // since InMemoryDatabase does not support transactions
                // for test purposes we are going to ignore this exception
                warn.Ignore(InMemoryEventId.TransactionIgnoredWarning);
            });
        });

        services.AddMediator(o =>
        {
            o.AddPipelineForLogging(options =>
            {
                options.LogCommandResult = true;
                options.LogQueryResult = true;
            });
            o.AddPipeline<TimeoutPipeline>();
            o.AddPipelineForValidation(options =>
            {
                options.ValidateCommand = true;
                options.ValidateEvent = true;
            });
            o.AddPipelineForEFCoreTransaction<ApiDbContext>(options =>
            {
                options.BeginTransactionOnCommand = true;
            });
            o.AddValidatorsFromAssemblyOf<Startup>();
            o.AddHandlersFromAssemblyOf<Startup>();
        });
    }

    // ..
}

Conclusion

I hope this article gave you a good idea on how to use mediator pipelines to simplify the management of Entity Framework Core transactions, making the implementation of command handlers less error prone since developers won’t forget to flush changes to the database (that behavior will be implicit unless an exception is thrown).

Even if your application is using another ORM or other lightweight libraries (e.g. Dapper), you can easily implement your own pipeline.

I also made an article about auditing user actions with pipelines, you may also find it helpful.

Validation with Mediator Pipelines in ASP.NET Core Applications

2020-11-04T00:00:00.000Z

When implementing web applications that manipulate information, there is always the need to validate data sent by the clients, ensuring business rules are properly implemented.

Previously I talked about the implementation of Command Query Responsibility Segregation (CQRS) and Event Sourcing (ES) using a mediator pattern and how to support transversal behavior via pipelines.

In this article I’m going to demonstrate how validation can be enforced into your commands and events before reaching the handlers, making sure that invalid data will be rejected by the API.

This approach not only reduces the amount of duplicated code, it also ensures validations won’t be forgotten, unless explicitly stated.

The project

To make it faster to implement the validation pipeline, I’m going to leverage this example on both of my previous articles, in which we implemented an endpoint to manage products and introduced both a logging and timeout pipelines.

The source code is available on GitHub.

The validations

To help us configure the rules we are going to use a very popular and one of my favorites libraries FluentValidation by creating classes implementing the interface IValidator<T>.

These classes will be added to the dependency injection container and used by the pipeline to validate both the commands and events before reaching the handler.

Lets start by installing the NuGet FluentValidation:

Create a Validations folder at the project root level, with a subfolder Products.

Inside the Products folder create both a validator for CreateProductCommand and CreatedProductEvent by extending the class AbstractValidator<T> (which itself implementes the interface IValidator<T>) and configure some rules in the constructors:

public class CreateProductCommandValidator : AbstractValidator<CreateProductCommand>
{
    public CreateProductCommandValidator()
    {
        RuleFor(e => e.Code)
            .NotEmpty()
            .Length(8)
            .Matches("^[0-9a-zA-Z]*$");

        RuleFor(e => e.Name)
            .NotEmpty()
            .MaximumLength(128);

        RuleFor(e => e.Price)
            .GreaterThanOrEqualTo(0);
    }
}

public class CreatedProductEventValidator : AbstractValidator<CreatedProductEvent>
{
    public CreatedProductEventValidator()
    {
        RuleFor(e => e.ExternalId)
            .NotEmpty();

        RuleFor(e => e.Code)
            .NotEmpty()
            .Length(8)
            .Matches("^[0-9a-zA-Z]*$");

        RuleFor(e => e.Name)
            .NotEmpty()
            .MaximumLength(128);

        RuleFor(e => e.Price)
            .GreaterThanOrEqualTo(0);
    }
}

Feel free to create validators for all other commands and events, I’m just focusing on these for simplicity. You can also check the documentation for supported rules and detailed usage instructions.

Open the Startup.cs file and register all classes implementing IValidator<T> into the container:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen();

        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseInMemoryDatabase("ApiDbContext");
        });

        services.AddMediator(o =>
        {
            o.AddPipeline<LoggingPipeline>();
            o.AddPipeline<TimeoutPipeline>();
            o.AddHandlersFromAssemblyOf<Startup>();
        });

        foreach (var implementationType in typeof(Startup)
            .Assembly
            .ExportedTypes
            .Where(t => t.IsClass && !t.IsAbstract))
        {
            foreach (var serviceType in implementationType
                .GetInterfaces()
                .Where(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IValidator<>)))
            {
                services.Add(new ServiceDescriptor(serviceType, implementationType, ServiceLifetime.Transient));
            }
        }
    }

    // ...
}

The pipeline

Because for this example we are going to enforce validation only on commands and events, since they either mutate or represent the system state at a given point in time, the pipeline will be implemented as follows:

Intercept any command or event;
Resolve a required instance of IValidator<TCommand> or IValidator<TEvent> from the container;
Invoke the method ValidateAndThrowAsync, failing with a ValidationException if something is invalid;

Inside the Pipelines folder create a ValidationPipeline class extending Pipeline (because we only need some of the methods):

public class ValidationPipeline : Pipeline
{
    private readonly IServiceProvider _provider;

    public ValidationPipeline(IServiceProvider provider)
    {
        _provider = provider;
    }

    public override async Task OnCommandAsync<TCommand>(Func<TCommand, CancellationToken, Task> next, TCommand cmd, CancellationToken ct)
    {
        await ValidateAndThrowAsync(cmd, ct);
        await next(cmd, ct);
    }

    public override async Task<TResult> OnCommandAsync<TCommand, TResult>(Func<TCommand, CancellationToken, Task<TResult>> next, TCommand cmd, CancellationToken ct)
    {
        await ValidateAndThrowAsync(cmd, ct);
        return await next(cmd, ct);
    }

    public override async Task OnEventAsync<TEvent>(Func<TEvent, CancellationToken, Task> next, TEvent evt, CancellationToken ct)
    {
        await ValidateAndThrowAsync(evt, ct);
        await next(evt, ct);
    }

    private async Task ValidateAndThrowAsync<T>(T instance, CancellationToken ct)
    {
        var validator = _provider.GetRequiredService<IValidator<T>>();
        await validator.ValidateAndThrowAsync(instance, ct);
    }
}

Open the Startup.cs file and add the ValidationPipeline at least after the LoggingPipeline ensuring, in case invalid data is submitted, we can still see it in the logs:

services.AddMediator(o =>
{
    o.AddPipeline<LoggingPipeline>();
    o.AddPipeline<TimeoutPipeline>();
    o.AddPipeline<ValidationPipeline();
    o.AddHandlersFromAssemblyOf<Startup>();
});

If you now start the server and try to create a product with invalid data you will receive a ValidationException.

Because returning an HTTP 500 due to invalid data would be confusing to the client, lets just finish this example by creating an ASP.NET Core middleware converting this exception into a more appropriate code, like HTTP 422.

Once again, open the Startup.cs file and register the middleware immediately after the developer exception page, catching this exception and returning HTTP 422 with a more detailed JSON representation:

public class Startup
{
    // ...

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

        app.Use(async (ctx, next) =>
        {
            try
            {
                await next();
            }
            catch (ValidationException e)
            {
                var response = ctx.Response;
                if (response.HasStarted)
                    throw;
                ctx.RequestServices
                    .GetRequiredService<ILogger<Startup>>()
                    .LogWarning(e, "Invalid data has been submitted");
                response.Clear();
                response.StatusCode = 422;
                await response.WriteAsync(JsonSerializer.Serialize(new
                {
                    Message = "Invalid data has been submitted",
                    ModelState = e.Errors.ToDictionary(error => error.ErrorCode, error => error.ErrorMessage)
                }), Encoding.UTF8, ctx.RequestAborted);
            }
        });

        app.UseSwagger();

        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "Mediator ExampleApi V1");
        });

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

Submit invalid data again and a more detailed message should be returned:

POST /products
{
  "code": "-123456",
  "name": "",
  "price": -1
}

HTTP 422
{
   "Message":"Invalid data has been submitted",
   "ModelState":{
      "ExactLengthValidator":"'Code' must be 8 characters in length. You entered 7 characters.",
      "RegularExpressionValidator":"'Code' is not in the correct format.",
      "NotEmptyValidator":"'Name' must not be empty.",
      "GreaterThanOrEqualValidator":"'Price' must be greater than or equal to '0'."
   }
}

Speeding things up!

If just like me, you can see yourself using a pipeline for validation in most of your projects, there is already a pipeline available via NuGet that should be configurable to most use cases while also providing a simpler way to register the validators into the container.

Install SimpleSoft.Mediator.Microsoft.Extensions.ValidationPipeline via NuGet:

Use the extension method AddPipelineForValidation and enforce both command and event validations and use the extension method AddValidatorsFromAssemblyOf to scan for all IValidator<T> classes and register them into the container.

For the current project, the ConfigureServices method would be similar to the following:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen();

        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseInMemoryDatabase("ApiDbContext");
        });

        services.AddMediator(o =>
        {
            o.AddPipeline<LoggingPipeline>();
            o.AddPipeline<TimeoutPipeline>();
            o.AddPipelineForValidation(options =>
            {
                options.ValidateCommand = true;
                options.ValidateEvent = true;
            });
            o.AddValidatorsFromAssemblyOf<Startup>();
            o.AddHandlersFromAssemblyOf<Startup>();
        });
    }

    // ...
}

Conclusion

I hope this article gave you a good idea on how to use mediator pipelines to ensure that all your commands, events and even queries are initialized with proper data, either implementing your own pipeline or by using the existing ValidationPipeline NuGet.

I also made an article about transaction management with pipelines, you may also find it helpful.

Using Mediator Pipelines in ASP.NET Core Applications

2020-11-02T00:00:00.000Z

In my previous article I explained how you could implement Command Query Responsibility Segregation (CQRS) and Event Sourcing (ES) patterns using a mediator instance from SimpleSoft.Mediator in ASP.NET Core applications.

This time I’m going to explain how to intercept commands, queries and events, making it possible to apply transversal behavior before they reach the handlers, reducing significantly the amount of boilerplate and duplicated code.

Transaction management, logging, auditing, caching or validations are some of the good examples where pipelines can be very helpful. Imagine the following chains:

Commands:
  Mediator
    LoggingPipeline
      ValidationPipeline
        TransactionPipeline
          AuditPipeline
            Handler

Queries:
  Mediator
    LoggingPipeline
      Handler

Events:
  Mediator
    LoggingPipeline
      StoragePipeline
        Handler(s)

Not only you can plugin any pipeline at will without changing the handlers implementation, you can also be specific to the entities each pipeline is interested.

Pipelines

Mediator pipelines are represented by the interface IPipeline (or the abstract class Pipeline) with methods to intercept each entity type:

public interface IPipeline
{
    Task OnCommandAsync<TCommand>(
        Func<TCommand, CancellationToken, Task> next, 
        TCommand cmd, 
        CancellationToken ct
    ) where TCommand : class, ICommand;

    Task<TResult> OnCommandAsync<TCommand, TResult>(
        Func<TCommand, CancellationToken, Task<TResult>> next, 
        TCommand cmd, 
        CancellationToken ct
    ) where TCommand : class, ICommand<TResult>;

    Task OnEventAsync<TEvent>(
        Func<TEvent, CancellationToken, Task> next, 
        TEvent evt, 
        CancellationToken ct
    ) where TEvent : class, IEvent;
        
    Task<TResult> OnQueryAsync<TQuery, TResult>(
        Func<TQuery, CancellationToken, Task<TResult>> next, 
        TQuery query, 
        CancellationToken ct
    ) where TQuery : class, IQuery<TResult>;
}

You receive a delegate for the next pipe and the entity, so the concept is very simple: either do some work before or after invoking the next pipe, or break the chain by returning or throwing an exception.

public class IsItMondayAlreadyPipeline : Pipeline
{
    public override async Task<TResult> OnQueryAsync<TQuery, TResult>(
        Func<TQuery, CancellationToken, Task<TResult>> next, 
        TQuery query, 
        CancellationToken ct
    )
    {
        if(DateTime.Now.DayOfWeek == DayOfWeek.Monday)
            throw new InvalidOperationException("Today is monday, no data for you!");

        return await next(query, ct);
    }
}

Pipelines are executed by the same order they are added to the container so, to be deterministic, don’t scan the assemblies for classes implementing IPipeline.

Commands pipeline

Intercept commands sent into the mediator by implementing the methods OnCommandAsync:

Queries pipeline

Intercept queries being fetched from the mediator by implementing the methods OnQueryAsync:

Events pipeline

Intercept events before being broadcasted by the mediator into all the handlers by implementing the method OnEventAsync:

The project

To make it easier, we are going to leverage on the previous article and continue from there. As a reminder, we implemented an endpoint to manage products with the following:

GET /products — search for products using some filters (SearchProductsQuery);
GET /products/{id} — get a product by its unique identifier (GetProductByIdQuery);
POST /products — create a product (CreateProductCommand and CreatedProductEvent);
PUT /products/{id} — update a product by its unique identifier (UpdateProductCommand and UpdatedProductEvent);
DELETE /products/{id} — delete a product by its unique identifier (DeleteProductCommand and DeletedProductEvent);

The complete source code can be found on GitHub.

The pipelines

Since the objective of this article is to show how to implement pipelines in the mediator, the following should be enough:

LoggingPipeline — serializes every command, queries, events and results as JSON into the log if Trace is enabled;
TimeoutPipeline — cancels the handler execution if it takes more than a given set of time;

Start by creating a Pipelines folder at the project root level.

LoggingPipeline

Because we don’t want logging to affect the timeout, this will be the first pipeline to be added to the chain.

Inside the Pipelines folder, create a LoggingPipeline class implementing IPipeline. This pipeline will receive an ILogger instance and use System.Text.Json to serialize the objects:

public class LoggingPipeline : IPipeline
{
    private readonly ILogger<LoggingPipeline> _logger;
    private readonly JsonSerializerOptions _serializerOptions = new JsonSerializerOptions
    {
        WriteIndented = true
    };

    public LoggingPipeline(ILogger<LoggingPipeline> logger)
    {
        _logger = logger;
    }

    public async Task OnCommandAsync<TCommand>(Func<TCommand, CancellationToken, Task> next, TCommand cmd, CancellationToken ct) 
        where TCommand : class, ICommand
    {
        Log("Command: {command}", cmd);

        await next(cmd, ct);
    }

    public async Task<TResult> OnCommandAsync<TCommand, TResult>(Func<TCommand, CancellationToken, Task<TResult>> next, TCommand cmd, CancellationToken ct) 
        where TCommand : class, ICommand<TResult>
    {
        Log("Command: {command}", cmd);

        var result = await next(cmd, ct);

        Log("Command.Result: {commandResult}", result);

        return result;
    }

    public async Task OnEventAsync<TEvent>(Func<TEvent, CancellationToken, Task> next, TEvent evt, CancellationToken ct) 
        where TEvent : class, IEvent
    {
        Log("Event: {event}", evt);

        await next(evt, ct);
    }

    public async Task<TResult> OnQueryAsync<TQuery, TResult>(Func<TQuery, CancellationToken, Task<TResult>> next, TQuery query, CancellationToken ct) 
        where TQuery : class, IQuery<TResult>
    {
        Log("Query: {query}", query);

        var result = await next(query, ct);

        Log("Query.Result: {queryResult}", result);

        return result;
    }

    private void Log<T>(string message, T instance)
    {
        if (_logger.IsEnabled(LogLevel.Trace))
            _logger.LogTrace(message, JsonSerializer.Serialize(instance, _serializerOptions));
    }
}

Open the Startup.cs file and register the pipeline into the mediator:

services.AddMediator(o =>
{
    o.AddPipeline<LoggingPipeline>();
    
    o.AddHandlersFromAssemblyOf<Startup>();
});

Open the appsettings.development.json file and set the default log level to Trace:

{
  "Logging": {
    "LogLevel": {
      "Default": "Trace",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

If you now start the server and do some actions in the API, like creating or searching for products, you should start seeing your objects being serialized:

As a note, if you find this helpful for your APIs, you can use the NuGet SimpleSoft.Mediator.Microsoft.Extensions.LoggingPipeline. Just give a look at the Startup.cs file in the example API.

TimeoutPipeline

Inside the Pipelines folder, create a TimeoutPipeline class implementing IPipeline. For simplicity, the timeout value will be fixed, but could be received as an options from the container.

public class TimeoutPipeline : IPipeline
{
    private static readonly TimeSpan Timeout = TimeSpan.FromMilliseconds(500);

    public async Task OnCommandAsync<TCommand>(Func<TCommand, CancellationToken, Task> next, TCommand cmd, CancellationToken ct) 
        where TCommand : class, ICommand
    {
        using var cts = CreateCancellationTokenSource(ct);

        await next(cmd, cts.Token);
    }

    public async Task<TResult> OnCommandAsync<TCommand, TResult>(Func<TCommand, CancellationToken, Task<TResult>> next, TCommand cmd, CancellationToken ct) 
        where TCommand : class, ICommand<TResult>
    {
        using var cts = CreateCancellationTokenSource(ct);

        return await next(cmd, cts.Token);
    }

    public async Task OnEventAsync<TEvent>(Func<TEvent, CancellationToken, Task> next, TEvent evt, CancellationToken ct) 
        where TEvent : class, IEvent
    {
        using var cts = CreateCancellationTokenSource(ct);

        await next(evt, cts.Token);
    }

    public async Task<TResult> OnQueryAsync<TQuery, TResult>(Func<TQuery, CancellationToken, Task<TResult>> next, TQuery query, CancellationToken ct) 
        where TQuery : class, IQuery<TResult>
    {
        using var cts = CreateCancellationTokenSource(ct);

        return await next(query, cts.Token);
    }

    private static CancellationTokenSource CreateCancellationTokenSource(CancellationToken ct)
    {
        var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
        cts.CancelAfter(Timeout);

        return cts;
    }
}

Once again, open the Startup.cs file and register the pipeline into the mediator after the logging pipe:

services.AddMediator(o =>
{
    o.AddPipeline<LoggingPipeline>();
    o.AddPipeline<TimeoutPipeline>();
    
    o.AddHandlersFromAssemblyOf<Startup>();
});

If you now open any of your handlers and add an Task.Delay(1000, ct) into the HandleAsync methods you should receive a TaskCanceledException. I added one when searching for products:

If you look at the stack trace, you’ll see the invocation order was kept:

ProductsController
    MicrosoftFetcher (internal class used by the mediator)
        LoggingPipeline
            TimeoutPipeline
                SearchProductsQueryHandler

The project structure with pipeline classes:

The final Startup.cs file:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen();

        services.AddDbContext<ApiDbContext>(o =>
        {
            o.UseInMemoryDatabase("ApiDbContext");
        });

        services.AddMediator(o =>
        {
            o.AddPipeline<LoggingPipeline>();
            o.AddPipeline<TimeoutPipeline>();
            o.AddHandlersFromAssemblyOf<Startup>();
        });
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        app.UseDeveloperExceptionPage();

        app.UseSwagger();

        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "Mediator ExampleApi V1");
        });

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

Conclusion

I hope this article gave you a good idea about mediator pipelines and how you can use them to empower your solutions, making them more resilient to developer mistakes (like forgetting to save changes into the database).

For me, this is one of the strongest aspects of the mediator pattern and one of the main reason I always use this pattern even when implementing minimum viable products.