Fluent API support for static methods

[AlexRadch]

Motivation

The fluent API is one of the most commonly used design patterns in C#. It is elegant and expressive, so a fluent code reads like prose. It is widely and ubiquitously used in libraries and public APIs. However, creating a fluent API can require a lot of ceremony. It is especially difficult to create a fluent API for static methods.

The idea of ​​how to extend C# to create a Fluent API for static methods came about when I was working on extending the Guard class from the .NET Community Toolkit library. The Guard class can be used to validate method arguments in a streamlined manner, which is also faster, less verbose, more expressive, and less error-prone than manually writing checks and throwing exceptions.

public void SampleMethod(int[] array, int index, Span<int> span, string text)
{
    Guard.IsNotNull(array);
    Guard.HasSizeGreaterThanOrEqualTo(array, 10);
    Guard.IsInRangeFor(index, array);
    Guard.HasSizeGreaterThanOrEqualTo(span, array.Length - index);
    Guard.IsNotNullOrEmpty(text);
}

The Guard has many static methods and does not support fluent API style and he didn’t need to support fluent API style until primary constructors were added to C#. There was a desire to support parameter checking in primary constructors.

public class SampleClass(int[] array, int index, Memory<int> memory, string text)
{
    protected int[] Array { get; } = Guard.IsNotNull(array).HasSizeGreaterThanOrEqualTo(10);
    protected int Index { get; } = Guard.IsInRangeFor(index, array);
    protected int Memory { get; } = Guard.HasSizeGreaterThanOrEqualTo(memory, array.Length - index);
    protected string Text { get; } = Guard.IsNotNullOrEmpty(text);
}

As you can see in the code above, the Guard class must support a fluent API style for checking the parameters in primary constructors.

How can we add support for primary constructors to the Guard class? We can't convert the Guard class methods into functions for several reasons. Firstly, the class will become binary incompatible with earlier versions, and secondly, a compiler warning will appear stating that the return value is not used anywhere in old classic methods.

One solution would be to add a FGuard (fluent guard) class whose extension functions would return a checked parameter. At the moment this is the best solution that C# can offer us. This solution has a huge disadvantage: We would have to duplicate a large number of methods of the original class, duplicate test methods for them, duplicate documentation for them, and then maintain it all in double size, which of course we want to avoid. Adding extension functions to the FGuard class begins to extend the available methods for all classes, which is also not very convenient. The extension functions of the FGuard class are needed only by primary constructors, but they become available throughout the program.

So I came up with the following objectives.

Objectives

To reduce the number of ceremonies, it is necessary to implement a fluent API for existing static methods:

1. Do not require duplication of a large number of methods of the original class, duplication of test methods for them, duplication of documentation for them.
2. Use an already written class and its methods without breaking binary compatibility.
3. Create a new fluent API in the original class, as if we had added extension functions to it.
4. The new fluent API should make extended fluent methods available only where the developer needs them.
5. Don't make new extended methods available where the developer doesn't need them.

The result should look like we have added extension functions to the original class and also satisfy the constraints mentioned in 4-5 points above.

Suggestions

I suggest adding the [Fluent] attribute to the parameter of the method for which we are adding support for the Fluent API. This is what it would look like for the original Guard class:

// Static class with fluent methods
public static class Guard
{
    public static void IsNotNull<T>([Fluent] T? value) {}
    public static void HasSizeGreaterThanOrEqualTo<T>([Fluent] Span<T> span, int minimum) {}
    public static void IsInRangeFor([Fluent] int index, ICollection collection) {}
    public static void IsNotNullOrEmpty([Fluent] string text) {}
}

As you can see, we did not change anything in the Guard class, we only added the [Fluent] attribute to its parameter, its binary compatibility has not changed.

To the compiler, this attribute will mean two things:

1. A parameter marked with the [Fluent] attribute will be automatically used to call the next method as if this method would return this parameter unchanged.
2. Class methods that have a parameter marked with the [Fluent] attribute become extension methods only for the parameter returned in the first point. Class methods do not become extension methods throughout the application because we did not add the this modifier to a parameter.

Below I showed how the compiler will compile code with the new fluent API.

// Fluent code
var guarded = Guard
    .IsNotNull(input)
    .IsLenghtInRange(10, 125)
    .IsAscii();

// Will be compiled to
string guarded;
{
    Guard.IsNotNull(input);
    Guard.IsLenghtInRange(input, 10, 125)
    Guard.IsAscii(input);
    guarded = input;
}

