DEV Community: Fabrizio Bagalà

Response Compression in ASP.NET

Fabrizio Bagalà — Wed, 19 Jul 2023 07:45:32 +0000

Given that network bandwidth is a finite resource, optimizing its usage can markedly improve your application's performance. One effective strategy for maximizing network bandwidth utilization is response compression. It involves not only reducing the size of data transmitted from the server to the client, but can greatly improve the responsiveness of an application.

Configuration

Enabling response compression in ASP.NET requires you to do two things:

Use AddResponseCompression to add the response compression service to the service container.
Use UseResponseCompression to enable response compression middleware in the request processing pipeline.

❗️ Important
Response compression middleware must be registered before other middleware that might write into the response.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression();

var app = builder.Build();

app.UseResponseCompression();

app.UseHttpsRedirection();

app.MapGet("/", () => "Hello World!");

app.Run();

Compression with HTTPS

Due to inherent security risks, response compression for HTTPS connections is disabled by default. However, if you need to use this feature, it can be enabled by setting the EnableForHttps option to true.

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
});

Using response compression over HTTPS can expose you to CRIME and BREACH attacks. These attacks can be mitigated in ASP.NET with antiforgery tokens.

The following is an example of a minimal API code that uses response compression with HTTPS enabled and implements antiforgery token checking:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAntiforgery(options => options.HeaderName = "X-CSRF-TOKEN");

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
});

var app = builder.Build();

app.UseHttpsRedirection();

app.UseResponseCompression();

app.MapGet("/generate-token", (IAntiforgery antiforgery, HttpContext httpContext) =>
{
    var tokens = antiforgery.GetAndStoreTokens(httpContext);
    return Task.FromResult(tokens.RequestToken);
});

app.MapPost("/", async (IAntiforgery antiforgery, HttpContext httpContext) =>
{
    try
    {
        await antiforgery.ValidateRequestAsync(httpContext);
        return Results.Ok("Hello World");
    }
    catch
    {
        return Results.BadRequest("Invalid CSRF token");
    }
});

app.Run();

In this code, when you make a GET request to /generate-token, the server generates an antiforgery token and returns it. When you make a POST request to /, you should include this token in the request header with the name X-CSRF-TOKEN. The Antiforgery middleware will then validate the token. If the validation is successful, the response will be Hello World. Otherwise, the response will be Invalid CSRF token.

Providers

A compression provider is a component that implements a specific compression algorithm. It is used to compress data before it is sent to the client.

When you invoke the AddResponseCompression method, two compression providers are included by default:

BrotliCompressionProvider, using the Brotli algorithm.
GzipCompressionProvider, using the Gzip algorithm.

Brotli is the default compression setting if the client supports this compressed data format. However, if the client does not support Brotli but does support Gzip compression, then Gzip becomes the default compression method.

Also, it is important to note that when you add a specific compression provider, other providers will not be included automatically. As an instance, if you have only explicitly included the Gzip compression provider, the system will not add any other compression providers.

Here is an example where you enable response compression for HTTPS requests and add the response compression providers Brotli and Gzip:

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
});

You can set the compression level with BrotliCompressionProviderOptions and GzipCompressionProviderOptions. By default, both Brotli and Gzip compression providers use the fastest compression level, known as CompressionLevel.Fastest. This may not result in the most efficient compression. If you are aiming for the best compression, you should adjust the response compression middleware settings for optimal compression.

Compression Level	Value	Description
Optimal	0	The compression operation should optimally balance compression speed and output size.
Fastest	1	The compression operation should complete as quickly as possible, even if the resulting file is not optimally compressed.
NoCompression	2	No compression should be performed on the file.
SmallestSize	3	The compression operation should create output as small as possible, even if the operation takes a longer time to complete.

builder.Services.Configure<BrotliCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.Fastest;
});

builder.Services.Configure<GzipCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.SmallestSize;
});

Custom providers

A custom compression provider is a class that inherits from the ICompressionProvider interface to provide a custom compression method for HTTP responses.

Unlike the other examples, this time I decided to create a real provider that you can reuse in your applications. The provider I am going to make is DeflateCompressionProvider, which takes advantage of the Deflate algorithm.

First, I define the options that I will use in the provider. I implement within it the Level property, specifying which compression level to use for the stream. The default setting is Fastest.

public class DeflateCompressionProviderOptions : IOptions<DeflateCompressionProviderOptions>
{
    public CompressionLevel Level { get; set; } = CompressionLevel.Fastest;

    DeflateCompressionProviderOptions IOptions<DeflateCompressionProviderOptions>.Value => this;
}

Next, I create the compression provider using the built-in DeflateStream class as the compression algorithm, specifying in its constructor:

the stream to be compressed;
one of the values in the Level enumeration property of options;
true to leave the stream object open after disposing the DeflateStream object.

In addition, I specify in the EncodingName property the encoding name that will be used in the Accept-Encoding request header and the Content-Encoding response header. I also set the SupportsFlush property to true with which I go to indicate whether the specified provider supports Flush and FlushAsync.

public class DeflateCompressionProvider : ICompressionProvider
{
    public DeflateCompressionProvider(IOptions<DeflateCompressionProviderOptions> options)
    {
        ArgumentNullException.ThrowIfNull(nameof(options));

        Options = options.Value;
    }

    private DeflateCompressionProviderOptions Options { get; }

    public string EncodingName => "deflate";
    public bool SupportsFlush => true;

    public Stream CreateStream(Stream outputStream)
        => new DeflateStream(outputStream, Options.Level, leaveOpen: true);
}

Finally, I add the newly created compression provider into the application when I configure response compression:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<DeflateCompressionProvider>();
});

builder.Services.Configure<DeflateCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.Optimal;
});

var app = builder.Build();

app.UseHttpsRedirection();

app.UseResponseCompression();

app.MapGet("/", () => "Hello World!");

app.Run();

MIME types

The middleware for response compression provides a default collection of MIME types that can be compressed. For a comprehensive list of supported MIME types, refer to the source code.

You can modify or supplement the MIME types by using ResponseCompressionOptions.MimeTypes.

