AbstractBuilder 1.6.0

AbstractBuilder

A NuGet package that contains a builder pattern for testing in C#.

How to add it

To use this package, simply install the NuGet AbstractBuilder. It has no external dependencies.

dotnet add package AbstractBuilder

Alternatively, you can visit the NuGet webpage for AbstractBuilder: https://www.nuget.org/packages/AbstractBuilder/.

How does it works

We start with a default builder and modify it as needed. Each modification creates a new builder that inherits the previous changes. When we call the Build method, we create the object.

    MyBuilder builder = new MyBuilder()
        .WithArms(2)
        .WithLegs(2);

    Person john = builder.WithName("John").Build();
    Person peter = builder.WithName("Peter").Build();

In the previous example, we make two changes and create two Person objects.

How can I use it? - Way 1: Heritage

To use the AbstractBuilder class, you need to inherit from it and specify the generic type as the result. The build steps can vary in complexity, as shown in this example.

    public MyBuilder : AbstractBuilder<Person>
    {
        // DEFAULT CONSTRUCTOR
        public MyBuilder() : this(CreateDefaultValue)
        {
        }

        // MANDATORY CONSTRUCTOR (it can be private or protected)
        private MyBuilder(Func<Person> seedFunc) : base(seedFunc)
        {
        }

        public MyBuilder WithName(string name)
        {
            return Set<MyBuilder>(x => x.Name = name);
        }

        private static Result CreateDefaultValue()
        {
            return new Person {
                IsAlive = true
            };
        }
    }

Your builder requires a public constructor (the default constructor in the example) and another constructor with the seed (the visibility does not matter). In this example, we can set the "Name" property with the WithName method. We should always use the Set<> method to create new methods that modify the builder.

How can I use it? - Way 2: Using the abstract builder itself

You can use it directly without any restrictions. However, you will need to declare everything and you cannot reuse the builder.

    var builder = new AbstractBuilder<Person>()
        .Set(x => x.Arms = 2)
        .Set(x => x.Legs = 2);

    Person john = builder.Set(x => x.Name = "John").Build();
    Person peter = builder.Set(x => x.Name = "Peter").Build();

Could we aggregate some modifications in one call?

We can do either of these: call the lambda action multiple times or use brackets.

    var builder1 = new AbstractBuilder<Person>().Set(x => x.Arms = 2, x => x.Legs = 2)

    var builder2 = new AbstractBuilder<Person>().Set(x => {
        x.Arms = 2;
        x.Legs = 2;
    });

Asyncronous build

The process is the same, but with the synchronous method BuildAsync. The cancellation token can be accessed by passing an argument of type BuilderContext.

    var builderContext = new BuilderContext() { CancellationToken = myCancellationToken };

    var builder = new AbstractBuilder<Person>()
        .Set((x, ctx) => x.Arms = 2)
        .Set((x, ctx) => x.Legs = 2);

    Person john = await builder.Set(x => x.Name = "John").BuildAsync(builderContext);
    Person peter = await builder.Set(x => x.Name = "Peter").BuildAsync(builderContext);

BuilderContext

You can inherit from BuilderContext to pass your own arguments, besides the CancellationToken, if you need them.

If your builder has multiple constructors, the one with the BuilderContext parameter has the highest priority.

You can use any version of the Set method interchangeably, as the builder internally converts them to the same operation. However, if you omit the context parameter, you will not be able to access it for that method.

    var builderContext = new MyBuilderContext() { Multiplier = 5 };

    var builder = new AbstractBuilder<Person>()
        .Set((x, ctx) => x.Arms = 2 * ((MyBuilderContext)ctx).Multiplier)
        .Set(x => x.Legs = 2);

    Person mutantJohn = await builder.Set(x => x.Name = "John").BuildAsync(builderContext);
    Person mutantPeter = await builder.Set(x => x.Name = "Peter").BuildAsync(builderContext);

Builder for records

Records cannot use this generic builder pattern because their properties are read-only after the object is created. To achieve a similar result, you should use RecordBuilder.

    public record Point(double X, double Y, double Z); 

    public PointBuilder : RecordBuilder<Point>
    {
        public PointBuilder WithCoordinateAlpha()
        {
            return Set<PointBuilder>(p => p.X, () => 10)
                  .Set<PointBuilder>(p => p.Y, () => 20);
        }
    }

The Set method assigns a value to the chosen parameter. If no value is given, it uses the default value of the parameter or in the worst case, the default value of the type.

This builder supports both record class and record struct.

    var builder = new PointBuilder()
        .WithCoordinateAlpha();

    Point alpha = builder.Build();
    Point beta = builder.Set<PointBuilder>(x => x.Z, () => 10).Build();
    Point charlie = builder.Set<PointBuilder>(x => x.Z, () => 20).Build();

In the previous example, alpha was (10,20,0), beta was (10,20,10) and charlie was (10,20,20).

Enjoy t3st1ng!