// Fluent code for the primary constructor
public class SampleClass(int[] array, int index, Memory<int> memory, string text)
{
    protected int[] Array { get; } = Guard.IsNotNull(array).HasSizeGreaterThanOrEqualTo(10);
    protected int Index { get; } = Guard.IsInRangeFor(index, array);
    protected int Memory { get; } = Guard.HasSizeGreaterThanOrEqualTo(memory, array.Length - index);
    protected string Text { get; } = Guard.IsNotNullOrEmpty(text);
}

// Will be compiled to
public class SampleClass(int[] array, int index, Memory<int> memory, string text)
{
    protected int[] Array { get; }
    protected int Index { get; }
    protected int Memory { get; }
    protected string Text { get; }

    public SampleClass(int[] array, int index, Memory<int> memory, string text)
    {
         Guard.IsNotNull(array); 
         Guard.HasSizeGreaterThanOrEqualTo(array, 10); 
         Array = array;

         Guard.IsInRangeFor(index, array);
         Index  = index;

         Guard.HasSizeGreaterThanOrEqualTo(memory, array.Length - index); 
         Memory = memory;

         Guard.IsNotNullOrEmpty(text);
         Text = text;
    }
}

Thus, the [Fluent] attribute allows the compiler to add full support for the new Fluent API to the Guard class without having to write a lot of duplicate code and documentation.

Likewise, this feature will be useful for adding Fluent API to many existing classes.

Other discussions on this topic

Fluent API and builders: language-level support
Return this type for fluent API
Discussion: implicit return of this for builder pattern with this type
"this" type
Implicit this return for Builder Pattern
Performance-effective Fluent API support

[KennethHoff]

I could see this being able to be done with a Roslyn Source Generator, by creating ( ideally a ref struct) that has methods with identical signatures that's just a wrapper around the original one.

[Fluent]
public static class Guard
{
    public static void NotNull(object o) {...}
    public static void NotFull(object o) {...}
}

The previous code spits out something like this

public ref struct FluentGuard
{
    public FluentGuard NotEmpty(object o)
    {
        Guard.NotEmpty(o)
return this;
    }
    public FluentGuard NotFull(object o)
    {
        Guard.NotFull(o);
    }
}

And you'd call it like this

new FluentGuard().NotEmpty(myObj).NotFull();

I'm not saying this is pretty - and this particular psycho code is probably wrong in many ways - but the concept might work.. or maybe not 🫠

[KennethHoff]

Don't get me wrong, I love the builder posted, and I definitely think it should get some more love on the language level.

The ol' public MyThing DoThing(param..) {...; return this;} is also very confusing and ugly.

[AlexRadch]

Writing the right code generator, even for this not-so-complicated case, is much more difficult than duplicating the code manually, which is what I've already done. And it would have taken me much more time to write and debug the generator.

[CyrusNajmabadi]

The benefit of a generator is that you do that investment once, but then can benefit greatly from that point on:-)

[DavidArno]

Writing the right code generator, even for this not-so-complicated case, is much more difficult than duplicating the code manually, which is what I've already done. And it would have taken me much more time to write and debug the generator.

You'd like the language team to do the work for you instead? In my view, your proposal is very closely aligned to source generators, so - regardless of who does the work - this does seem the obvious way of achieving your proposal.

But I don't think this the best way of achieving what you want here. Like with any other source generator solution, it all feels a big hacky with lots of wavy hand "magic" going on in non-obvious ways. In my view, having the language implement expression blocks would result in a cleaner solution here, as well as being useful in many other scenarios:

public class SampleClass(int[] array, int index, Memory<int> memory, string text)
{
    protected int[] Array { get; } = (Guard.IsNotNull(array); Guard.HasSizeGreaterThanOrEqualTo(array, 10); array);
    protected int Index { get; } = (Guard.IsInRangeFor(index, array); index);
    protected int Memory { get; } = (Guard.HasSizeGreaterThanOrEqualTo(memory, array.Length - index); memory);
    protected string Text { get; } = (Guard.IsNotNullOrEmpty(text); text);
}

[AlexRadch]

In my view, having the language implement expression blocks would result in a cleaner solution here, as well as being useful in many other scenarios

@DavidArno Yes! Expression blocks can solve this issue without creating a flexible API. But they won't help you create a flexible API for existing methods. Without a fluent API, a code is less readable anyway.

About Expression blocks: I would also prefer the design of expression blocks inside curly braces and an explicit indication of the expression that should be returned. This will allow you to see more clearly what is being returned. Like this { = array }; or even like this { := array };. I don't like how this is done implicitly in other languages.