⚠️ Warning
Wildcard MIME types, such as text/*, are not supported.

In the following example, a MIME type is added for image/svg+xml in order to compress .svg files:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
    options.MimeTypes = ResponseCompressionDefaults.MimeTypes.Concat(new[] { "image/svg+xml" });
});

var app = builder.Build();

app.UseResponseCompression();

Benchmark

For a more in-depth understanding of how much bandwidth can be saved, let's use the following minimal API:

app.MapGet("/", () => Results.Ok(
    Enumerable.Range(1, 500).Select(num => new
    {
        Id = num, 
        Description = $"Hello World #{num}", 
        DayOfWeek = (DayOfWeek)Random.Shared.Next(0, 6)
    })));

Using the different compression providers listed above, including the one I made myself, and the different compression levels used, we examine the results obtained:

Provider	Compression level	Response size	Percentage decrease
None	None	28,93 KB	baseline
Gzip	NoCompression	29,00 KB	-0.2% (increase)
Gzip	Fastest	3,60 KB	87,6%
Gzip	Optimal	3,32 KB	88,5%
Gzip	SmallestSize	3,06 KB	89,4%
Brotli	NoCompression	4,14 KB	85,7%
Brotli	Fastest	3,29 KB	88,6%
Brotli	Optimal	1,74 KB	94,0%
Brotli	SmallestSize	1,74 KB	94,0%
Deflate	NoCompression	28,99 KB	-0.2% (increase)
Deflate	Fastest	3,57 KB	87,7%
Deflate	Optimal	3,29 KB	88,6%
Deflate	SmallestSize	3,04 KB	89,5%

🔎 Insight
The formula for calculating the percentage decrease is as follows:
Percentage decrease = ((Original size - Compressed size) / Original size) * 100

The first entry, None, indicates the absence of a compression provider. It provides a baseline for understanding the effect of using different compression providers.

Next, the compression provider Gzip is examined. When it is used at the NoCompression level, it introduces a small increase in response size, indicating a small overhead associated with compression attempted, but not performed. When the compression level is increased to Fastest, the effectiveness of Gzip in reducing response size becomes apparent. Moving further to the Optimal level, Gzip demonstrates significant improvement, suggesting an ideal balance between compression speed and efficiency. At the SmallestSize level, Gzip attempts to reduce response size as much as possible, regardless of the time required for compression.

The compression provider Brotli shows a different behavior. At the NoCompression level, Brotli is much more efficient than Gzip. When set at the Fastest level, Brotli is shown to be very effective in reducing response size. Interestingly, at both the Optimal and SmallestSize levels, Brotli outperforms Gzip, achieving significantly better compression efficiency.

Finally, we analyze the compression provider Deflate. Like Gzip, at the NoCompression level it slightly increases the size of the response. Instead at the Fastest, Optimal, and SmallestSize levels, Deflate achieves similar compression efficiency to Gzip.

In summary, these results underscore the effectiveness of various compression providers in optimizing ASP.NET responses. It is particularly noteworthy that Brotli emerges as the most efficient provider, especially at the Optimal and SmallestSize compression levels.

Conclusion

In this article, we explored optimizing ASP.NET application performance through response compression. We discussed how to configure and enable response compression, highlighting the need to balance performance with security considerations, especially in HTTPS contexts.

We also examined the use of different compression providers like Brotli and Gzip, emphasizing how the right provider choice can significantly impact performance. Additionally, we considered implementing custom compression providers for specific needs.

Concluding, through practical benchmarks, we demonstrated the effectiveness of various compression methods, underscoring the importance of choosing the most suitable solution to optimize bandwidth usage and enhance application responsiveness.

References

Response compression in ASP.NET Core

Fluent Assertions: Fluently Assert the Result of .NET Tests

Fabrizio Bagalà — Tue, 11 Jul 2023 17:33:16 +0000

ℹ️ Information
The code in the following article was tested on .NET and ASP.NET 6 and 7.

Fluent Assertions was created to provide a more expressive way of writing assertions in .NET unit tests. Typically, assertions in unit tests can be syntactically complex and not very expressive, which makes them hard to read and understand. Fluent Assertions aims to make assertions more human-readable by using a natural language syntax.

This library extends the traditional assertions provided by frameworks like MSTest, NUnit, or XUnit by offering a more extensive set of extension methods. Fluent Assertions supports a wide range of types like collections, strings, and objects and even allows for more advanced assertions like throwing exceptions.

Installation

You can install Fluent Assertions through the NuGet Package Manager:

Install-Package FluentAssertions

Or using the .NET CLI from a terminal window:

dotnet add package FluentAssertions

First assertion

Suppose you have an integer variable result:

var result = 10;

In order to check the value of the integer variable result, you can write the assertion in the following way:

result.Should().Be(expectedValue)

where expectedValue is the value you expect result to be. In this expression, the Should() extension method plays a key role, as it serves as the entry point for the Fluent Assertions library's functionality.

One of the primary strengths of Should() is its contribution to readability. By using Should(), the assertions begin to resemble natural language. Take for example result.Should().Be(10) it reads almost like an english sentence: "Result should be 10". This natural flow makes it far simpler for developers to comprehend what exactly is being tested.

Furthermore, Should() empowers the utilization of the fluent interface pattern. This design allows for a seamless chaining of methods, which not only keeps the code succinct, but also substantially augments the expressiveness of tests.

Additionally, the Fluent Assertions library is structured to support extensive customization and flexibility through the methods available after calling Should(). With a rich set of options such as BeGreaterThan(), BeOfType() and many others, it allows for crafting assertions that can efficiently address a wide range of testing scenarios.

Another significant aspect of using Should() is how it impacts maintenance and communication. Tests often double as documentation, providing insights into the expected behavior of code. When Should() is employed to craft assertions, the tests closely mirror spoken language. This closeness is invaluable as it not only makes maintenance easier but also facilitates clear communication among developers. This is particularly beneficial for those who may not have an in-depth familiarity with the codebase.

Nullable types

For asserting whether a variable has (not) value or is (not) null, the following methods can be used:

int? result = null;

result.Should().BeNull();
result.Should().HaveValue();

result.Should().NotBeNull();
result.Should().NotHaveValue();

Furthermore, it is possible to verify a nullable type via a predicate:

int? result = 10;

result.Should().Match(x => !x.HasValue);

Booleans

For asserting whether a variable is true or false, you can use:

var result = true;
var otherBoolean = true;

result.Should().BeTrue();
result.Should().BeFalse();
result.Should().Be(otherBoolean);
result.Should().NotBe(otherBoolean);

Another interesting method for booleans is Imply(), which exploits the concept of boolean implication.

var result = false;
var otherBoolean = true;

result.Should().Imply(otherBoolean);

Boolean implication A implies B simply means "if A is true, then B is also true". This implies that if A is not true, then B can be anything. The symbol used to denote implies is A => B. Thus:

A	B	A => B
T	T	T
T	F	F
F	T	T
F	F	T

A => B is an abbreviation for (not A) or B, i.e., "either A is false, or B must be true".

Strings

For asserting whether a string is null, empty, or contains (not) whitespace only, you have several methods at your disposal:

var result = "This is an example";

result.Should().BeNull();
result.Should().BeEmpty();
result.Should().HaveLength(0);
result.Should().BeNullOrWhiteSpace();

result.Should().NotBeNull();
result.Should().NotBeEmpty();
result.Should().NotBeNullOrWhiteSpace();

To ensure the characters in a string are all (not) upper or lower cased, you can use the following assertions:

var result = "This is an example";

result.Should().BeUpperCased();
result.Should().BeLowerCased();

result.Should().NotBeUpperCased();
result.Should().NotBeLowerCased();

⚠️ Warning
Numbers and special characters do not have casing, so BeUpperCased and BeLowerCased will always fail on a string that contains anything but alphabetic characters.

Of course, there are also other methods for string assertions:

var result = "This is an example";

result.Should().Be("This is an example");
result.Should().BeEquivalentTo("THIS IS AN EXAMPLE");

result.Should().NotBe("This is another example");
result.Should().NotBeEquivalentTo("THIS IS ANOTHER EXAMPLE");

result.Should().BeOneOf("That is an example", "This is an example");

result.Should().Contain("is an");
result.Should().Contain("is an", AtMost.Times(5));
result.Should().ContainAll("should", "contain", "all", "of", "these");
result.Should().ContainAny("any", "of", "these", "will", "do");
result.Should().ContainEquivalentOf("THIS IS AN EXAMPLE");
result.Should().ContainEquivalentOf("THIS IS AN EXAMPLE", Exactly.Thrice());

result.Should().NotContain("is an");
result.Should().NotContainAll("can", "contain", "some", "but", "not", "all");
result.Should().NotContainAny("cannot", "contain", "any", "of", "these");
result.Should().NotContainEquivalentOf("THIS IS ANOTHER EXAMPLE");

result.Should().StartWith("This");
result.Should().StartWithEquivalentOf("THIS");

result.Should().NotStartWith("That");
result.Should().NotStartWithEquivalentOf("THAT");

result.Should().EndWith("an example");
result.Should().EndWithEquivalentOf("AN EXAMPLE");

result.Should().NotEndWith("an other example");
result.Should().NotEndWithEquivalentOf("AN OTHER EXAMPLE");

📝 Note
All methods ending with EquivalentOf are case insensitive.

If you prefer a more fluent syntax than Exactly.Once(), AtLeast.Twice(), AtMost.Times(5) and so on, you can proceed as follows:

var result = "This is an example";

result.Should().Contain("is an", 1.TimesExactly()); // equivalent to Exactly.Once()
result.Should().Contain("is an", 2.TimesOrMore());  // equivalent to AtLeast.Twice()
result.Should().Contain("is an", 5.TimesOrLess());  // equivalent to AtMost.Times(5)

In addition, the Match, NotMatch, MatchEquivalentOf and NotMatchEquivalentOf methods support the following wildcards in the pattern:

Wildcard specifier	Matches
* (asterisk)	Zero or more characters in that position.
? (question mark)	Exactly one character in that position.

⚠️ Warning
The wildcard pattern does not support regular expressions.

For instance, if you would like to assert that some email address is correct, use this:

var result = "john.doe@example.com";

result.Should().Match("*@*.com");

Numerics

For asserting a numeric variable, you have several methods at your disposal:

var result = 10;

result.Should().Be(10);
result.Should().NotBe(5);
result.Should().BeGreaterThan(5);
result.Should().BeGreaterThanOrEqualTo(5);
result.Should().BeLessThan(15);
result.Should().BeLessThanOrEqualTo(15);
result.Should().BePositive();
result.Should().BeNegative();

result.Should().BeInRange(5, 15);
result.Should().NotBeInRange(11, 20);

result.Should().Match(x => x % 2 == 0);

result.Should().BeOneOf(5, 10, 15);

The Should().Be() and Should().NotBe() methods are not available for floats and doubles, this is because floating-point variables are inherently imprecise and should never be compared for equality. Instead, you can use BeInRange() or the following method:

var result = 3.1415927F;

result.Should().BeApproximately(3.14F, 0.01F);

This will verify that the value of the float is between 3.139 and 3.141.

Conversely, to assert that the value differs by an amount, you can do this:

var result = 3.5F;

result.Should().NotBeApproximately(2.5F, 0.5F);

This will verify that the value of the float is not between 2.0 and 3.0.

Dates and times

For asserting a DateTime, several methods are provided:

var result = new DateTime(2023, 07, 07, 12, 15, 00, DateTimeKind.Utc);

result.Should().Be(7.July(2023).At(12, 15));
result.Should().BeAfter(1.June(2023));
result.Should().BeBefore(1.August(2023));
result.Should().BeOnOrAfter(1.June(2023));
result.Should().BeOnOrBefore(1.August(2023));
result.Should().BeSameDateAs(7.July(2023).At(12, 16));

result.Should().NotBe(1.July(2023).At(12, 15));
result.Should().NotBeAfter(2.August(2023));
result.Should().NotBeBefore(1.June(2023));
result.Should().NotBeOnOrAfter(2.August(2023));
result.Should().NotBeOnOrBefore(1.June(2023));
result.Should().NotBeSameDateAs(6.July(2023));

result.Should().BeIn(DateTimeKind.Utc);

result.Should().BeOneOf(
    7.July(2023).At(12, 15),
    7.July(2023).At(13, 15),
    7.July(2023).At(14, 15)
);

If you only care about specific parts of a date or time, use the following assertion methods instead:

var result = new DateTime(2023, 07, 07, 12, 15, 00, DateTimeKind.Utc);

result.Should().HaveDay(7);
result.Should().HaveMonth(7);
result.Should().HaveYear(2023);
result.Should().HaveHour(12);
result.Should().HaveMinute(15);
result.Should().HaveSecond(0);

result.Should().NotHaveDay(1);
result.Should().NotHaveMonth(6);
result.Should().NotHaveYear(2022);
result.Should().NotHaveHour(11);
result.Should().NotHaveMinute(16);
result.Should().NotHaveSecond(1);

To assert that a date/time is (not) within a specified time span from another date/time value you can use this method:

result.Should().BeCloseTo(7.July(2023).At(12, 15), 2.Seconds());
result.Should().NotBeCloseTo(8.July(2023), 1.Hours());

This can be particularly useful if your database truncates date/time values.

Collections

For asserting a collection, both have two possibilities:

1️⃣ Perform assertions on the entire collection

IEnumerable<int> collection = new[] { 1, 2, 3, 4 };

collection.Should().BeEmpty();
collection.Should().BeNullOrEmpty();
collection.Should().NotBeNullOrEmpty();

collection.Should().Equal(new List<int> { 1, 2, 3, 4 });
collection.Should().Equal(1, 2, 3, 4);
collection.Should().BeEquivalentTo(new[] { 1, 2, 3, 4 });

collection.Should().NotEqual(new List<int> { 5, 6, 7, 8 });
collection.Should().NotBeEquivalentTo(new[] { 5, 6, 7, 8 });

collection.Should().HaveCount(4);
collection.Should().HaveCountGreaterThan(3);
collection.Should().HaveCountGreaterThanOrEqualTo(4);
collection.Should().HaveCountLessThan(5);
collection.Should().HaveCountLessThanOrEqualTo(4);
collection.Should().HaveSameCount(new[] { 6, 2, 0, 5 });

collection.Should().NotHaveCount(3);
collection.Should().NotHaveSameCount(new[] { 6, 2, 0 });

collection.Should().StartWith(1);
collection.Should().StartWith(new[] { 1, 2 });
collection.Should().EndWith(4);
collection.Should().EndWith(new[] { 3, 4 });

collection.Should().BeSubsetOf(new[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, });

collection.Should().ContainSingle();
collection.Should().ContainSingle(x => x > 3);

collection.Should().Contain(x => x > 3);
collection.Should().Contain(collection, "", 5, 6); // It should contain the original items, plus 5 and 6.

collection.Should().NotContain(10);
collection.Should().NotContain(new[] { 10, 11 });
collection.Should().NotContain(x => x > 10);

collection.Should().OnlyContain(x => x < 10);
collection.Should().ContainItemsAssignableTo<int>();

collection.Should().ContainInOrder(new[] { 1, 5, 8 });
collection.Should().NotContainInOrder(new[] { 5, 1, 2 });

collection.Should().ContainInConsecutiveOrder(new[] { 2, 5, 8 });
collection.Should().NotContainInConsecutiveOrder(new[] { 1, 5, 8 });

collection.Should().NotContainNulls();

IEnumerable<int> otherCollection = new[] { 1, 2, 3, 4, 1 };
IEnumerable<int> anotherCollection = new[] { 10, 20, 30, 40, 10 };
collection.Should().IntersectWith(otherCollection);
collection.Should().NotIntersectWith(anotherCollection);

const int element = 2;
const int successor = 3;
const int predecessor = 1;
collection.Should().HaveElementPreceding(successor, element);
collection.Should().HaveElementSucceeding(predecessor, element);

To assert that a set contains elements in a certain order, it is sufficient to use one of the following methods:

IEnumerable<int> collection = new[] { 1, 2, 3, 4 };

collection.Should().BeInAscendingOrder();
collection.Should().BeInDescendingOrder();

collection.Should().NotBeInAscendingOrder();
collection.Should().NotBeInDescendingOrder();

collection.Should().BeInAscendingOrder(x => x.SomeProperty);
collection.Should().BeInDescendingOrder(x => x.SomeProperty);

collection.Should().NotBeInAscendingOrder(x => x.SomeProperty);
collection.Should().NotBeInDescendingOrder(x => x.SomeProperty);

As mentioned at the beginning of the article, multiple assertions can be concatenated with each other using the And property:

IEnumerable<int> collection = new[] { 1, 2, 3, 4 };

collection.Should().NotBeEmpty()
    .And.HaveCount(4)
    .And.ContainInOrder(new[] { 2, 3 })
    .And.ContainItemsAssignableTo<int>();

2️⃣ Perform individual assertions on all elements of a collection

var collection = new[]
{
    new { Id = 1, Name = "John", Attributes = new string[] { } },
    new { Id = 2, Name = "Jane", Attributes = new string[] { "attr" } }
};

collection.Should().SatisfyRespectively(
    first =>
    {
        first.Id.Should().Be(1);
        first.Name.Should().StartWith("J");
        first.Attributes.Should().NotBeNull();
    },
    second =>
    {
        second.Id.Should().Be(2);
        second.Name.Should().EndWith("e");
        second.Attributes.Should().NotBeEmpty();
    });

If you need to perform the same assertion on all elements of a collection:

var collection = new[]
{
    new { Id = 1, Name = "John", Attributes = new string[] { } },
    new { Id = 2, Name = "Jane", Attributes = new string[] { "attr" } }
};

collection.Should().AllSatisfy(x =>
{
    x.Id.Should().BePositive();
    x.Name.Should().StartWith("J");
    x.Attributes.Should().NotBeNull();
});

If you need to perform individual assertions on all elements of a collection without setting expectation about the order of elements:

var collection = new[]
{
    new { Id = 1, Name = "John", Attributes = new string[] { } },
    new { Id = 2, Name = "Jane", Attributes = new string[] { "attr" } }
};

collection.Should().Satisfy(
    e => e.Id == 2 && e.Name == "Jane" && e.Attributes == null,
    e => e.Id == 1 && e.Name == "John" && e.Attributes != null && e.Attributes.Length > 0);

Exceptions

Imagine you have the SampleClass class:

public class SampleClass
{
    public void SampleMethod(string? value)
    {
        ArgumentNullException.ThrowIfNull(value);
    }
}

With Fluent Assertions, you can check whether a given method throws a specific exception. In this case, using xUnit, we check that SampleMethod throws the ArgumentNullException exception when the argument is null:

public class SampleClassTests
{
    [Fact]
    public void SampleMethodTest_WithoutValue_ThrowsException()
    {
        // Arrange
        var subject = new SampleClass();

        // Act
        Action act = () => subject.SampleMethod(null);

        // Assert
        act.Should().Throw<ArgumentNullException>()
            .WithParameterName("value");
    }
}

You can also test the case when SampleMethod throws no exception, that is, when the argument is other than null:

public class SampleClassTests
{
    [Fact]
    public void SampleMethodTest_WithValue_NoThrows()
    {
        // Arrange
        var subject = new SampleClass();

        // Act
        Action act = () => subject.SampleMethod("test");

        // Assert
        act.Should().NotThrow();
    }
}

Finally, you can also check whether or not a method executed asynchronously throws an exception:

public class SampleClass
{
    public Task<string> SampleMethodAsync(string? value)
    {
        return string.IsNullOrEmpty(value)
            ? Task.FromException<string>(new ArgumentException())
            : Task.FromResult(value);
    }
}

public class SampleClassTests
{
    [Fact]
    public async Task SampleMethodAsync_WithoutValue_ThrowsException()
    {
        // Arrange
        var sampleClass = new SampleClass();

        // Act
        Func<Task<string>> act = async () => await sampleClass.SampleMethodAsync(null);

        // Assert
        await act.Should().ThrowAsync<ArgumentException>();
    }

    [Fact]
    public async Task SampleMethodAsync_WithValue_NoThrows()
    {
        // Arrange
        var sampleClass = new SampleClass();

        // Act
        Func<Task<string>> act = async () => await sampleClass.SampleMethodAsync("test");

        // Assert
        await act.Should().NotThrowAsync();
    }
}

Object graph comparison

Consider a Person record with an associated Address and one or more associated EmailAddress:

public record Person(string FirstName, string LastName, Address Address, List<EmailAddress> EmailAddresses);

public record Address(string Street, string State, string City, string ZipCode);

public record EmailAddress(string Email, EmailType Type);

public enum EmailType
{
    Private,
    Work
}

And to have an equivalent PersonDto (also called DTO):

public record PersonDto(string FirstName, string LastName, Address AddressDto, List<EmailAddressDto> EmailAddressDtos);

public record AddressDto(string Street, string State, string City, string ZipCode);

public record EmailAddressDto(string Email, EmailType Type);

You might want to verify that all exposed members of all objects in the PersonDto object graph match the equally named members of the Person object graph.

You may assert the structural equality of two object graphs with the BeEquivalentTo() method:

personDto.Should().BeEquivalentTo(person);

Also, you can verify the inequality of two objects with NotBeEquivalentTo() method:

personDto.Should().NotBeEquivalentTo(person);

Let us see below the most common options that can be defined for both methods:

Recursion

By default, the comparison is recursive and recurs up to 10 levels deep. Despite this, you can force recursion as deep as possible with the AllowingInfiniteRecursion option:

personDto.Should().BeEquivalentTo(person, options => options.AllowingInfiniteRecursion());

or if you want to disable recursion just use the ExcludingNestedObjects option:

personDto.Should().BeEquivalentTo(person, options => options.ExcludingNestedObjects());

Matching members

All public members of the Person object must be available in the PersonDto with the same name. If any member is missing, an exception will be thrown. However, you can only include members that both graph objects have:

personDto.Should().BeEquivalentTo(person, options => options.ExcludingMissingMembers());

Selecting members

If you want, you can exclude some members using the Excluding option:

personDto.Should().BeEquivalentTo(person, options => options.Excluding(p => p.FirstName));

The Excluding option also accepts a lambda expression, which provides more flexibility in deciding which member to exclude:

personDto.Should().BeEquivalentTo(person, options => options.Excluding(p => p.FirstName == "John"));

You can also decide to exclude a member of a particular nested object based on its index:

personDto.Should().BeEquivalentTo(person, options => options.Excluding(p => p.EmailAddresses[1]));

You can use For and Exclude if you want to exclude a member on each nested object regardless of its index:

personDto.Should().BeEquivalentTo(person, options => options.For(p => p.EmailAddresses).Exclude(ea => ea.Type));

📝 Note
Excluding and ExcludingMissingMembers can be combined.

In a mirrored manner, specific properties or lambdas can be included using the Including option:

personDto.Should().BeEquivalentTo(person, options => options.Including(p => p.FirstName));
personDto.Should().BeEquivalentTo(person, options => options.Including(p => p.FirstName == "John"));

Including properties and/or fields

You can also configure whether to include or exclude the inclusion of all public properties and fields. This behavior can be modified:

// Include properties (which is the default)
personDto.Should().BeEquivalentTo(person, options => options.IncludingProperties());

// Include fields
personDto.Should().BeEquivalentTo(person, options => options.IncludingFields());

// Include internal properties as well
personDto.Should().BeEquivalentTo(person, options => options.IncludingInternalProperties());

// And the internal fields
personDto.Should().BeEquivalentTo(person, options => options.IncludingInternalFields());

// Exclude Fields
personDto.Should().BeEquivalentTo(person, options => options.ExcludingFields());

// Exclude Properties
personDto.Should().BeEquivalentTo(person, options => options.ExcludingProperties());

Comparing members with different names

Imagine you want to compare a Person and a PersonDto using BeEquivalentTo, but the first type has a FirstName property and the second has a PersonFirstName property. You can map them using the following option:

// Using names with the expectation member name first. Then the subject's member name.
personDto.Should().BeEquivalentTo(person, options => options.WithMapping("FirstName", "PersonFirstName"));

// Using expressions, but again, with expectation first, subject last.
personDto.Should().BeEquivalentTo(person, options => options.WithMapping<PersonDto>(p => p.FirstName, s => s.PersonFirstName));

Enums

By default, BeEquivalentTo() compares Enum members by the underlying numeric value of the Enum. However, you can compare an Enum by name only by using the ComparingEnumsByName option:

personDto.Should().BeEquivalentTo(person, options => options.ComparingEnumsByName());

Custom assertions

Creating a custom assertion allows you to encapsulate a more complex assertion logic that can be reused across multiple tests. This can be particularly useful when working with complex or domain-specific assertion logic that is not covered by the predefined assertion methods.

To create a custom assertion, you need to create an extension method for the type of object on which you want to assert. This extension method should contain the assertion logic and can use the existing assertion methods provided by Fluent Assertions. Finally, you need to apply the [CustomAssertion] attribute to your extension method to signal that it is a custom assertion method.

Here is an example:

public static class PersonAssertions
{
    [CustomAssertion]
    public static void NotBeDoe(this Person? person, string because = "", params object[] becauseArgs)
    {
        Execute.Assertion.ForCondition(person is not null)
            .BecauseOf(because, becauseArgs)
            .FailWith("Expected person not to be null.");

        Execute.Assertion.ForCondition(!string.IsNullOrEmpty(person!.FirstName))
            .BecauseOf(because, becauseArgs)
            .FailWith("Expected person's first name not to be null or empty.");

        Execute.Assertion.ForCondition(string.Equals(person.LastName, "doe", StringComparison.OrdinalIgnoreCase))
            .BecauseOf(because, becauseArgs)
            .FailWith("Expected person must not have last name Doe.");
    }
}

This code first verifies that the Person object is not null. If it is, it will throw an exception with the message "Expected person not to be null.".

Next, it checks whether the FirstName of the Person object is not null or empty. If it is, it will trigger an exception with the message "Expected person's first name not to be null or empty.".

Lastly, it confirms that the LastName of the Person object is not equal to "doe", ignoring case differences. If it is, an exception will be thrown with the message "Expected person must not have last name Doe.".

The because and becauseArgs parameters can be used to specify a custom reason for the assertion to hold true.

This is how to use the custom method:

public class PersonTests
{
    [Fact]
    public void Person_WithLastNameDoe_Fails()
    {
        var person = new Person("John", "Doe");

        person.NotBeDoe(); // Fails
    }
}

Assertion scopes

AssertionScope is a powerful function that allows multiple assertions to be grouped into a single scope. When you use it, all assertions within the scope are executed and any failures are reported together at the end. This is in contrast to the default behavior, in which test execution stops at the first failed assertion.

The advantage of using AssertionScope is that you can see all failed assertions in a single test execution, instead of correcting one, rerunning the tests, and then finding the next one. This can be especially useful when writing tests with multiple assertions and you want to get an overview of all the problems at once.

Here is how you can use AssertionScope:

public record Person(string FirstName, string LastName);

public class PersonTests
{
    [Fact]
    public void AssertionScopeTest()
    {
        var person = new Person("John", "Doe");

        using (new AssertionScope())
        {
            person.FirstName.Should().Be("Jane");
            person.LastName.Should().Be("Smith");
        }
    }
}

In this example, even though the first assertion fails, the second assertion is also executed, and both failures are reported together.

Execution time

Fluent Assertions also provides a method to assert that the execution time of particular method or action does not exceed a predefined value.

To check the execution time of a method, you can write:

public class SampleClass
{
    public string ExpensiveMethod()
    {
        var temp = string.Empty;
        for (var i = 0; i < short.MaxValue; i++)
        {
            temp += i;
        }
        return temp;
    }
}

public class SampleTests
{
    [Fact]
    public void SampleMethodTests()
    {
        var sampleClass = new SampleClass();
        sampleClass.ExecutionTimeOf(s => s.ExpensiveMethod()).Should().BeLessOrEqualTo(1.Seconds());
    }
}

Alternatively, to check the execution time of an arbitrary action, you can write in this other way:

Action someAction = () => Thread.Sleep(100);
someAction.ExecutionTime().Should().BeLessThanOrEqualTo(200.Milliseconds());

ExecutionTime supports the same assertions as TimeSpan, namely:

someAction.ExecutionTime().Should().BeLessThan(200.Milliseconds());
someAction.ExecutionTime().Should().BeGreaterThan(100.Milliseconds());
someAction.ExecutionTime().Should().BeGreaterThanOrEqualTo(100.Milliseconds());
someAction.ExecutionTime().Should().BeCloseTo(150.Milliseconds(), 50.Milliseconds());

If you are dealing with a Task, you can also assert that it completed within a specified period of time or not completed:

Func<Task> someAsyncWork = () => SomethingReturningATask();
await someAsyncWork.Should().CompleteWithinAsync(100.Milliseconds());
await someAsyncWork.Should().NotCompleteWithinAsync(100.Milliseconds());
await someAsyncWork.Should().ThrowWithinAsync<InvalidOperationException>(100.Milliseconds());

Conclusion

In this article, we have explored just some assertion methods of primitive types, collections, and exceptions, and we have also seen some advanced features such as creating custom assertions or checking the execution time of a single method.

All this leads us to the conclusion that Fluent Assertions is a valuable tool for any developer writing tests in .NET. Because of its emphasis on natural language syntax, it promotes greater readability, which is critical for understanding and maintaining efficient code bases. It also simplifies communication within teams, making it easier to convey the intention behind the tests.

References

FluentValidation: A Validation Library for .NET

Fabrizio Bagalà — Fri, 30 Jun 2023 15:41:32 +0000

FluentValidation is an open-source validation library for .NET. It was developed to provide a more flexible and customizable alternative to the Data Annotations. The library allows you to build validation rules using a fluent interface, which leads to cleaner and more readable code.

It supports .NET and ASP.NET and has extensive integration points, making it suitable for various types of applications.

Installation

You can install FluentValidation through the NuGet Package Manager:

Install-Package FluentValidation

Or using the .NET CLI from a terminal window:

dotnet add package FluentValidation

First validator

Imagine that you have a Person record:

public record Person(string FirstName, string LastName);

📝 Note
With FluentValidation you can use both class and record.

You would define a set of validation rules for this record by inheriting from AbstractValidator<Person>:

using FluentValidation;

public class PersonValidator : AbstractValidator<Person> 
{
    public PersonValidator() 
    {
        RuleFor(person => person.FirstName).NotEmpty().WithMessage("Please specify a first name");
        RuleFor(person => person.LastName).NotEmpty().WithMessage("Please specify a last name");
    }
}

To specify a validation rule for a particular property, call the RuleFor method, passing a lambda expression that indicates the property that you wish to validate.

To run the validator, instantiate the validator object and call the Validate method, passing in the object to validate:

Person person = new Person("John", "Doe");
PersonValidator validator = new PersonValidator();
ValidationResult result = validator.Validate(person);

The Validate method returns a ValidationResult object. This contains two properties:

IsValid - a boolean that says whether the validation succeeded.
Errors - a collection of ValidationFailure objects containing details about any validation failures.

You can also call ToString on the ValidationResult to combine all error messages into a single string. By default, the messages will be separated with new lines, but if you want to customize this behaviour you can pass a different separator character to ToString.

ValidationResult results = validator.Validate(person);
string allErrorMessages = results.ToString(", "); // Prints: Please specify a first name, Please specify a last name

📝 Note
If there are no validation errors, ToString() will return an empty string.

Complex properties

Validators can be re-used for complex properties. For example, given two record Person and Address:

public record Person(string FirstName, string LastName, Address Address);

public record Address(string Street, string State, string City, string ZipCode);

Define an AddressValidator:

public class AddressValidator : AbstractValidator<Address>
{
    public AddressValidator()
    {
        RuleFor(address => address.Street).NotEmpty().WithMessage("Please specify a street");
        RuleFor(address => address.State).NotEmpty().WithMessage("Please specify a state");
        RuleFor(address => address.City).NotEmpty().WithMessage("Please specify a city");
        RuleFor(address => address.ZipCode).Matches("^\\d{5}$").WithMessage("Invalid zip code");
    }
}

Add the AddressValidator to the PersonValidator:

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(person => person.FirstName).NotEmpty().WithMessage("Please specify a first name");
        RuleFor(person => person.LastName).NotEmpty().WithMessage("Please specify a last name");
        RuleFor(person => person.Address).SetValidator(new AddressValidator());
    }
}

Finally, when you call Validate on the PersonValidator, it goes through the validators defined in both the PersonValidator and AddressValidator and combines the results into a single ValidationResult.

📝 Note
If the child property is null, then the child validator will not be executed.

Collections

You can combine RuleForEach with SetValidator when the collection is of another complex objects. For instance, given the models:

public record Person(string FirstName, string LastName, Address Address, List<EmailAddress> EmailAddresses);

public record Address(string Street, string State, string City, string ZipCode);

public record EmailAddress(string Email, EmailType Type);

public enum EmailType
{
    Private,
    Work
}

The resulting validators will be:

public class EmailAddressValidator : AbstractValidator<EmailAddress>
{
    public EmailAddressValidator()
    {
        RuleFor(emailAddress => emailAddress.Email).EmailAddress().WithMessage("Invalid email");
        RuleFor(emailAddress => emailAddress.Type).IsInEnum().WithMessage("Invalid email type");
    }
}

public class AddressValidator : AbstractValidator<Address>
{
    public AddressValidator()
    {
        RuleFor(address => address.Street).NotEmpty().WithMessage("Please specify a street");
        RuleFor(address => address.State).NotEmpty().WithMessage("Please specify a state");
        RuleFor(address => address.City).NotEmpty().WithMessage("Please specify a city");
        RuleFor(address => address.ZipCode).Matches("^\\d{5}$").WithMessage("Invalid zip code");
    }
}

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(person => person.FirstName).NotEmpty().WithMessage("Please specify a first name");
        RuleFor(person => person.LastName).NotEmpty().WithMessage("Please specify a last name");
        RuleFor(person => person.Address).SetValidator(new AddressValidator());
        RuleForEach(person => person.EmailAddresses).SetValidator(new EmailAddressValidator());
    }
}

Alternatively, as of FluentValidation 8.5, you can also define rules for child collection elements in-line using the ChildRules method:

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(person => person.FirstName).NotEmpty().WithMessage("Please specify a first name");
        RuleFor(person => person.LastName).NotEmpty().WithMessage("Please specify a last name");
        RuleFor(person => person.Address).SetValidator(new AddressValidator());
        RuleForEach(person => person.EmailAddresses).ChildRules(emailAddressValidator =>
        {
            emailAddressValidator.RuleFor(emailAddress => emailAddress.Email).EmailAddress().WithMessage("Invalid email");
            emailAddressValidator.RuleFor(emailAddress => emailAddress.Type).IsInEnum().WithMessage("Invalid email type");
        });
    }
}

Cascade mode

Cascade mode is a configuration setting that determines how the library should execute validation rules when one of the rules fails. It checks whether the validation process should continue checking subsequent rules or whether it should stop immediately after encountering the first validation failure. This is particularly useful in scenarios where certain validation rules are contingent upon others or where performance is a critical concern and it is unnecessary to evaluate every rule if one has already failed.

The two cascade modes are:

Continue (the default) - always invokes all rules in a validator class, or all validators in a rule, depending on where it is used.
Stop - stops executing a validator class as soon as a rule fails, or stops executing a rule as soon as a validator fails, depending on where it is used.

⚠️ Warning
The Stop option is only available in FluentValidation 9.1 and newer. In older versions, you can use StopOnFirstFailure instead.

In addition, you can set two different levels:

1️⃣ ClassLevelCascadeMode: This is set at the validator class level. It dictates the default behavior for all the rules within that validator class. For example, if you set the cascade mode to Stop at the class level, it means that as soon as one validation rule fails for a property, the rest of the rules for that property will not be executed. This behavior will be applied to all the properties and their rules within that validator class unless a specific rule overrides it with its own setting.

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        ClassLevelCascadeMode = CascadeMode.Stop;

        RuleFor(person => person.FirstName).NotEmpty().WithMessage("Please specify a first name");
        RuleFor(person => person.LastName).NotEmpty().WithMessage("Please specify a last name");
        RuleFor(person => person.Address).SetValidator(new AddressValidator());
        RuleForEach(person => person.EmailAddresses).SetValidator(new EmailAddressValidator());
    }
}

2️⃣ RuleLevelCascadeMode: This is set for an individual validation rule. It overrides the Class Level setting for that particular rule. For instance, if you have set the cascade mode to Stop at the class level, but you want a specific rule to continue evaluating subsequent conditions even if one fails, you can set the cascade mode for that particular rule to Continue.

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        ClassLevelCascadeMode = CascadeMode.Stop;

        RuleFor(person => person.FirstName).NotEmpty().WithMessage("Please specify a first name");
        RuleFor(person => person.LastName).NotEmpty().WithMessage("Please specify a last name");
        RuleFor(person => person.Address).Cascade(CascadeMode.Continue).SetValidator(new AddressValidator());
        RuleForEach(person => person.EmailAddresses).SetValidator(new EmailAddressValidator());
    }
}

Severity level

Severity level is a way to categorize the importance or criticality of a validation failure. This feature allows you to mark specific validation rules with different levels of severity. This can be helpful in scenarios where you might want to treat different validation failures in distinct ways based on their criticality.

FluentValidation provides an enumeration called Severity with the following levels:

Error: This is the default severity level. It indicates that the validation failure is critical, and the data should not be processed further until the issue is resolved.
Warning: This level can be used to indicate that the validation failure is not critical and does not necessarily block further processing. However, it is important enough to warrant attention.
Info: This is the lowest level of severity. It can be used to indicate that the validation failure is more informational and may not require immediate action.

Here’s an example:

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(person => person.FirstName).NotEmpty().WithMessage("Please specify a first name").WithSeverity(Severity.Error);
        RuleFor(person => person.LastName).NotEmpty().WithMessage("Please specify a last name").WithSeverity(Severity.Error);
        RuleFor(person => person.Address).SetValidator(new AddressValidator()).WithSeverity(Severity.Warning);
        RuleForEach(person => person.EmailAddresses).SetValidator(new EmailAddressValidator()).WithSeverity(Severity.Info);
    }
}

Throw exception

Instead of returning a ValidationResult, you can alternatively tell FluentValidation to throw an exception if validation fails by using the ValidateAndThrow method:

Address address = new Address("Street 5", "Austin", "Texas", "73301");
List<EmailAddress> emailAddresses = new List<EmailAddress>
{
    new EmailAddress("john.doe@private.com", EmailType.Private),
    new EmailAddress("john.doe@work.com", EmailType.Work)
};
Person person = new Person("John", "Doe", address, emailAddresses);
PersonValidator validator = new PersonValidator();
validator.ValidateAndThrow(person);

The ValidateAndThrow method is an extension method and is equivalent to doing the following:

validator.Validate(person, options => options.ThrowOnFailures());

Asynchronous validation

Asynchronous validation allows you to perform validation checks that involve asynchronous operations. This is especially useful when you need to perform validation that involves calling external resources such as a database or an API, and you do not want to block the execution thread while waiting for the response.

Let's look at an example that checks whether a person ID is already in use using an external Web API:

public class PersonValidator : AbstractValidator<Person> 
{
    WebApiClient _client;

    public PersonValidator(WebApiClient client)
    {
        _client = client;

        RuleFor(person => person.Id).MustAsync(async (id, cancellation) => 
        {
            bool exists = await _client.ExistsAsync(id);
            return !exists;
        }).WithMessage("ID must be unique");
    }
}

Invoking the validator is essentially the same, but you should now invoke it by calling ValidateAsync:

PersonValidator validator = new PersonValidator(new WebApiClient());
ValidationResult result = await validator.ValidateAsync(person);

📝 Note
Calling ValidateAsync will run both synchronous and asynchronous rules.

⚠️ Warning
If your validator contains asynchronous validators or asynchronous conditions, it is important that you always call ValidateAsync on your validator and never Validate. If you call Validate, then an exception will be thrown.

As with synchronous operations, you can throw an exception if validation fails rather than return the ValidationResult. To do this, you use the asynchronous ValidateAndThrowAsync method:

PersonValidator validator = new PersonValidator();
await validator.ValidateAndThrowAsync(person);

Custom validators

Creating a custom validator in FluentValidation allows you to encapsulate a validation rule that can be reused in different validators.

Here is how to create custom validator to check whether a string contains only letters and has a certain length:

public static class CustomValidators
{
    public static IRuleBuilderOptions<T, string> MustBeLettersAndHaveLength<T>(this IRuleBuilder<T, string> ruleBuilder, int minLength, int maxLength) 
    {
        return ruleBuilder
            .NotEmpty().WithMessage("The field is required.")
            .Length(minLength, maxLength).WithMessage($"The field must be between {minLength} and {maxLength} characters long.")
            .Matches("^[a-zA-Z]+$").WithMessage("The field can only contain letters.");
    }
}

This extension method MustBeLettersAndHaveLength extends the IRuleBuilder interface and takes two additional parameters for minimum and maximum length. It chains the rules for NotEmpty, Length, and Matches for validating that the string is not empty, within a certain length, and contains only letters.

Now, you can use the extension method you just created within the PersonValidator:

public record Person(string FirstName, string LastName);

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(person => person.FirstName).MustBeLettersAndHaveLength(5, 20);
        RuleFor(person => person.LastName).MustBeLettersAndHaveLength(5, 20);
    }
}

Localization

FluentValidation comes ready with translations for its standard validation messages in various languages. Normally, it uses the language that is set in .NET's current user interface settings (CultureInfo.CurrentUICulture) to decide which language to display the messages in.

If you are using Visual Studio and taking advantage of its built-in feature for handling .resx files and their strongly-typed counterparts, you can localize a message by using a version of WithMessage that accepts a lambda expression:

RuleFor(person => person.FirstName).NotNull().WithMessage(x => MyLocalizedMessages.FirstNameRequired);

If you are employing IStringLocalizer for handling localization, the process is simple. You just need to inject your localizer into your validator, and utilize it inside a WithMessage callback, like this:

public class PersonValidator : AbstractValidator<Person> 
{
  public PersonValidator(IStringLocalizer<Person> localizer)
   {
    RuleFor(person => person.FirstName).NotNull().WithMessage(x => localizer["FirstName is required"]);
  }
}

If you want to replace all (or some) of FluentValidation’s default messages then you can do this by implementing a custom version of the ILanguageManager interface.

For example, the default message for the NotNull validator is '{PropertyName}' must not be empty.. If you wanted to replace this message for all uses of the NotNull validator in your application, you could write a custom Language Manager:

public class CustomLanguageManager : LanguageManager
{
    public CustomLanguageManager() 
    {
        AddTranslation("en", "NotNullValidator", "'{PropertyName}' is required.");
        AddTranslation("it-IT", "NotNullValidator", "'{PropertyName}' è richiesto.");
        AddTranslation("es-ES", "NotNullValidator", "'{PropertyName}' es necesario.");
    }
}

CultureInfo cultureInfo = new CultureInfo("es-ES");
Thread.CurrentThread.CurrentUICulture = cultureInfo;

ValidatorOptions.Global.LanguageManager = new CustomLanguageManager();

Person person = new Person(null!, "Doe");
PersonValidator validator = new PersonValidator();
ValidationResult result = validator.Validate(person);
Console.WriteLine(result.ToString()); // Prints: 'First Name' es necesario.

Testing

FluentValidation provides some extensions to assist you in testing your validator classes.

The TestValidate extension method can be used to invoke a validator for testing, and then perform assertions on the result. This makes writing tests for validators easier.

For instance, consider the Person record and its PersonValidator validator:

public record Person(string FirstName);

public class PersonValidator : AbstractValidator<Person>
{
   public PersonValidator()
   {
      RuleFor(person => person.FirstName).NotNull();
   }
}

You can verify the functionality of this validator by writing the following tests (using xUnit):

public class PersonValidatorTests
{
    private readonly PersonValidator _validator;

    public PersonValidatorTests()
    {
        _validator = new PersonValidator();
    }

    [Fact]
    public void ShouldHaveValidationError_WhenFirstNameIsNotSpecified()
    {
        // Arrange
        var person = new Person(null!);

        // Act
        var result = _validator.TestValidate(person);

        // Assert
        result.ShouldHaveValidationErrorFor(p => p.FirstName);
    }

    [Fact]
    public void ShouldNotHaveValidationError_WhenFirstNameIsSpecified()
    {
        // Arrange
        var person = new Person("John");

        // Act
        var result = _validator.TestValidate(person);

        // Assert
        result.ShouldNotHaveValidationErrorFor(p => p.FirstName);
    }
}

There is also an asynchronous TestValidateAsync method available which corresponds to the regular ValidateAsync method. Usage is similar, except the method returns an awaitable Task instead.

ASP.NET integration

FluentValidation can be applied in ASP.NET web applications to check if the data coming in through models is valid. You can do this in two primary ways:

Manual validation
Automatic validation

In manual validation, you add the validator to your controller (or API endpoint), then run the validator and do something based on the outcome. This method is pretty direct and trustworthy.

In automatic validation, FluentValidation connects itself to a built-in system in ASP.NET MVC that checks data. With this, the data in the models is checked even before the controller takes any action (during the time the model is being bound to data).

Dependency injection

Like any other dependency, we can register our PersonValidator validator with the service provider within the Program.cs file by calling AddScoped:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<IValidator<Person>, PersonValidator>();

Alternatively, when you need to register multiple validators, you can use the extension method AddValidatorsFromAssemblyContaining:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddValidatorsFromAssemblyContaining<PersonValidator>();

Manual validation

Using the manual validation method, you would add the validator into your controller by injecting it, and then use it to check the model.

public record Person(long Id, string FirstName);

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(person => person.FirstName).NotEmpty();
    }
}

[ApiController]
[Route("[controller]")]
public class PersonController : ControllerBase
{
    private IValidator<Person> _validator;

    public PersonController(IValidator<Person> validator)
    {
        _validator = validator;
    }

    [HttpGet("{id}")]
    public IActionResult GetPerson(int id)
    {
        return Ok(new Person(1, "John"));
    }

    [HttpPost]
    public async Task<IActionResult> CreatePerson([FromBody] Person person)
    {
        var validationResult = await _validator.ValidateAsync(person);

        if (!validationResult.IsValid)
        {
            return BadRequest(validationResult.Errors);
        }

        var createdPersonId = 1;

        return CreatedAtAction(nameof(GetPerson), new { id = createdPersonId }, person);
    }
}

In this example, the PersonController class is a web API controller that is designed to handle HTTP requests related to persons.

The controller receives an instance of IValidator<Person> through its constructor. This instance, which is stored in the _validator field, will be used to validate the data of a Person object.

Within the CreatePerson method, the _validator instance is used to manually validate the Person object received in the request. If the object does not pass validation, the method returns a 400 Bad Request response, containing the validation errors.

If the validation passes, it is generally expected that the application would save the Person object to a database. However, for simplicity, this example does not include database storage. Instead, it simulates the creation of a new resource and returns a 201 Created HTTP response.

Automatic validation

To use automatic validaton, you need to call AddFluentValidationAutoValidation within the Program.cs file.

Here is an example on how you can configure it:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFluentValidationAutoValidation();
builder.Services.AddValidatorsFromAssemblyContaining<PersonValidator>();

When you use AddFluentValidationAutoValidation, FluentValidation automatically connects to the model binding process in ASP.NET. This means that before a controller action is executed, FluentValidation will automatically perform validation of the incoming model according to the defined rules.

If the validation fails, the framework will automatically return a response with validation errors, without you having to write additional code to handle this scenario.

It is important to note that the AutoValidation feature has some limitations compared to manual validation, such as not supporting asynchronous validation and working only with MVC controllers and Razor Pages. Therefore, you should use it with caution and consider whether it is the best approach for your specific use case.

Conclusion

FluentValidation is an invaluable tool for developers building .NET applications. Its fluent interface, extensibility, ease of testing, localization support, and integration capabilities make it an ideal choice for implementing validation logic in a clean and maintainable way. Whether you are building a small-scale application or an enterprise-level solution, FluentValidation can play a significant role in ensuring the integrity of your data.

References

FluentValidation documentation

Object Mapping in .NET

Fabrizio Bagalà — Thu, 22 Jun 2023 22:12:18 +0000

Object mapping is a critical technique in software development that involves converting data from one object type into another. Essentially, it's about matching the properties of two different types of objects, so that their data can be seamlessly passed from one to another. This is particularly useful when you need to transfer data between objects that are not compatible or were designed to work with different architectures or data models.

There are several scenarios where object mapping is incredibly beneficial:

Data Transfer Objects (DTOs): When data is retrieved from a database, it's often transformed into DTOs which are plain objects that hold data. These DTOs can then be mapped to objects that have more business logic.
Database Abstraction: ORM is often used as a way to map the data retrieved from a database into objects within an application. This abstraction allows developers to interact with databases using object-oriented code rather than writing SQL queries.
Model Transformations: When working with different layers in an application, such as UI, business logic, and data access layers, the shape of the data often needs to change to suit the specific layer. Object mapping helps in transforming the data models as they move between layers.
API Responses: When developing APIs, you often want to control the shape of the data being sent to the client. Object mapping allows you to map your internal data models to a simplified model suitable for an API response.

The complexity of object mapping can range from simple, where properties are copied as is, to complex where some kind of transformation logic is applied during the mapping. The latter might include changing the type of the data, restructuring the object, or aggregating multiple properties into one.

Why use object mapping?

Using object mapping is beneficial for several reasons. First, it reduces the boilerplate code that is required when manually mapping fields from one object to another, which contributes to cleaner code. Secondly, object mapping enhances maintainability by centralizing the data model, so updates can be made in one place without having to modify the mapping logic throughout the entire application. Lastly, performance is an important aspect and many object mapping libraries are optimized to provide high-performance mapping solutions.

Popular libraries

When it comes to object mapping, several libraries have gained popularity among developers for their efficiency, ease of use and flexibility. Among them:

1️⃣ AutoMapper: It is perhaps the most well-known library for object mapping in .NET. It allows you to configure maps between objects in a very simple manner and is extremely flexible.

var configuration = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Person, PersonDto>();
});

var person = new Person
{
    Id = 1,
    FirstName = "John",
    LastName = "Doe",
    Birthday = DateTime.UtcNow
};
var mapper = configuration.CreateMapper();
var personDto = mapper.Map<PersonDto>(person);

Here, we first create a MapperConfiguration object, which is used to configure the mappings. Within the configuration, we call CreateMap method to define a mapping between Person and PersonDto. After setting up the configuration, we create an instance of the mapper through CreateMapper method. Finally, we call the Map method on the mapper object to transform the source object into the destination type.

2️⃣ Mapster: It is known for its performance and ease of use. It offers a lightweight alternative to AutoMapper, and is just as powerful.

var person = new Person
{
    Id = 1,
    FirstName = "John",
    LastName = "Doe",
    Birthday = DateTime.UtcNow
};
var personDto = person.Adapt<PersonDto>();

Mapster allows for a more streamlined syntax. You can simply call the Adapt method directly on the source object, and specify the type of the destination object as a generic parameter. Mapster automatically handles the mapping configuration and execution for you, making it very concise and easy to use.

3️⃣ ExpressMapper: Focused on speed, ExpressMapper is a lightweight object mapping library that relies on expression compilation to achieve high-performance mappings.

ExpressMapper.Mapper.Register<Person, PersonDto>();
var person = new Person
{
    Id = 1,
    FirstName = "John",
    LastName = "Doe",
    Birthday = DateTime.UtcNow
};
var personDto = ExpressMapper.Mapper.Map<Person, PersonDto>(person);

In ExpressMapper, the mapping configuration is done through a static Mapper class. You call the Register method to define mappings between source and destination types. After that, you use the Map method on the same Mapper class to transform the source object into the destination type.

⚠️ Warning
ExpressMapper 1.9.1 does not support mapping between record.

Implicit operator

In addition to the libraries mentioned above, it is possible to map objects using implicit conversion operators. An implicit conversion operator allows for the conversion of an object of one custom type to another custom type without explicit casting. This provides a clean way to perform simple object mappings, particularly when the transformation logic is straightforward.

Here is an example illustrating how to define implicit conversion operators for object mapping:

public class Person
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime Birthday { get; set; }
}

public class PersonDto
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime Birthday { get; set; }

    public static implicit operator PersonDto(Person person)
    {
        return new PersonDto
        {
            Id = person.Id,
            FirstName = person.FirstName,
            LastName = person.LastName,
            Birthday = person.Birthday
        };
    }
}

In this example, we have two classes, Person and PersonDto. The PersonDto class has a static implicit operator defined which takes an instance of the Person class as a parameter. Inside the operator, a new instance of the PersonDto class is created and the properties are mapped from the Person object.

You can use this implicit operator like this:

var person = new Person
{
    Id = 1,
    FirstName = "John",
    LastName = "Doe",
    Birthday = DateTime.UtcNow
};
PersonDto personDto = person;

Notice that there is no explicit cast or function call necessary for the conversion. The implicit operator automatically handles the conversion and mapping of properties between the two objects. This can make your code cleaner and more readable, especially for simple mappings.

However, it is important to be cautious when using implicit operators, as they can sometimes lead to unexpected conversions which are not immediately obvious from the code. For complex mapping scenarios, using a dedicated mapping library may be more appropriate.

Benchmark

To quantify and compare the performance of the object mapping strategies discussed earlier, we can employ BenchmarkDotNet.

[Config(typeof(ObjectMappingBenchmarkConfig))]
public class ObjectMappingBenchmark
{
    private sealed class ObjectMappingBenchmarkConfig : ManualConfig
    {
        public ObjectMappingBenchmarkConfig()
        {
            SummaryStyle = BenchmarkDotNet.Reports.SummaryStyle.Default.WithRatioStyle(RatioStyle.Trend);
        }
    }

    private IMapper _mapper = null!;
    private Person _person = null!;

    [GlobalSetup]
    public void Setup()
    {
        var configuration = new MapperConfiguration(cfg =>
        {
            cfg.CreateMap<Person, PersonDto>();
        });
        _mapper = configuration.CreateMapper();

        ExpressMapper.Mapper.Register<Person, PersonDto>();

        _person = new Person
        {
            Id = 1,
            FirstName = "John",
            LastName = "Doe",
            Birthday = DateTime.UtcNow
        };
    }

    [Benchmark(Baseline = true)]
    public void AutoMapper()
    {
        _ = _mapper.Map<PersonDto>(_person);
    }

    [Benchmark]
    public void Mapster()
    {
        _ = _person.Adapt<PersonDto>();
    }

    [Benchmark(Description = "ExpressMapper")]
    public void Expressmapper()
    {
        _ = ExpressMapper.Mapper.Map<Person, PersonDto>(_person);
    }

    [Benchmark]
    public void ImplicitOperator()
    {
        PersonDto personDto = _person;
    }
}

From the comparison, the following results were obtained:

|           Method |      Mean |     Error |    StdDev |        Ratio | RatioSD |
|----------------- |----------:|----------:|----------:|-------------:|--------:|
|       AutoMapper | 51.673 ns | 0.0744 ns | 0.0659 ns |     baseline |         |
|          Mapster | 26.851 ns | 0.0688 ns | 0.0644 ns | 1.92x faster |   0.00x |
|    ExpressMapper | 70.970 ns | 0.3536 ns | 0.3307 ns | 1.37x slower |   0.01x |
| ImplicitOperator |  6.926 ns | 0.0493 ns | 0.0461 ns | 7.46x faster |   0.06x |

The table reflects a comparison of how swiftly different object mapping techniques can execute the mapping process. With the ImplicitOperator method clearly coming out on top, it’s evident that this method has been optimized for performance, likely employing minimal overhead. This is essential in high-throughput scenarios where object mapping needs to be rapid and efficient, such as real-time data processing or applications with high transaction rates.

Mapster, which follows ImplicitOperator in performance, demonstrates that it's a solid choice for those who are looking for a balance between ease of use and performance. Though not as fast as using the ImplicitOperator, Mapster offers additional features and flexibility which may be more suited to varied and complex mapping scenarios.

AutoMapper, being in the mid-range, is known for its rich set of features and versatility, but this comes at the cost of performance. It is a well-established library and might be preferred in applications where the mapping requirements are complex and the slight lag in performance is not a critical issue.

ExpressMapper lags behind the rest in terms of performance. This indicates that, while it might have its own set of features that make it useful in certain contexts, it is not the best choice when performance is paramount. ExpressMapper might be more applicable in scenarios where the ease of configuration and specific feature set align with the project requirements.

⚠️ Warning
Keep in mind that you may get different values than those given in the table. This depends on various factors, such as the complexity of the object to be mapped, the hardware of the machine on which the code is run, etc.

Conclusion

Object Mapping is a gear that facilitates the movement of data through the various layers and components of an application. With a variety of tools and techniques at their disposal, such as AutoMapper, Mapster, ExpressMapper, and implicit operators, .NET developers have several options for implementing efficient and maintainable mappings. The choice of the appropriate method will depend on the specific requirements of the project and the complexity of the mappings.

References

Const and Readonly in C#

Fabrizio Bagalà — Tue, 20 Jun 2023 08:52:49 +0000

Immutability is a core concept in software development, offering numerous benefits including code predictability, easier reasoning, and reduced bugs. Languages like C# support immutability through several mechanisms, two of which are the const and readonly keywords.

Const

The const keyword is used to declare a constant, that is, a variable whose value cannot be changed after initialization. When declaring a constant, you must assign it a value.

public const int MyConstant = 10;

In this example, MyConstant is a constant that has been initialized with the value 10. From this point onwards, the value of MyConstant cannot be changed at any other point in the code.

Readonly

The readonly keyword can be used in four contexts:

1️⃣ In a field declaration, readonly indicates that assignment to the field can only occur as part of the declaration or in a constructor in the same class.

public class MyClass
{
    private readonly int _myReadonlyVariable;

    public MyClass() 
    {
        _myReadonlyVariable = 10;
    }
}

⚠️ Warning
An externally visible type that contains an externally visible read-only field that is a mutable reference type may be a security vulnerability and may trigger warning CA2104 : "Do not declare read only mutable reference types."

2️⃣ In a readonly struct type definition, readonly indicates that the structure type is immutable.

public readonly struct Coords
{
    public Coords(double x, double y)
    {
        X = x;
        Y = y;
    }

    public double X { get; init; }
    public double Y { get; init; }

    public override string ToString() => $"({X}, {Y})";
}

3️⃣ In an instance member declaration within a structure type, readonly indicates that an instance member does not modify the state of the structure.

Typically, you apply the readonly to the following kinds of instance members:

Methods:

public readonly double Sum()
{
    return X + Y;
}

You can also apply the readonly to methods that override methods declared in System.Object:

public readonly override string ToString() => $"({X}, {Y})";

Properties and indexers:

private int counter;
public int Counter
{
    readonly get => counter;
    set => counter = value;
}

In C# 9.0 and later, you may apply the readonly to a property or indexer with an init accessor:

public readonly double X { get; init; }

4️⃣ In a ref readonly method return, the readonly indicates that method returns a reference and writes are not allowed to that reference.

private static readonly SamplePoint s_origin = new SamplePoint(0, 0, 0);
public static ref readonly SamplePoint Origin => ref s_origin;

Differences between `const` and `readonly`

Although const and readonly seem similar, there are some key differences between the two:

Initialization: A constant must be initialized at the time of declaration, whereas a readonly variable can be initialized at the time of declaration or in a constructor.
Type of value: A constant can hold only primitive or a null reference, whereas a readonly variable can hold any type of value.
Scope: Constants may have a global scope and can be used anywhere in the code, whereas readonly variables are confined within the class they are declared in.
Runtime vs compile time: Constants are evaluated at compile time, whereas readonly variables can be evaluated at runtime.

Conclusion

Understanding the functionalities and applications of const and readonly keywords is fundamental in C# programming. Both provide you with the ability to protect your variables from unintended changes, promoting code safety and predictability.

While constants are suitable for values that will never change, readonly variables provide a little more flexibility, as they can be assigned within constructors. This distinction makes readonly variables a perfect choice for values that are known at the time of object construction but are not known at compile time.

Remember, the right use of these keywords not only increases code readability and maintainability but also prevents potential bugs caused by inadvertent changes to these values. Always consider your specific use case, the nature of the values your variables will hold, and where and how they will be used within your code when choosing between const and readonly.

References

Covariance and Contravariance in C#

Fabrizio Bagalà — Tue, 20 Jun 2023 07:15:35 +0000

The world of object-oriented programming is filled with intricate concepts, among which covariance and contravariance hold significant roles. These principles define the permissible type relationships in programming languages, especially when dealing with generic types.

Covariance

Covariance allows the use of a derived type in place of a base type. It is supported for reference type parameters in method returns, arrays, delegates, and generic interfaces.

Consider the following example with a base class Animal and a derived class Dog. If we have a method that returns an Animal, we can have it return a Dog without problems, since Dog is a derivative of Animal.

public class Animal { }
public class Dog : Animal { }
public class Cat : Animal { }

public Animal GetAnimal()
{
    return new Dog(); // This operation is allowed
}

However, you can not do the opposite, i.e., have it return an Animal when you expect a Dog:

public Dog GetDog()
{
    return new Animal(); // This operation is NOT allowed
}

Regarding generic types, covariance is only allowed for read operations on reference types:

IEnumerable<Dog> dogs = new List<Dog>();
IEnumerable<Animal> animals = dogs; // This operation is allowed

However, it is not possible to use an IEnumerable<Animal> where an IEnumerable<Dog> is expected:

IEnumerable<Animal> animals = new List<Animal>();
IEnumerable<Dog> dogs = animals; // This operation is NOT allowed

Contravariance

Contravariance is the concept opposite to covariance. It allows the use of a base type in place of a derived type. Contravariance is supported for reference type parameters in method parameter positions, delegates, and generic interfaces.

Consider the following example with a delegate:

delegate void Action<in T>(T arg);

static void Main()
{
    Action<Animal> animalAction = (Animal a) => Console.WriteLine(a);
    Action<Dog> dogAction = animalAction; // This operation is allowed
    dogAction(new Dog()); // Prints "Dog"
}

In this example, the delegate accepts an Animal type. Since Dog is a derivative of Animal, we can assign animalAction to dogAction. However, we can't do the opposite:

Action<Dog> dogAction = (Dog d) => Console.WriteLine(d);
Action<Animal> animalAction = dogAction; // This operation is NOT allowed

In summary, contravariance allows only write operations on reference types.

Invariance

If a type is neither covariant nor contravariant, it is said to be invariant. An invariant generic type maintains the exact identity of the type parameter. This means you cannot use a different type than the one specified as the parameter of the generic type.

For instance, in the generic class List<T>, T is invariant. This means you can not use a List<Animal> where you expect a List<Dog>, or vice versa, even though Dog is a derived type of Animal.

List<Animal> animals = new List<Dog>(); // This operation is NOT allowed

Similarly, if you have a method that accepts a List<Animal>, you can not pass a List<Dog>:

void ProcessAnimals(List<Animal> animals) { /*...*/ }

List<Dog> dogs = new List<Dog>();
ProcessAnimals(dogs); // This operation is NOT allowed

Although invariance might seem limiting, it is essential for type safety. Without invariance, you could introduce type errors into your code, as in the following example:

List<Animal> animals = new List<Dog>(); // Suppose this operation was allowed
animals.Add(new Cat()); // This would be an error because we're trying to add a Cat to a list of Dogs

Invariance ensures that these situations do not occur, preserving the integrity and safety of your code.

Conclusion

Covariance and contravariance might sound complicated, but they are really helpful in making your code flexible. C# strongly supports these ideas, and you can use them in many situations. But you need to be careful, as using them without fully understanding them can cause confusing errors. So, it is important to really understand what covariance and contravariance mean before you start using them to boost your code's potential.

References

Covariance and Contravariance (C#)

Ref, Out, In parameters in C#

Fabrizio Bagalà — Thu, 15 Jun 2023 09:08:02 +0000

ℹ️ Information
The code in the following article was tested with C# 8 or above.

In C#, we have various techniques available for controlling the passing of arguments to methods. Among these, the keywords ref, out, and in play a particularly important role. These parameter modifiers allow you to specify the way data is transferred between methods, although they have some limitations.

Ref

The ref keyword is used to pass an argument to a method by reference, rather than by value. This means that if a method changes the value of a ref parameter, this change will also be visible to the variable passed by the caller.

🔎 Insight
In pass by value, a copy of the actual parameter value is created and passed to the function. Any modifications made to the parameter inside the function do not affect the original value outside the function.
In pass by reference, the reference or memory address of the parameter is passed. Any modifications made to the parameter inside the function are reflected in the original value outside the function.

public void SampleMethod(ref int x) 
{
    x = 10;
}

int num = 1;
SampleMethod(ref num);
Console.WriteLine(num); // Prints 10

It's important to highlight that to use a ref parameter, both the method definition and the calling method must explicitly use the ref keyword. Also, the variable passed as a ref parameter must be initialized before being passed to the method.

⚠️ Warning
Do not confuse the concept of passing by reference with the concept of reference types. The two concepts are not the same. A method parameter can be modified by ref regardless of whether it is a value type or a reference type. There is no boxing of a value type when it is passed by reference.

Out

The out keyword is used to pass arguments by reference. Unlike ref, however, out does not require that the input variable be initialized before being passed. Also, the method must necessarily assign a value to the out parameter before it concludes its execution.

public void SampleMethod(out int x) 
{
    x = 10;
}

int num;
SampleMethod(out num);
Console.WriteLine(num); // Prints 10

⚠️ Warning
The out keyword can also be used with a generic type parameter to specify that the type parameter is covariant.

In

The in keyword, introduced in C# 7.2, is used to pass an argument to a method by reference but prevents the value from being modified within the method. This is particularly useful when working with large structures, because it avoids the overhead of copying, while at the same time ensuring the integrity of the data.

public void SampleMethod(in int x) 
{
    // x = 10; // This will generate an error
    Console.WriteLine(x);
}

int num = 1;
SampleMethod(in num); // Prints 1

⚠️ Warning
The in keyword can also be used with a generic type parameter to specify that the type parameter is contravariant, as part of a foreach statement, or as part of a join clause in a LINQ query.

Limitations

Despite their usefulness, the keywords ref, out, and in have some limitations:

They cannot be used in async methods defined with the async modifier.
They cannot be used in iterator methods that include a yield return or yield break statement.
The first argument of an extension method cannot have the in modifier unless that argument is a struct.
They cannot be used in the first argument of an extension method in which that argument is a generic type, even when that type is constrained to be a struct.

The restrictions also extend to extension methods:

The out keyword cannot be used in the first argument of an extension method.
The ref keyword cannot be used in the first argument of an extension method, unless the argument is a struct or an unconstrained generic type.
The in keyword cannot be used unless the first argument is a struct. Furthermore, it cannot be used in any generic type, even when it is constrained to be a struct.

Additionally, it's important to remember that members of a class cannot have signatures that differ only by ref, in, or out. In practice, a compiler error will occur if the only difference between two members of a type is that one of them has a ref parameter and the other has an out or in parameter.

⛔️ Compiler Error CS0663
Cannot define overloaded methods that differ only on ref and out.

public class TestClass
{
   public void SampleMethod(out int i) { }
   public void SampleMethod(ref int i) { }
}

Overloading is legal, however, if one method takes a ref, in, or out argument and the other has none of those modifiers, like this:

public class TestClass1
{
    public void SampleMethod(int i) { }
    public void SampleMethod(ref int i) { }
}

public class TestClass2
{
    public void SampleMethod(int i) { }
    public void SampleMethod(out int i) => i = 5;
}

public class TestClass3
{
    public void SampleMethod(int i) { }
    public void SampleMethod(in int i) { }
}

Conclusion

The ref, out, and in keywords provide detailed control over how arguments are passed to methods. Understanding and using them correctly can enhance code efficiency and safety. However, it's crucial to be aware of their limitations and use them cautiously, as improper use can render the code complex and hard to manage.

References

Heap Sort

Fabrizio Bagalà — Tue, 13 Jun 2023 16:03:43 +0000

Heap Sort is a comparison-based sorting algorithm that leverages the properties of a binary heap. A binary heap is a complete binary tree that satisfies the heap property - in a max heap, for any given node i, the value of i is greater than or equal to the values of its children. Conversely, in a min heap, the value of i is less than or equal to the values of its children. The Heap Sort algorithm uses this structure to sort an array in ascending or descending order.

How it works

Heap Sort primarily involves two steps - building the heap and then performing the sort operation.

Building the heap: The initial unsorted array is transformed into a heap data structure. For sorting in ascending order, a max heap is built, whereas for sorting in descending order, a min heap is constructed. The heap construction is performed in-place, i.e., the data structure is built within the array itself.
Performing the sort: Once the heap is constructed, the root of the heap (which is the maximum or minimum element, depending on the type of heap) is swapped with the last element of the heap. The size of the heap is then reduced by one. The swapping operation may disrupt the heap property, so the heapify operation is performed to restore it. This process is repeated until the heap size reduces to 1, resulting in a sorted array.

The crux of Heap Sort lies in the heapify operation which maintains the heap structure after each swap.

Here is a simple implementation in C#:

public void HeapSort(int[] arr)
{
    var n = arr.Length;

    for (var i = n / 2 - 1; i >= 0; i--)
    {
        Heapify(arr, n, i);
    }

    for (var i = n - 1; i >= 0; i--)
    {
        Swap(ref arr[0], ref arr[i]);
        Heapify(arr, i, 0);
    }
}

private void Heapify(int[] arr, int n, int i)
{
    var largest = i;
    var left = 2 * i + 1;
    var right = 2 * i + 2;

    if (left < n && arr[left] > arr[largest])
    {
        largest = left;
    }

    if (right < n && arr[right] > arr[largest])
    {
        largest = right;
    }

    if (largest != i)
    {
        Swap(ref arr[i], ref arr[largest]);
        Heapify(arr, n, largest);
    }
}

private void Swap(ref int a, ref int b)
{
    (a, b) = (b, a);
}

In the provided code, the first phase of the sort function builds a max heap from the given array. This is done by calling the Heapify method for each of the non-leaf nodes, starting from the lowest and rightmost node that has children (the mid-element of the array).

In the second phase, the root node (the maximum element in a max heap) is repeatedly removed, swapped with the last element of the reduced heap (the element at the end of the array), and then the heap property is restored by calling Heapify again.

Time complexity

From a time perspective, Heap Sort has a complexity of O(n log n), both in the average and worst-case scenarios. This time efficiency is due to the fact that you have to perform n heapify operations, each of which has a complexity of O(log n).

Space complexity

In terms of space, Heap Sort is very efficient, with a complexity of O(1). This is because all the sorting happens in place, i.e., within the original array, without the need for additional space.

Conclusion

Heap Sort is a very powerful sorting algorithm that takes advantage of the unique properties of a binary heap data structure. Its efficiency in terms of time complexity makes it a preferred choice for sorting large datasets. In contrast, its in-place sorting feature makes it an excellent choice in environments where memory usage is an issue.

References

Algoritmi e programmazione in C di Francesco Oliveri, Aracne editrice (Italian book)

Garbage Collector in .NET

Fabrizio Bagalà — Fri, 09 Jun 2023 18:10:32 +0000

The .NET Garbage Collector (GC) is one of the most essential components of the framework. It automatically manages memory, ensuring that resources are correctly disposed of when no longer needed, thereby mitigating the risk of memory errors. Although it operates in the background, understanding how it works is useful for developers in optimizing application performance and resolving memory-related issues.

How it works

At its core, the GC operates on the principle of automatic memory management, which means it is responsible for both the allocation and deallocation of memory for .NET applications. It takes care of disposing of objects that are no longer used by the application, thereby freeing up valuable memory space.

It uses a reference tracking algorithm to determine which objects can be disposed of. Any object not referenced by another running object is deemed "unreachable" and is subsequently marked for collection.

The GC process is divided into three phases:

Marking: In this phase, it identifies all objects in memory that are still reachable, i.e., in use.
Removal: It removes the unreachable objects identified in the marking phase.
Compaction: This phase reduces memory fragmentation as the GC moves the remaining objects to occupy contiguous space.

Generations

The GC employs a generational model to improve performance. The model is based on the following considerations:

Memory compaction for a part of the managed heap is faster than for the entire managed heap.
Most recent objects typically have a shorter lifespan, while older ones have a longer lifespan.
More recent objects tend to be related and are accessed by the application at the same time.

Based on these factors, the GC categorizes objects in memory into three generations: 0, 1, and 2.

Generation 0 is the youngest, it contains short-lived objects like temporary variables. Garbage collection occurs most frequently in this generation. When Generation 0 gets filled, the GC performs a collection to free up space, usually reclaiming enough memory to allow the application to continue creating new objects.

Generation 1 serves as a buffer between short-lived and long-lived objects. After a Generation 0 collection, the GC compacts the memory for reachable objects and promotes them to Generation 1. This generation essentially serves as a 'second chance' for objects before they are promoted to Generation 2.

Generation 2 contains long-lived objects, like static data in a server application that remain active for the duration of the process. Generation 2 collections, also known as full garbage collections, include objects from all generations and therefore involve the entire managed heap.

Large objects go into the Large Object Heap (LOH), sometimes referred to as Generation 3. It's a physical generation that is logically collected as part of Generation 2.

Benefits

The GC offers numerous advantages:

Developer relief: It frees developers from the duty of manually releasing memory, a task often complicated and error-prone.
Efficient allocation: It allocates objects in the managed heap efficiently, reducing memory fragmentation and making more efficient use of system resources.
Unused object recovery: It recovers unused objects, wipes their memory, and keeps the memory available for future allocations. Managed objects automatically get clean content at the beginning, so constructors don't have to initialize every data field.
Memory safety: It ensures memory safety by making sure that an object cannot use for itself the memory allocated for another object. This eliminates a host of potential bugs and security issues.

Execution conditions

A Garbage Collection operation is carried out when one or more of the following conditions occur:

System physical memory shortage: The operating system or the host signals a reduced memory condition.
Excessive memory usage by objects allocated in the managed heap: When the memory used surpasses a certain threshold, which is continuously adjusted during the process execution, a Garbage Collection operation is initiated.
Call to the GC.Collect method: Although it is not necessary in almost all cases (since the GC operates continuously), this method can be called primarily in exceptional situations or for testing purposes.

Conclusion

Understanding the workings of the Garbage Collector, the importance of its generational approach, the benefits it offers, and the conditions that trigger a Garbage Collection operation allows developers to write more efficient code and competently address performance issues related to memory.

References

Fundamentals of garbage collection

Span, Memory, ReadOnlySequence in .NET

Fabrizio Bagalà — Fri, 09 Jun 2023 17:05:43 +0000

🔄 Updates
June 10, 2023 - Fixed benchmark.

In the landscape of the .NET, a key aspect is effective data manipulation. This capability is even more crucial when it comes to memory management. The Span<T>, Memory<T>, and ReadOnlySequence<T> structures provide advanced tools for optimal data management. These structures not only provide a high degree of control and flexibility, but also greatly increase the efficiency of operations.

Span

Provides a type-safe and memory-safe representation of a contiguous region of arbitrary memory.

Span<T> is a ref struct, and as such, it is allocated on the stack, not on the managed heap. This specific attribute imposes certain restrictions to ensure they do not get promoted to the managed heap. The constraints include preventing them from being boxed, assigned to variables of type Object or dynamic or any interface type, being fields in a reference type, and their use across await and yield boundaries. Invoking methods like Equals(Object) and GetHashCode on Span<T> will throw a NotSupportedException.

Given its stack-only nature, Span<T> might not be appropriate for scenarios that necessitate storing references to buffers on the heap. This restriction often applies in routines making asynchronous method calls. In these cases, complementary types like System.Memory<T> and System.ReadOnlyMemory<T> should be considered.

When dealing with immutable or read-only structures, it's more appropriate to use System.ReadOnlySpan<T>.

var array = new byte[100];
var span1 = new Span<byte>(array);
var span2 = array.AsSpan();

In this example, a byte array of 100 elements is first created. Then, two instances of Span<byte> are then constructed from this array using two distinct methods. The first instance is created directly via the Span<T> constructor, and the second one uses the AsSpan() extension method available on arrays. The use of the AsSpan() method can often lead to more readable and concise code, especially when performing additional operations on the span inline.

Memory

Represents a contiguous region of memory.

Similar to Span<T>, Memory<T> denotes a contiguous memory region. However, a key difference lies in their structure: Memory<T> is not a ref struct, unlike Span<T>. This structural distinction means that Memory<T> can reside on the managed heap, a feature not shared with Span<T>. As a result, Memory<T> is not bound by the same constraints as a Span<T> instance. Specifically:

It can be utilized as a field in a class.
It can operate across await and yield boundaries.

Alongside Memory<T>, System.ReadOnlyMemory<T> can be used to signify immutable or read-only memory, making it a versatile tool for handling different data storage needs.

var array = new byte[100];
var memory1 = new Memory<byte>(array);
var memory2 = array.AsMemory();

In this instance, mirroring the previous example, we first create a byte array of 100 elements and then two instances of Memory<T> from this array. The first instance is created via the constructor, the second via the readable and concise AsMemory() extension method.

ReadOnlySequence

Represents a sequence that can read a sequential series of T.

ReadOnlySequence<T> is a structure specifically engineered to manage non-contiguous data sequences, offering substantial utility when dealing with data scattered across multiple arrays or buffers. Essentially, it's a sequence representing a linked list of one or more Memory objects. If you find yourself needing to treat multiple memory fragments as a single entity, this data structure is your best option.

var array = new byte[100];
var sequence = new ReadOnlySequence<byte>(array);

In this code snippet, a byte array is created, and a ReadOnlySequence<byte> is then constructed from this array. The resulting ReadOnlySequence<byte> provides a unified view over the byte array as if it were a single, contiguous slice.

Benchmark

To objectively assess the performance of these structures, we can use a benchmarking framework like BenchmarkDotNet. In this way, we can compare the performance of Span<T>, Memory<T>, and ReadOnlySequence<T> to arrays and lists.

[Config(typeof(MemoryBenchmarkConfig))]
public class MemoryBenchmark
{
    private sealed class MemoryBenchmarkConfig : ManualConfig
    {
        public MemoryBenchmarkConfig()
        {
            SummaryStyle = BenchmarkDotNet.Reports.SummaryStyle.Default.WithRatioStyle(RatioStyle.Trend);
        }
    }

    private const int OperationsPerInvoke = 4096;

    private string _text = null!;

    [GlobalSetup]
    public void Setup()
    {
        _text = "Hello World";
    }

    [Benchmark(Baseline = true)]
    public void ArrayRange()
    {
        _ = _text[4..];
    }

    [Benchmark]
    public void ListRange()
    {
        _ = _text.ToList().GetRange(4, 7);
    }

    [Benchmark(OperationsPerInvoke = OperationsPerInvoke)]
    public void SpanSlice()
    {
        for (var i = 0; i < OperationsPerInvoke; i++)
        {
            _ = _text.AsSpan().Slice(4);
        }
    }

    [Benchmark]
    public void MemorySlice()
    {
        _ = _text.AsMemory().Slice(4);
    }

    [Benchmark]
    public void ReadOnlySequenceSlice()
    {
        _ = new ReadOnlySequence<char>(_text.AsMemory()).Slice(4);
    }
}

The following results emerged from the comparison:

|                Method |        Mean |     Error |    StdDev |         Ratio | RatioSD |
|---------------------- |------------:|----------:|----------:|--------------:|--------:|
|            ArrayRange |   6.1415 ns | 0.0235 ns | 0.0220 ns |      baseline |         |
|             ListRange | 102.9986 ns | 0.3432 ns | 0.3210 ns | 16.77x slower |   0.09x |
|             SpanSlice |   0.5854 ns | 0.0009 ns | 0.0008 ns | 10.49x faster |   0.04x |
|           MemorySlice |   0.8952 ns | 0.0029 ns | 0.0027 ns |  6.86x faster |   0.03x |
| ReadOnlySequenceSlice |   9.1725 ns | 0.0198 ns | 0.0185 ns |  1.49x slower |   0.01x |

In the table, ArrayRange serves as a reference point, given its essential and direct nature.

ListRange performs much less well than baseline. This is probably due to the inherent complexity of lists, which, while offering great flexibility, require a higher overhead than arrays.

In contrast, SpanSlice and MemorySlice far outperform ArrayRange in terms of speed. This suggests that their ability to operate on portions of data rather than entire collections allows for more efficient and faster data manipulation.

Finally, ReadOnlySequenceSlice ranks slightly below ArrayRange in terms of performance. This may be because ReadOnlySequenceSlice offers advantages in terms of data security, as it prevents unwanted modifications. However, these advantages come at a small cost in terms of performance.

⚠️ Warning
Keep in mind that you may get different values than those given in the table. This depends on various factors, such as the length and complexity of the input strings, the hardware of the machine on which the code is running, etc.

Conclusion

The advanced memory structures provided by .NET, like Span<T>, Memory<T>, and ReadOnlySequence<T>, can deliver significant efficiency and performance benefits when dealing with contiguous or disconnected data. Familiarity with these structures and the ability to effectively utilize them can be a core skill for .NET developers aiming to optimize their applications.

References

Quick Sort

Fabrizio Bagalà — Thu, 08 Jun 2023 19:25:16 +0000

QuickSort, also known as partition-exchange sort, is a highly efficient, comparison-based sorting algorithm. Originally developed by Tony Hoare in 1960 during his work on machine language translation, it operates on a divide et impera strategy.

It selects a pivot element from the array and partitions the remaining elements into two groups: those less than the pivot and those greater than the pivot. This process is recursively applied to the two partitions, breaking down a large sorting problem into smaller, more manageable ones until the entire array is sorted.

Over the years, QuickSort has firmly established its status as a commonly used sorting algorithm in the software industry.

How it works

It operates on the following key points:

Pivot selection: Initially, the algorithm chooses a pivot element from the array. The pivot can be chosen randomly or through a specific strategy, often it's the first, middle, or last element.
Partitioning: Post pivot selection, the array is rearranged such that all elements smaller than the pivot are moved before it and all elements larger are moved after it. This process is referred to as partitioning. Upon the completion of this step, the pivot element is in its final position in the sorted array.
Recursion: The algorithm then recursively applies the same operations to the two partitions, i.e., the elements less than the pivot and those greater than the pivot. This process continues, recursively dividing the array until only one element remains in each partition. At this stage, since each single-element array is inherently sorted, the entire array becomes sorted.

Here is a simple implementation in C#:

public void QuickSort(int[] arr, int left, int right)
{
    if (left < right)
    {
        var pivot = Partition(arr, left, right);

        QuickSort(arr, left, pivot - 1);  
        QuickSort(arr, pivot + 1, right); 
    }
}

public int Partition(int[] arr, int left, int right)
{
    var pivot = arr[right];  
    var i = left - 1;

    for (var j = left; j <= right - 1; j++)
    {
        if (arr[j] < pivot)
        {
            i++;
            Swap(ref arr[i], ref arr[j]);
        }
    }

    Swap(ref arr[i + 1], ref arr[right]);
    return i + 1;
}

public void Swap(ref int a, ref int b)
{
    (a, b) = (b, a);
}

To use the above implementation, you simply need to call the QuickSort method with your array and the lowest and highest indexes as arguments. For instance, if an array of integers is known as arr, the sorting process would be initiated by executing the corresponding method call:

QuickSort(arr, 0, arr.Length - 1);

Time complexity

The time complexity in the best and average case is O(n log n) making it a compulsory choice for large data sets. In the worst-case scenario, that is, when the input array is already sorted, its time complexity becomes O(n²).

Space complexity

The space complexity is O(log n). This mirrors the space required to accommodate the stack of recursive calls. However, it is worth mentioning that this can vary depending on the intricacies of the implementation and the pivot selection strategy. Generally, it performs impressively in terms of space complexity, making it a good choice when memory is a consideration.

Conclusion

QuickSort is a highly effective and adaptable sorting algorithm that is extensively used when dealing with large datasets. Its performance may taper in certain edge cases, but overall, it delivers an excellent balance of time and space efficiency, making it a preferred choice across a range of data management scenarios.

References

Algoritmi e programmazione in C di Francesco Oliveri, Aracne editrice (Italian book)

JWT Authentication in ASP.NET

Fabrizio Bagalà — Sat, 03 Jun 2023 18:17:53 +0000

ℹ️ Information
The code in the following article was tested with ASP.NET 6 and 7.

When it comes to security in web applications, one of the main challenges is ensuring user authentication and authorization. Among the various technologies available to manage authentication are JWTs.

What is a JWT?

JWT stands for JSON Web Token and it's an open standard for creating access tokens that allow the secure sharing of information between different parties in a compact, self-contained format.

A JWT consists of three parts:

Header: It contains metadata that describes the token itself. It usually includes the type of token, which is JWT, and the signing algorithm used, like HMAC SHA256 or RSA.
Payload: It contains the so-called "claims", which are assertions about the subject (the user, in most cases) and additional information. There are three types of claims: registered, public, and private. Registered claims are a predefined set of claims with specific meanings, such as iss (token issuer), exp (token expiration date), sub (token subject), among others. Public and private claims are user-defined.
Signature: It is used to verify that the sender of the JWT is whom they claim to be and to ensure that the message has not been altered along the way.

Once created, the JWT is encoded and signed, making it a secure token to send between the client and server.

JWTs are commonly used to implement token-based authentication in RESTful APIs. When a user successfully authenticates, the server creates a JWT and sends it to the client. The client can then use the JWT to authenticate subsequent requests. Since the JWT contains information about the user's permissions, the server can use the JWT to authorize the operations requested by the client.

Pros and cons of using JWT

One of the main advantages of using JWTs is their stateless nature. They contain all the necessary information for authentication, eliminating the need to maintain a server-side session. This saves resources and promotes application scalability. Additionally, JWTs are very compact, making them suitable for sending via URL, POST parameters, or in the HTTP header. This compactness is particularly useful when data needs to be sent across the network. From a security perspective, JWTs can be digitally signed, allowing for the verification of data integrity. If necessary, a JWT can be encrypted to ensure data confidentiality. Finally, a JWT is self-contained as it holds all the necessary information about who the user is and what permissions they have, significantly simplifying authorization decisions.

However, there are also drawbacks to using JWTs. Although JWTs are compact, they tend to be larger than alternatives such as session cookies. If the JWT's payload is too large, it could affect the performance of the application. Implementing JWTs can also be more complex than other solutions, such as session-based authentication. Furthermore, the security of JWTs is tied to the robustness of the encryption algorithm and key used. Since JWTs are stateless, invalidating or updating a JWT without contacting the server can be challenging, which can pose problems in scenarios like user logout or password change. Finally, from a security perspective, if a JWT is stolen, it can be used to impersonate the user and, due to the difficulty of invalidating a JWT, often the solution involves setting short expiration times and frequently renewing tokens.

Therefore, when deciding to use JWTs, it is important to carefully consider these advantages and disadvantages to determine if it suits the specific use case.

Example of use of JWT

Here is an example of a minimal API in ASP.NET that uses the JWT to authenticate a user.

var builder = WebApplication.CreateBuilder(args);

var jwtOptionsSection = builder.Configuration.GetRequiredSection("Jwt");
builder.Services.Configure<JwtOptions>(jwtOptionsSection);

builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(jwtOptions =>
{
    var configKey = jwtOptionsSection["Key"];
    var key = Encoding.UTF8.GetBytes(configKey);

    jwtOptions.TokenValidationParameters = new TokenValidationParameters
    {
        ValidIssuer = jwtOptionsSection["Issuer"],
        ValidAudience = jwtOptionsSection["Audience"],
        IssuerSigningKey = new SymmetricSecurityKey(key),
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = false,
        ValidateIssuerSigningKey = true
    };
});

builder.Services.AddAuthorization();

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

builder.Services.AddTransient<IUserService, UserService>();
builder.Services.AddTransient<IJwtService, JwtService>();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1.0))
    .ReportApiVersions()
    .Build();

app.MapPost("v{version:apiVersion}/token", [AllowAnonymous]([FromBody] UserInfo user,
    [FromServices] IUserService userService, [FromServices] IJwtService jwtService) =>
{
    var storedUser = userService.GetUser(user?.Username);
    if (!userService.IsAuthenticated(user?.Password, storedUser?.PasswordHash))
    {
        return Results.Unauthorized();
    }

    var tokenString = jwtService.GenerateToken(storedUser);
    return Results.Ok(new { token = tokenString });
}).WithApiVersionSet(versionSet);

app.MapGet("v{version:apiVersion}/weather", [Authorize]() =>
{
    var data = Enumerable.Range(1, 5)
        .Select(i => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(i),
            TemperatureC = Random.Shared.Next(-20, 55)
        })
        .ToArray();

    return Results.Ok(data);
}).WithApiVersionSet(versionSet);

app.Run();

Let's analyze this example step by step.

Step 1: Creating the application

var builder = WebApplication.CreateBuilder(args);

We start by creating an instance of the application builder. This builder will be used to configure services and middleware before the application starts.

Step 2: Configuring JWT options

We use the options pattern to read the Jwt section from the configuration file and map it onto an instance of the JwtOptions class.

var jwtOptionsSection = builder.Configuration.GetRequiredSection("Jwt");
builder.Services.Configure<JwtOptions>(jwtOptionsSection);

GetRequiredSection("Jwt") retrieves the Jwt section from the configuration file. Configure<JwtOptions>(jwtOptionsSection) maps the settings of the Jwt section onto the JwtOptions object, making it available for injection into other classes through the dependency injection system.

The used appsettings.json configuration file is:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Jwt": {
    "Issuer": "example.com",
    "Audience": "example.com",
    "Key": "This is a secure secret key"
  }
}

In this file, the Jwt section contains the settings related to the JWT, such as Issuer, Audience, and Key.

The JwtOptions class is a POCO (Plain Old CLR Object) class that corresponds to the settings of the Jwt section:

public class JwtOptions
{
    public string Issuer { get; init; } = string.Empty;
    public string Audience { get; init; } = string.Empty;
    public string Key { get; init; } = string.Empty;
}

Each property in this class is initialized with the corresponding value from the Jwt section of the configuration file. This class will then be injected into any class that requires these settings.

⚠️ Warning
In a production environment, do not store sensitive data in the code or appsettings.json. Rather use Vault Secrets.

Step 3: Adding authentication

builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(jwtOptions =>
{
    var configKey = jwtOptionsSection["Key"];
    var key = Encoding.UTF8.GetBytes(configKey);

    jwtOptions.TokenValidationParameters = new TokenValidationParameters
    {
        ValidIssuer = jwtOptionsSection["Issuer"],
        ValidAudience = jwtOptionsSection["Audience"],
        IssuerSigningKey = new SymmetricSecurityKey(key),
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = false,
        ValidateIssuerSigningKey = true
    };
});

The authentication service is added and configured to use JWT authentication as the default authentication scheme. The token validation options are set from jwtOptionsSection, which was configured in the previous step.

Note that the NuGet package Microsoft.AspNetCore.Authentication.JwtBearer needs to be installed.

Step 4: Adding authorization

builder.Services.AddAuthorization();

The authorization service is added, which allows access to controllers and actions to be restricted based on user roles or policies.

Step 5: Adding API versioning

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

To be able to use API versioning, you need to install the NuGet package Asp.Versioning.Http.

In the code, we are setting the default version of the API to version 1.0, assuming this default version when not specified, and reading the API version from the URL segment of the request. We are also choosing to report the API versions in the HTTP responses, which can be useful for your API customers to know about the different versions available.

🔎 Insight
Even though it's just an example, I decided to add versioning because I consider it an important aspect when writing an API. Let's look at some key reasons:

Seamless evolution: APIs change and evolve over time. You might need to add new features or change existing ones. Versioning allows you to make these changes without disrupting applications using previous versions of your API.

Controlled deprecation: You might want to deprecate some features or entire versions of your API in the future. Versioning allows you to do this in a controlled manner, providing users with a notice and a transition period before removing the deprecated features or versions.

Flexibility for users: Versioning gives your users the flexibility to choose which version of your API to use. For instance, they may choose to stick to a previous version if the changes introduced in a new version are not compatible with their applications.

Documentation and testing: Each version of your API can have its own documentation and test suite, which can help both you and your users to understand and verify the functionality of each version.

Step 6: Services registration

builder.Services.AddTransient<IJwtService, JwtService>();
builder.Services.AddTransient<IUserService, UserService>();

In this step, IJwtService and IUserService are registered as transient services, which means a new instance will be created each time a component requests one of these services. They are responsible for managing the JWT and managing users, respectively.

Let's start with IJwtService. This interface defines a GenerateToken method, which takes a UserDto object as an argument and returns a string. This string represents the JWT token generated for the user.

public record UserDto(Guid Id, string Username, string PasswordHash, string Email, string Role);

public interface IJwtService
{
    string GenerateToken(UserDto? user);
}

The JwtService class implements IJwtService. It has a variable _options of type JwtOptions. This variable is initialized via the class constructor, which receives an IOptions<JwtOptions> object. IOptions is a wrapper containing configuration options (in this case JwtOptions) from a configuration file (for instance, appsettings.json).

The GenerateToken method of JwtService creates a JWT token for the user passed as an argument. First of all, it ensures the user is not null, otherwise, it throws an ArgumentNullException. Then, it creates a symmetric security key using the key present in the JWT options. Subsequently, it creates a security token descriptor. This descriptor contains a number of important information, such as the user's claims, the token's expiration date, the issuer, the audience, and the signing credentials. Finally, it uses JwtSecurityTokenHandler to create and write the token.

public sealed class JwtService : IJwtService
{
    private readonly JwtOptions _options;

    public JwtService(IOptions<JwtOptions> options)
    {
        _options = options.Value ?? throw new ArgumentNullException(nameof(options));
    }

    public string GenerateToken(UserDto? user)
    {
        ArgumentNullException.ThrowIfNull(user);

        var key = Encoding.ASCII.GetBytes(_options.Key);
        var securityKey = new SymmetricSecurityKey(key);
        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(new[]
            {
                new Claim(ClaimTypes.Name, user.Username),
                new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
                new Claim(ClaimTypes.Email, user.Email),
                new Claim(ClaimTypes.Role, user.Role)
            }),
            Expires = DateTime.UtcNow.AddMinutes(5),
            Issuer = _options.Issuer,
            Audience = _options.Audience,
            SigningCredentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256Signature)
        };
        var tokenHandler = new JwtSecurityTokenHandler();
        var token = tokenHandler.CreateToken(tokenDescriptor);
        return tokenHandler.WriteToken(token);
    }
}

The created token can be decoded through JWT.IO.

The IUserService interface defines two methods: GetUser, which returns a UserDto object based on the provided username, and IsAuthenticated, which verifies if a password matches a provided password hash.

public interface IUserService
{
    UserDto? GetUser(string? username);
    bool IsAuthenticated(string? password, string? passwordHash);
}

The UserService class implements IUserService. It has a variable _users, which is a list of UserDto objects. In the constructor of this class, this list is initialized with two example users, whose data are hardcoded.

The GetUser method returns a UserDto object that has the provided username, or null if such a user does not exist. The IsAuthenticated method checks if the provided password, once hashed, matches the provided password hash. It uses the Verify method of the NuGet package BCrypt.Net-Next to perform this check.

public sealed class UserService : IUserService
{
    private readonly List<UserDto> _users;

    public UserService()
    {
        _users = new List<UserDto>
        {
            new(Guid.NewGuid(), "user1", BCrypt.Net.BCrypt.HashPassword("password1"), "user1@gmail.com", "Admin"),
            new(Guid.NewGuid(), "user2", BCrypt.Net.BCrypt.HashPassword("password2"), "user2@gmail.com", "User")
        };
    }

    public UserDto? GetUser(string? username)
    {
        ArgumentNullException.ThrowIfNull(username);

        return _users.SingleOrDefault(u => u.Username == username);
    }

    public bool IsAuthenticated(string? password, string? passwordHash)
    {
        ArgumentNullException.ThrowIfNull(password);
        ArgumentNullException.ThrowIfNull(passwordHash);

        return BCrypt.Net.BCrypt.Verify(password, passwordHash);
    }
}

Step 7: Building the application

var app = builder.Build();

This code builds the web application with all the configurations and services that have been registered.

Step 8: Middleware configuration

app.UseAuthentication();
app.UseAuthorization();

The authentication and authorization middleware are added to the application.

Step 9: Creating the API version set

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1.0))
    .ReportApiVersions()
    .Build();

An API version set is created to be used with the endpoints.

Creating a version set is useful for grouping and managing API versions in a consistent way. The NewApiVersionSet() method creates a new version set. A specific API version can be added to this version set using the HasApiVersion() method.

Additionally, the ReportApiVersions() method enables API version reporting. This setting allows including information about supported versions in HTTP responses. This can be very helpful for developers using your API, as it allows them to quickly see what API versions are available.

Finally, the Build() method builds the version set. This version set is then used in combination with API endpoints to manage different API versions.

Step 10: Defining the endpoints

Endpoints represent access points to our API. In our example, we are defining two main endpoints: one for token generation and one for accessing protected data.

Token Endpoint (POST /token): This endpoint is responsible for generating the JWT token. It receives a UserInfo object in the request body, which contains user credentials (username and password). These details are then passed to the user service for authentication. If the user is correctly authenticated, the JWT service generates a token that is returned to the client. This endpoint is decorated with the AllowAnonymous attribute, meaning that no token needs to be provided to access it.

public record UserInfo(string? Username, string? Password);

app.MapPost("v{version:apiVersion}/token", [AllowAnonymous]([FromBody] UserInfo user,
    [FromServices] IUserService userService, [FromServices] IJwtService jwtService) =>
{
    var storedUser = userService.GetUser(user?.Username);
    if (!userService.IsAuthenticated(user?.Password, storedUser?.PasswordHash))
    {
        return Results.Unauthorized();
    }

    var tokenString = jwtService.GenerateToken(storedUser);
    return Results.Ok(new { token = tokenString });
}).WithApiVersionSet(versionSet);

Protected Endpoint (GET /weather): This endpoint is intended to provide protected data, in this case, a series of weather forecasts. The Authorize attribute ensures that only authenticated users with a valid token can access this endpoint. If a client tries to access this endpoint without providing a valid token, they will receive an HTTP 401 Unauthorized error.

app.MapGet("v{version:apiVersion}/weather", [Authorize]() =>
{
    var data = Enumerable.Range(1, 5)
        .Select(i => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(i),
            TemperatureC = Random.Shared.Next(-20, 55)
        })
        .ToArray();

    return Results.Ok(data);
}).WithApiVersionSet(versionSet);

The endpoint routes use a version:apiVersion parameter that allows clients to specify the API version they want to use. This is part of our versioning strategy, as discussed in step 5.

Step 11: Running the application

app.Run();

The application is started and begins listening for incoming requests.

Conclusion

In this article, I addressed the nuances of implementing JSON Web Token (JWT) in ASP.NET for managing user authentication. I outlined the essentials of JWT and why it has become a popular choice in modern Web development. From configuring properties to generating and decoding tokens, I explored each step in the process. I also examined the advantages and potential disadvantages of its use.

In summary, the goal of this guide was to provide a foundation for integrating JWT authentication into ASP.NET applications. Although I have tried to cover the main aspects, I always remember that understanding the basic principles and adhering to security best practices are critical when using new technology.

DEV Community: Fabrizio Bagalà

Response Compression in ASP.NET

Configuration

Compression with HTTPS

Providers

Custom providers

MIME types

Benchmark

Conclusion

References

Fluent Assertions: Fluently Assert the Result of .NET Tests

Installation

First assertion

Nullable types

Booleans

Strings

Numerics

Dates and times

Collections

Exceptions

Object graph comparison

Custom assertions

Assertion scopes

Execution time

Conclusion

References

FluentValidation: A Validation Library for .NET

Installation

First validator

Complex properties

Collections

Cascade mode

Severity level

Throw exception

Asynchronous validation

Custom validators

Localization

Testing

ASP.NET integration

Dependency injection

Manual validation

Automatic validation

Conclusion

References

Object Mapping in .NET

Why use object mapping?

Popular libraries

Implicit operator

Benchmark

Conclusion

References

Const and Readonly in C#

Const

Readonly

Differences between const and readonly

Conclusion

References

Covariance and Contravariance in C#

Covariance

Contravariance

Invariance

Conclusion

References

Ref, Out, In parameters in C#

Ref

Out

In

Limitations

Conclusion

References

Heap Sort

How it works

Time complexity

Space complexity

Conclusion

References

Garbage Collector in .NET

How it works

Generations

Benefits

Differences between `const` and `readonly`