The API goal canvas

The API goal canvas is an API modeling tool suggested by Arnaud Lauret in his excellent book "Designing Web API" at Manning. It is very simple and efficient: it involves filling in a table that lists the APIs to be executed for a user to reach his goal (eg: "Place an order").

To create an API goal canvas, you can provide the following information:

• The "what": what does the user want to do?

• The "who": who has access to the resource?

• The "how": what are the necessary API steps to achieve the user's goal?

• API inputs and outputs.

• The goal of the API.

Other columns can be added as needed:

• The category: purchase, administration, ...

• The scope to manage permissions, for example buy:create, admin:manage_products...

• The endpoint path.

• ...

Here is what it could looks like for an online store:

The problem

The API goal canvas is a very simple and efficient tool, domain experts can quickly adopt it. However, it has some drawbacks:

• The level of detail is important. This can be problematic in large domains: how to forget as few APIs as possible?

• In a microservices architecture, systems need to communicate. But when? What messages to send to other systems?

To answer these questions, DDD's Event Storming is of great help.

Event storming to the rescue

Principle

Event storming is a method for discovering and modeling a business domain. It is a question of being interested in first place in the events which occur in this domain. This makes the work efficient: events are facts that happened and they are non-debatable.

The principle is as follows:

1. Get post-its (it can be a lot!).

2. Invite the different profiles of your team: developers, business experts, testers...

3. Ask everyone to write on a post-it an event that happened in the domain. For example: "An order has been paid.". The participants must be at ease: there is no harm in imagining an event that does not exist in reality. The audience is here to learn from each other.

4. Organize and sort the events in chronological order.

5. For each event, ask participants which command (which process) is at its origin. Other information can be added on other color post-its such as aggregates.

Here is what it could look like for our online store:

Domain Events as API goal canvas milestones

We can use domain events in the API goal canvas as the milestones of our API journey. This allows a classic problem-solving approach: thoughts must begin by identifying the objectives to be achieved.

Step 1: focus on the essentials

In the previous example, the "Validate cart" API is missing in our first canvas because we dove too much into the details.

So we need to focus on the essentials first:

• Let's remove the input and output columns. These are implementation details.

• Add the events and their associated command.

• Add all the actions that lead to the event.

Step 2: complete the API canvas

Now it's about identifying all APIs and their implementation details (input, outputs, scopes, ...) that lead to a consistent API journey. Pay attention to the input and output data to ensure that it will be possible to chain API calls.

Below is an example of a completed API goal canvas:

Domain events are of great interest

Domain events serve as milestones during the APIs requirement analysis. They also play a vital role in microservices architectures:

1. They make it possible to establish clear audit trails.

2. They allow microservices to communicate asynchronously

3. They allow caches to update. I will talk about that in further articles.

In summary

To effectively identify the APIs to be implemented within a business domain and make them useful in your system, adopt an "Event first" (or "Message first") approach:

1. Organize a DDD Event storming.

2. Use the results of this work to create the milestones of your API goal canvas.

3. Complete your API goal canvas by identifying the APIs needed to reach these milestones.

4. Finally, add all implementation details you need (input, output, scopes, goal, ...) for your APIs into your goal canvas.

About the cover image

Messier 78. This well-known reflection nebula is found in the Orion constellation, just above Horsehead nebula. It asks very clear skies to be photographed.

View it in large size on my website.

I have been working recently on integration tests, an important topic for building sustainable software. I then discovered ASP.Net Core's TestServer to perform fast integration testing. But is it really faster than a classic ASP.Net Core server? Let's see that.

The test project

The project we are going to work on is a simple online sales website. It contains some microservices, all written using a functional architecture. We will focus on the Shopping Cart microservice. It contains an endpoint to add a product to a cart: we will use it to perform some benchmarking.

[HttpPost]
public async Task<ActionResult> AddProductToCart([FromBody] AddProductToCartDto addProductToCartDto)
{
    /*...*/
}

ASP.Net Core TestServer

ASP.Net Core TestServer is a web server you can find in ASPNetCore.TestHost package. It makes the handling of HTTP requests fast because they don't go through a normal network stack.

BenchmarkDotNet

We will use BenchmarkDotNet to compare the performance between the two approaches. It is a small and extremely well-made library to carry out performance measurements. The purpose of this article is not to show how it works, for that you need to refer to its documentation.

The benchmark classes

ServerBase.cs

To make a fair comparison, the context must be the same between the two servers. So we will pool as much code as possible between the two approaches, i.e.:

• Creation of an in-memory SQLite database.

• Initialization of the test data.

• Initialization of DI services.

• Initialization of the web server.

These initializations are done in the constructor of an abstract ServerBase.cs class:

public abstract class ServerBase
{
    protected WebApplicationBuilder WebAppBuilder { get; set; }
    protected WebApplication WebApp { get; set; }
    protected CallistoDbContext DbContext { get; set; }
    protected SqliteConnection Connection { get; set; }
    protected HttpClient? Sut { get; set; }

    private readonly string _baseUrl;

    protected ServerBase(string baseUrl)
    {
        WebAppBuilder = WebApplication.CreateBuilder();
        WebAppBuilder.Services.AddControllers().PartManager.ApplicationParts.Add(new AssemblyPart(typeof(CartController).Assembly)); // Necessary to add controllers from other projects

        Connection = new SqliteConnection("DataSource=file::memory:"); // We will use an in-memory Database
        Connection.Open();

        // Database Initialization
        var options = new DbContextOptionsBuilder<CallistoDbContext>().UseSqlite(Connection);
        DbContext = new CallistoDbContext(options.Options);
        DbContext.Database.Migrate();
        DbContext.Product.Add(new ProductModel("2EJX-6HCC", "PS5", "Playstation 5", 500, DateTime.UtcNow));
        DbContext.SaveChanges();

        // Services configuration
        WebAppBuilder.Services.AddSingleton<CallistoDbContext>(_ => DbContext);
        WebAppBuilder.Services.AddTransient<ICartRepository, CartRepository>();
        WebAppBuilder.Services.AddTransient<IProductRepository, ProductRepository>();

        WebAppBuilder.WebHost.UseUrls(baseUrl);
        _baseUrl = baseUrl;
    }
}

Finally, we will add a test method to call the endpoint for adding a product to a cart. The first call adds a product to a new cart (because no CartId is given), then we add 10 times the same product in this cart:

public async Task RunTest()
{
    var addProductToCart = new
    {
        CartId = "",
        ProductId = "2EJX-6HCC",
        Quantity = 1
    };

    var response = await Sut!.PostUtf8Async($"{_baseUrl}/carts", addProductToCart);
    var cartId = (await response!.Content.ReadFromJsonAsync<List<Read.Entities.Cart>>())!.ElementAt(0).CartId;


    // Adding 10 times the same product in the cart
    for (int i = 0; i < 10; i++)
    {
        addProductToCart = new
        {
            CartId = cartId,
            ProductId = "2EJX-6HCC",
            Quantity = 1
        };
        await Sut.PostUtf8Async($"{_baseUrl}/carts", addProductToCart);
    }
}

ClassicServer.cs

This class contains initializations specific to the test with the classic server. It inherits from ServerBase.cs:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace Callisto.Sales.Benchmark
{
    internal class ClassicServer : ServerBase
    {
        public ClassicServer(string baseUrl) : base(baseUrl)
        {
            WebAppBuilder.Services.AddHttpClient();
            var serviceProvider = WebAppBuilder.Services.BuildServiceProvider();
            Sut = serviceProvider.GetService<HttpClient>()!;

            WebApp = WebAppBuilder.Build();
            WebApp.MapControllers();
            WebApp.Start();
        }
    }
}

TestServer.cs

This class contains initializations specific to testing with the ASP.Net Core TestServer; it also inherits from the ServerBase.cs class:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.TestHost;
using Microsoft.Extensions.Hosting;

namespace Callisto.Sales.Benchmark 
{
    internal class TestServer : ServerBase
    {
        public TestServer(string baseUrl) : base(baseUrl)
        {
            WebAppBuilder.WebHost.UseTestServer(); // Using TestServer

            WebApp = WebAppBuilder.Build();
            WebApp.MapControllers();
            WebApp.Start();

            Sut = WebApp.GetTestClient(); // Getting an HttpClient directly from the app.
        }
    }
}

The benchmark class

The benchmark class is as follows:

using BenchmarkDotNet.Attributes;

namespace Callisto.Sales.Benchmark
{
    [SimpleJob(launchCount: 5, warmupCount: 2, iterationCount: 10)]
    public class ClassicServerVSTestServerBenchmark
    {
        private readonly ClassicServer _classicServer;
        private readonly TestServer _testServer;

        public ClassicServerVSTestServerBenchmark()
        {
            _classicServer = new ClassicServer("http://localhost:5000");
            _testServer = new TestServer("http://localhost:5001");
        }

        [Benchmark]
        public async Task Classic_Server_Benchmark()
        {
            await _classicServer.RunTest();
        }

        [Benchmark]
        public async Task Test_Server_Benchmark()
        {
            await _testServer.RunTest();
        }
    }
}

And finally, to run the benchmark, we create a simple console project:

using BenchmarkDotNet.Configs;
using BenchmarkDotNet.Running;

namespace Callisto.Sales.Benchmark
{
    internal class Program
    {
        static void Main(string[] args)
        {
            BenchmarkRunner.Run<ClassicServerVSTestServerBenchmark>();
        }
    }
}

First results

Now, let's run the benchmark:

dotnet run -c Release

After a few minutes, I get these results:

|                      Method |         Mean |        Error |       StdDev |
|---------------------------- |-------------:|-------------:|-------------:|
|    Classic_Server_Benchmark | 455,511.2 us | 24,192.14 us | 48,314.32 us |
|       Test_Server_Benchmark | 454,201.1 us |  7,812.13 us | 15,780.88 us |

Intermediate conclusion: the gain with the test server is not obvious (~1.5 ms/test). I was a bit disappointed... So I wondered what the result would be without database interaction, only focusing on the network part. Let's see that.

A benchmark without database interaction

In the Shopping Cart microservice, I added a stub endpoint that does strictly nothing.

Then, in ServerBase.cs, I added a test for this endpoint :

public async Task RunTestWithoutDatabaseInteraction()
{
    await Sut.GetAsync($"{_baseUrl}/carts/stub");
}

I then added the following two new benchmarks in ClassicServerVSTestServerBenchmark.cs :

[Benchmark]
public async Task Classic_Server_Without_Database_Interaction_Benchmark()
{
    await _classicServer.RunTestWithoutDatabaseInteraction();
}

[Benchmark]
public async Task Test_Server_Without_Database_Interaction_Benchmark()
{
    await _testServer.RunTestWithoutDatabaseInteraction();
}

Here are the results :

|                                                Method |         Mean |        Error |       StdDev |
|------------------------------------------------------ |-------------:|-------------:|-------------:|
| Classic_Server_Without_Database_Interaction_Benchmark |   2,137.9 us |     32.98 us |     61.94 us |
|    Test_Server_Without_Database_Interaction_Benchmark |     177.6 us |      6.99 us |     13.48 us |

This time, the gain brought by the TestServer is clear: the calls to an endpoint are 12x faster! We gain ~2 ms per endpoint call, which is consistent with the results from the previous benchmark.

Conclusion

ASP.Net Core's TestServer only saves time on network calls by a few milliseconds. Perhaps the gains could be significant on a broad base of integration tests.

In any case, your database will remain the bottleneck for integration testing.

About the cover image

The Source of the Universe. In the desert of Atacama in Chile, the Milky Way seems to spring from a small and perfectly calm water hole...

View it in large size on my website.

Last article of the series: the application layer. We will talk about its role, how to write it in a functional style with just a few lines of code but also how to deal with asynchronism. For that, we will use all the concepts we have learned so far. Let's dive in and let's create sustainable software.

A refresher on the functional architecture

Functional architecture is a rigorous clean or onion architecture. Its domain and application layers are written by applying the principles of functional programming: immutability, function composition, etc.

A functional application layer

Remember, the application layer is an orchestrator between the infrastructure layer and the domain layer: the domain layer make the decisions and the infrastructure layer executes the necessary side effects (saving to a database, posting a message in a bus, ....) thanks to the application layer.

Let's take an example: adding a product to a catalog. The application layer will be responsible to perform the following steps:

1. Transform a ProductDto into a domain Product.

2. Check if the product reference already exists.

3. Save the product to the database.

We want these steps to be written in a functional style by creating a pipeline. We will use for that techniques we've learned so far: containers, Bind() and Map() functions.

Creating the pipeline

Creating the AddProduct() function

Let's create this function. We will complete it all along this article. It will look like this :

public static async OperationResultDto<ProductDto> AddProduct(
    AddProductDto addProductDto)
{
}

I have defined an OperationResult<T>: it will contain a value if no error happened during the operation, else it will contain an error.

Railway-oriented programming

A word about railway-oriented programming first. As soon as something wrong happens in the flow, then it is switched towards an error path: the execution flow of the pipeline is interrupted and the error messages are returned.

In our pipeline, the execution flow will be automatically routed to the error path whenever an entity is in an invalid state, thanks to Map() and Bind() functions defined on the entities.

Here is a little drawing to help you understand. This programming style is extremely well explained by Scott Wlaschin here.

Identifying the signatures of the pipeline functions

First step to write our pipeline: identifying the signatures of the functions that we will use for each step.

To easily create our pipeline, we will use an Entity<Product> as we've learned in the previous articles.

Its steps will be as follows:

1. We need to transform a ProductDto into a domain Product. The signature of this function will be ProductDto -> Entity<Product>.

2. Next, we need to check if the product reference already exists. For that, we will create a function that takes a domain Product and a count of identical references as parameters. It will return an Entity<Product> in a valid state if no other references have been found in the database, else it will be in an invalid state. So the function's signature will be Product -> int -> Entity<Product>.

3. Next, we need to save the product. The saving will be done by a repository. It will take a domain Product as a parameter and will return the saved domain product as a response. The signature of such a function is Product -> Product.

Nevertheless, we have a problem to create our pipeline because the function's outputs are all different, thus preventing us to chain them using a fluent style. That is where Bind() and Map() functions will come into play.

First step: converting a ProductDto to Entity<Product>

This first step is an easy one. We need transform a ProductDto into an Entity<Product>.

To do that, we simply define an extension method on the ProductDto class. I already have defined Reference, Name and Price Value Objects as explained in the 4th article of this series. I then create the Product Entity using the guidelines of the previous article of this series.

public static class AddProductDtoExtensions
{
    public static Entity<Product> ToProductEntity(this AddProductDto addProductDto)
    {
        return Product.CreateEmpty()
                        .WithReference(addProductDto.Reference)
                        .WithName(addProductDto.Name)
                        .WithPrice(addProductDto.Price);
    }
}

If a value of the ProductDto is not or incorrectly filled in, then the value objects will return an error when they are instantiated: they act as control gates and a big advantage of that is that we don't need to provide any model validation in the Dtos thus avoiding code duplication between the domain layer and the infrastructure layer. The entity will then be created in an invalid state and all subsequent steps in the flow will be skipped.

Now let's complete AddProduct() function and let's call our new extension method to convert our AddProductDto into an Entity<Product>:

public static OperationResultDto<ProductDto> AddProduct(
    AddProductDto addProductDto)
{
    var p = addProductDto.ToProductEntity();

    return p.Match(
        Valid: (v) => new OperationResultDto<ProductDto>(v.ToProductDto()),
        Invalid: (e) => new OperationResultDto<ProductDto>(e)
    );
}

Second step: verifying if the product reference exists

Let's create our verification function. It is a decision-making function, so you need to put in the domain layer. It returns an invalid Entity<Product> if the reference already exists:

public static Entity<Product> VerifyProductReference(Product product, int existingReferencesCount)
{
    if (existingReferencesCount > 0)
        return Entity<Product>.Invalid(new Error(string.Format(Messages.TheProductReferenceAlreadyExists, product.Reference.Value)));
    else
        return Entity<Product>.Valid(product);
}

In Grenat.Functional.DDD library, I added some implicit conversions to simplify writing. The following code is equivalent and shorter:

public static Entity<Product> VerifyProductReference(Product product, int existingReferencesCount)
{
    if (existingReferencesCount > 0)
        return new Error(string.Format(Messages.TheProductReferenceAlreadyExists, product.Reference.Value)); // No need do call Entity<Product>.Invalid()
    else
        return product;
}

But how does this function chain to the result of the previous step? The previous function outputs an Entity<Product>, and we need a Product. Well, we will use the Bind() function. Remember, Bind() takes a function and it applies it to the wrapped value of the Entity<T> container.

Using Bind(), we can add simply add this new step to our AddProduct() function:

public static OperationResultDto<ProductDto> AddProduct(
    AddProductDto addProductDto,
    Func<string, int> CountProductReferences)
{
    var p = addProductDto.ToProductEntity()
            .Bind(VerifyProductReference, CountProductReferences(addProductDto.Reference));

    return p.Match(
        Valid: (v) => new OperationResultDto<ProductDto>(v.ToProductDto()),
        Invalid: (e) => new OperationResultDto<ProductDto>(e)
    );
}

Third step: saving the product

I did not want to introduce an Entity<Product> container in the repository for that. It would have been useless to deal with an entity's state in the repository. The decision to save the product was already made by the domain layer, so the repository just have to execute. It does not need to verify the decision.

So the save function signature will be Product -> Product. Here again how to chain it to the function of the previous step? We need a Product whereas the previous step outputs an Entity<Product>. What's more, we need to get back an Entity<Product> to stay in the elevated world.

In that situation, Map() becomes handy. It is the same as Bind(), i.e. it takes a function and its parameters and it applies it to the wrapped value of the Entity<T> container.

But instead, it lifts the function's output to the elevated world: Entity<Product>, allowing us to stick to the elevated world.

So let's update the AddProduct() function by adding this last step. I will not give the details of the SaveProduct() function, it is a classical repository function.

public static OperationResultDto<ProductDto> AddProduct(
    AddProductDto addProductDto,
    Func<string, int> CountProductReferences
    Func<Product, Product> SaveProduct)
{
    var p = addProductDto.ToProductEntity()
            .Bind(Domain.Services.VerifyProductReference, CountProductReferences(addProductDto.Reference))
            .Map(SaveProduct);

    return p.Match(
        Valid: (v) => new OperationResultDto<ProductDto>(v.ToProductDto()),
        Invalid: (e) => new OperationResultDto<ProductDto>(e)
    );
}

Look how simple and clear is this code. Thanks to functional concepts, it deals with error harvesting and error management without having to write any conditional logic. If another step needs to be added to the flow, well... just insert it into the pipeline using Map(), Bind() and Entity<Product>. Forget about errors, say goodbye to many bugs :)

Dealing with asynchrony

All functions working with infrastructure resources must be asynchronous. Therefore, they must work with Tasks. But in C#, the syntax for representing functions returning Tasks is quite cumbersome… Func<Task<T>>, Func<T, Task<R>> …

To make our life easier, I added an AsyncFunc delegate to simplify this writing in Grenat.Functional.DDD:

• Func<Task<T>> is equivalent to AsyncFunc<T>.

• Func<T, Task<R>> is equivalent to AsyncFunc<T, R>.

• Etc., etc…

I also added asynchronous versions of Map() and Bind() : MapAsync() and BindAsync(). So, an asynchronous version of AddProduct() will be as follows:

public static async Task<OperationResultDto<ProductDto>> AddProduct(
    AddProductDto addProductDto,
    AsyncFunc<string, int> CountProductReferences,
    AsyncFunc<Product, Product> SaveProduct)
{
    var p = await addProductDto.ToProductEntity()
                    .BindAsync(VerifyProductReference, CountProductReferences(addProductDto.Reference))
                    .MapAsync(SaveProduct);

    return p.Match(
        Valid: (v) => new OperationResultDto<ProductDto>(v.ToProductDto()),
        Invalid: (e) => new OperationResultDto<ProductDto>(e)
    );
}

Improving performance with lazy evaluation

We have a performance problem with the previous code. It comes from this line of code:

.BindAsync(VerifyProductReference, CountProductReferences(addProductDto.Reference))

Here, the function CountProductReferences() is called even if Entity<Product> is in an invalid state because it is given as a parameter.

To correct this problem, you should give a function as a parameter. An overload of BindAsync() exists for that in my library: it will call the given function only if Entity<T> is valid. This behavior is called lazy evaluation.

The correct statement is as follows:

.BindAsync(VerifyProductReference, () => CountProductReferences(addProductDto.Reference))

Calling AddProduct from an ASP.Net Core controller

Finally, the code to call the application layers' AddProduct() function from an ASP.Net Core controller could look like this:

[HttpPost]
public async Task<ActionResult> AddProduct(AddProductDto addProductDto)
{
    var response = await CatalogOperations.AddProduct(
                                addProductDto,
_productRepository.CountExistingProductReferences,
                                _productRepository.AddProduct);
    if (response.Success)
        return Ok(response.Data);
    else
        return UnprocessableEntity(response.Errors);
}

As you can see, I pass functions as parameters instead of passing interfaces to AddProduct(). This functional approach makes the application much easier to test.

Summary

• Use functional techniques to write a very thin application layer: railway-oriented programming, containers (Entity<T>, ValueObject<T>, ...) and their underlying operations: Map(), Bind().

• Use my library Grenat.Functional.DDD to help you with that.

• Don't forget to use asynchrony for better performance when handling out-of-process resources (databases, message bus, ....).

• Think of lazy evaluation for better performance: when calling a function that needs to handle time-consuming resources, give a function reference as a parameter and don't call it in case of an error.

Final words about the series

This was the last article of this series. I hope you enjoyed it and that you learned new techniques for your daily C# DDD work. Feel free to contact me if you have any questions! :)

About the cover image

IC 4628, the Prawn nebula. This pretty nebula is found in the Scorpius constellation. It is visible with good conditions only in the southern hemisphere. Total exposure time is about 9 hours.

See it in large size in my portfolio.

Now that you know a lot about the functional representation of value objects, it is time to switch to entities and aggregates.

Entities in a few words

Unlike value objects, entities are data structures that have an identity. Let's take an example: a shopping cart. It must be traced in the purchase flows, so it must be assigned an identity.

Let’s start from this very first definition, we will improve it throughout this article:

public class Cart
{
    public int Id { get; set; } // An entity have an identifier
    public int TotalAmountWithoutTax { get; set; }
    // Incoming : Cart Items
}

The composition of an entity

An entity should consist of:

• Value objects (or list of value objects).

• And/or entities (or list of entities).

Let's see why.

A word on primitive obsession first

In the current cart implementation, we used two integers for the identifier and the total amount. Using primitives is a bad idea because it leads to the writing of defensive code, that is, code that does not believe in itself. This is called "Primitive obsession".

For example, suppose we need to calculate the total cart price with tax. What's more, the business asks us to implement two validations:

• Tax amount cannot be negative.

• The total amount of an order cannot exceed 10000.

It may be tempting to write this:

public class Cart 
{
    public int Id { get; set; }
    public int TotalAmountWithoutTax { get; set; }
    public int TotalAmountWithTax { get; set; }
    // Incoming : Cart Items

    public void SetTotalAmountWithTax(int taxAmount) 
    {
        if (taxAmount < 0) 
            throw new BusinessException("The tax amount cannot be negative.");

        var totalAmountWithTax = TotalAmountWithoutTax * taxAmount;        
        if (totalAmountWithTax > 10000) 
            throw new BusinessException("The total amount cannot be more than 10000.");

        TotalAmountWithTax = totalAmountWithTax;
    }
}

The problem is that this code is very defensive: several validations are carried out before executing the code. Now imagine these rules may have to be implemented in other places in the code: there is a high risk of code duplication.

An entity should consist of value objects...

Now we have seen value objects are so important, we will systematically use value objects in our entities instead of using primitives. They will our elementary blocks of code. We will define two of them: Amount and Identifier.

Here is the Amount Value Object. It is very important to define them as record so they remain immutable.

public record Amount
{
    private const int MAX_AMOUNT = 10000;
    private const int MIN_AMOUNT = 0;

    public readonly int Value;

    public Amount(int amount) 
    {
        if (amount < MIN_AMOUNT) 
            throw new BusinessException("An amount cannot be negative.");
        if (amount > MAX_AMOUNT)
            throw new BusinessException($"An amount cannot be more than {MAX_AMOUNT}.");

        Value = amount;
    }
}

Our cart class is slimmed down and now looks like this:

public class Cart 
{
    public Identifier Id { get; set; }
    public Amount TotalAmountWithoutTax { get; set; }
    // Incoming : Cart Items, Client

    public Amount GetTotalAmountWithTax(Amount taxAmount) 
    {
        return new Amount(TotalAmountWithoutTax.Value * taxAmount.Value);        
    }
}

With Value Objects, you no longer need elementary checks or even to think about it. I recommend that you apply a strict rule: do not use any primitive in the entities. It is restrictive at first, but after that, it will ease your mind.

The only downside of Value Objects is the lack of context in the error messages. For example, you will get a standard error "An amount cannot be negative." But I think that's OK because we usually know the context when the error occurs. If you really need to contextualize the error message, you can assign a code to the error, then catch that code and change the error message where you need to.

... and they should consist of other entities

An entity should consist of other entities or a collection of entities. In that case, it becomes an aggregate and it must be saved as a whole in the database.

For example, our cart becomes an aggregate when we introduce the items:

public class Cart 
{
    public Identifier Id { get; set; }
    public ImmutableList<Item> items { get; set; } 
    public Amount TotalAmountWithoutTax { get; set; }
    public Amount TotalAmountWithTax { get; set; }

    public void SetTotalAmountWithTax(Amount taxAmount) { /* ... */ }
}

In an aggregate, one entity must be designated as the aggregate root: it is responsible for the consistency of all the data in the aggregate. For example, the operation of updating a child entity is the responsibility of the aggregate root.

In our example, the aggregate root is the cart entity and it will embed the modification of an item. Thus, the total amount of the basket will be updated and will remain consistent with the current items in the basket.

public class Cart 
{
    public Identifier Id { get; set; }
    public List<Item> items { get; set; } 
    public Amount TotalAmountWithoutTax { get; set; }
    public Amount TotalAmountWithTax { get; set; }

    public void SetTotalAmountWithTax(Amount taxAmount) { /* ... */ }

    // Updating the quantity of an item is the responsability of the cart class
    public void UpdateItem(Item item){ /* ... */ }
}

Note that it is very important to favor simple identifiers instead of entities to limit the size of the aggregates. Do not try to model the reality: use only the data you need to persist the aggregate and maintain its consistency.

For more information about DDD, aggregates, entities and value objects in .Net, I strongly recommend the lecture on "Patterns, principles and practices of DDD" where the concepts are extremely well explained.

A functional entity

A read-only data structure

As we have seen previously, data structures are immutable in functional programming. The easiest change to make is transforming the class into a record like the value objects, and transforming the Lists into immutable lists.

public record Cart 
{
    public Identifier Id { get; init; }
    public ImmutableList<Item> Items { get; init; }
    public Amount TotalAmountWithoutTax { get; init; }
    public Amount TotalAmountWithTax { get; init; }
}

Behaviors

In functional programming, data is immutable and there is no state. Thus, behaviors become static extension methods of the immutable data structure and they return a new instance of it:

public static class CartExtensions 
{
    public static Cart SetTotalAmountWithTax(this Cart cart, Amount taxAmount) 
    {
        return cart with { TotalAmountWithTax = new Amount(cart.TotalAmountWithoutTax.Value * taxAmount.Value) } ;
    }
}

An Entity<T> container

As we have seen in previous articles, containers are a great help for chaining function calls. This will serve us a lot in the Application layer we will study it in the next article.

An Entity<T> container has been defined in my little library Grenat.Functional.DDD. Like ValueObject<T> it has two states: one valid and one invalid. Bind and Match operations have also been defined. See the previous article of this series for more details.

The challenges of immutability and container composition

Dealing with immutability and containerized entities is not an easy task. We will face several problems. Let's see why and how to tackle them.

The problem of container composition

If you read my previous article, Value Objects will be created and containerized in a ValueObject<T> container thanks to their static constructor. And they will be themselves containerized in a parent Entity<T> container. And we face the problem of a container containing other containers, i.e. an Entity<T> containing some ValueObject<T> or some Entity<T>. This is not convenient.

We don't want to write this:

public record Cart
{
    public ValueObject<Identifier> Id { get; init; }
    public ImmutableList<Entity<Item>> Items { get; init; }
    public ValueObject<Amount> TotalAmountWithoutTax { get; init; }
    public ValueObject<Amount> TotalAmountWithTax { get; init; }

    /*...*/
}

We want to write this:

public record Cart
{
    public Identifier Id { get; init; }
    public ImmutableList<Item> Items { get; init; }
    public Amount TotalAmountWithoutTax { get; init; }
    public Amount TotalAmountWithTax { get; init; }

    /*...*/
}

What's more, whenever we need to change an entity's property, we have to recreate a new instance of it to stick with immutability principles.

To solve these problems, Grenat.Functional.DDD contains some setters:

• SetValueObject

• SetEntity

• SetEntityList

• SetEntityDictionary

• SetEntityOption

• SetValueObjectOption

Behind the scenes, these setters :

1. Unwrap the inner value of the Entity<T> to modify. Then :

2. Unwrap the inner value of the container (an Entity<V>, a ValueObject<V>, an Option<V>, ...) that is passed as a parameter,

3. They modify the targeted property of Entity<T> thanks the setter function,

4. And they wrap the result in an new instance of Entity<T>.

If one of the Entity or ValueObject parameter is invalid, then the resulting Entity<T> will become invalid too.

Finally, Errors are harvested into this resulting entity.

Let's study them.

SetValueObject

Here is the function's signature :

public static Entity<T> SetValueObject<T, V>(this Entity<T> entity, ValueObject<V> valueObject, Func<T, V, T> setter) { /*...*/ }

It takes as arguments:

• The entity.

• The value object to set into the entity.

• A setter function.

You can use it this way:

public static Entity<Cart> SetTotalAmount(this Entity<Cart> cart, ValueObject<Amount> totalAmount)
{
     return cart.SetValueObject(totalAmount, static (cart, totalAmount) => cart with { TotalAmount = totalAmount });
}

SetEntity

SetEntity is the same as SetValueObject but instead of accepting a ValueObject<T> as a parameter, it accepts an Entity<T>. Here is its signature:

public static Entity<T> SetEntity<T, E>(this Entity<T> parentEntity, Entity<E> entity, Func<T, E, T> setter) { /* ... */ }

SetValueObjectList, SetEntityList, SetEntityDictionary, SetEntityOption...

As their name suggests, these setters do the same than the previous ones, but for immutable lists, immutable dictionaries and optionable entities and value objects.

Error harvesting

All setters perform error harvesting. That is to say, if you try to set an invalid value object or an invalid entity, their errors are harvested and added to the ones already existing on the parent entity. It is very interesting for APIs: if the user types bad data, then all the errors will be returned.

Let's have a look at an example, and let's define two value objects Identifier and Amount, written following the guidelines of the previous article:

Here is an Identifier value object:

public record Identifier
{
    public const string DEFAULT_VALUE = "";
    public readonly string Value = "";
      
    public Identifier() { Value = DEFAULT_VALUE; }

    private Identifier(string identifier)
    {
        Value = identifier;
    }

    public static ValueObject<Identifier> Create(string identifier)
    {
        if (string.IsNullOrEmpty(identifier))
            return new Error("An identifier cannot be null or empty.");

        return new Identifier(identifier);
    }
}

And here is an Amount value object:

public record Amount
{
    public const int MAX_AMOUNT = 2500;
    public const int DEFAULT_VALUE = 0;
    public const string DEFAULT_CURRENCY = "EUR";

    public readonly int Value;
    public readonly string Currency = DEFAULT_CURRENCY;

    public Amount() { Value = DEFAULT_VALUE; }

    private Amount(int value, string currency = DEFAULT_CURRENCY)
    {
        Value = value;
        Currency = currency;
    }

    public static ValueObject<Amount> Create(int amount)
    {
        if (amount < 0)
            return new Error("An amount cannot be negative.");
        if (amount > MAX_AMOUNT)
            return new Error(String.Format($"An amount cannot be more than {MAX_AMOUNT}"));

        return new Amount(amount);
    }
}

Now let's create a cart by setting invalid data and let's see the errors harvesting in action. Cart.Create() is a static constructor returning an empty Entity<Cart>:

var cart = Cart.Create()
            .SetValueObject(Identifier.Create(null), static (cart, identifier) => cart with { Id = identifier })
            .SetValueObject(Amount.Create(-1), static (cart, totalAmountWithoutTax) => cart with { TotalAmountWithoutTax = totalAmountWithoutTax })
            .SetValueObject(Amount.Create(3000), static (cart, totalAmountWithTax) => cart with { TotalAmountWithTax = totalAmountWithTax });

Console.WriteLine(cart.Errors);
// Output :
// An identifier cannot be null or empty.
// An amount cannot be negative.
// An amount cannot be more than 2500.

But, I agree with you, this code is a bit cryptic and not very "ubiquitous language"... Can we do better? Of course we can! Let's have a look.

Creating "ubiquitous language" setters

For better readability, you can create some setters using extension methods. They will call SetValueObject, SetEntity, SetEntityList, SetEntityDictionary functions under the hood. But be careful, Setters can be an anti-pattern that leads to data inconsistency, so use them wisely.

Here is an example:

public static class CartSetters
{
    public static Entity<Cart> SetId(this Entity<Cart> cart, string id) 
    {
        return cart.SetValueObject(Identifier.Create(id), static (cart, identifier) => cart with { Id = identifier });
    }

    public static Entity<Cart> SetTotalAmountWithoutTax(this Entity<Cart> cart, int totalAmount) 
    {
        return cart.SetValueObject(Amount.Create(totalAmount), static (cart, totalAmount) => cart with { TotalAmountWithoutTax = totalAmount });
    }

/* ... */
}

The problem of constructors

An entity with 6 fields requires a constructor with 6 parameters which is a lot... Moreover, some parameters could not be known depending on the call context. This would require creating several constructors or creating optional parameters.

To avoid multiplying the constructors, we will take inspiration from the builder pattern. Here is what I want to write to create a cart item:

var cartItem = new CartItemBuilder()
    .WithId("45xxsDg1=")
    .WithProductId("ne252TJqAWk3")
    .WithAmount(25)
    .Build();

How to do that? First, let's create the CartItem Entity :

public record Item 
{
    public Identifier Id { get; init; }
    public Identifier ProductId { get; init; }
    public Amount Amount { get; init; }
      
    private Item()
    {
        Id = new Identifier();
        ProductId = new Identifier();
        Amount = new Amount();
    }

    public static Entity<Item> Create(string id, string productId, int amount)
    {
        /* Add some verifications here if needed by returning an Error 
         * which will be automatically converted in an invalid Entity.
         * Eg: return new Error("Error !!")
         */

        return Entity<Item>.Valid(new Item())
            .SetId(id)
            .SetProductId(productId)
            .SetAmount(amount);
    }
}

And let's create the builder:

public record ItemBuilder
{
    private string _id { get; set; }
    private string _productId { get; set; }
    private int _amount { get; set; }

    public ItemBuilder WithId(string id) { _id = id; return this; }
    public ItemBuilder WithProductId(string productId) { _productId = productId; return this; }
    public ItemBuilder WithAmount(int amount) { _amount = amount; return this; }

    public Entity<Item> Build() => Item.Create(_id, _productId, _amount);
}

Et voilà! :) We now have a fully functional, immutable and containerized entity. It is the best approach I found so far, if you have new ideas to improve this, please let me know!

Next, we will talk about the application layer: containerization and binding will reveal their full power for chaining functions and error management, without writing tons of conditional logic.

You can find the complete source code of this article on my Github.

Some code generation

Writing all these setters and builders can be cumbersome work. So I wrote some Roslyn generators for that, have a look if you are interested: Grenat.Functional.DDD.Generators.

Summary

• An entity should be composed of entities, a list of entities or value objects, but never primitives.

• In a functional approach :

  • Use C# records to create immutable entities.

  • All behaviors take the form of extension methods that return a copy of the new entity.

• Use my library Grenat.Functional.DDD to help you with container composition and immutability.

About the cover image

This pretty little nebula located in the Cygnus constellation seems to make its way in the middle of a field of stars… The total exposure time is about 15 hours.

See it in large size in my portfolio.

Now is the time to tackle DDD... and let's start with Value Objects. We will study them using a classic object approach and then we will switch to a more functional approach.

Value objects in a few words

Value objects are the building blocks of any development made using DDD thinking. Value objects model things that don't have an identity: an amount of money, a quantity, an address, or a price... And since they have no identity, the equality of two Values Objects is achieved by comparing all the values they contain.

Another very important characteristic of Value objects is their immutability. They are not "variables", they are, as their name suggests, values. So to modify a Value Object, you need to create a new one.

An object approach

Let's take an example to illustrate this article. Here is a Quantity Value Object made using an object approach. It contains two fields: Value and Unit.

public class Quantity
{
    public readonly int Value;
    public readonly string Unit;

    public Quantity(int Quantity, string unit)
    {
        Value = Quantity;
        Unit = unit;
    }
}

As you can see, the Quantity Value Object is immutable because of its read-only attributes. So to modify one of its properties, you need to create a new one.

Let's enrich this object by adding a business rule. Let's say a quantity can never be more than 100. So we add a rule in the constructor, ensuring that no Quantity object will ever exist in our application with a value superior to 100. What's very interesting is that Value Objects Value Object helps us make illegal states unrepresentable in our application.

public Quantity(int quantity, string unit)
{
    if (quantity > MAX_QUANTITY)
        throw new ValueObjectException($"A quantity cannot be more than {MAX_QUANTITY}.");

    Value = quantity;
    Unit = unit;
}

We need now to implement the equality comparison. Remember, in case of Value Objects, we need to compare their members one by one. To do this, we will use the ValueObject base class as shown on Microsoft's website.

For the purposes of this article, we'll also add a function to increment the value. The final code of our quantity Value Object looks like this:

public class Quantity : ValueObject
{
    public readonly int Value;
    public readonly string Unit;

    public const int MAX_QUANTITY = 100;

    public Quantity(int quantity, string unit)
    {
        if (quantity > MAX_QUANTITY)
            throw new Exception($"A quantity cannot be more than {MAX_QUANTITY}.");

        Value = quantity;
        Unit = unit;
    }

    public Quantity Add(int increment) {
        return new Quantity(Value + increment, Unit);
    }

    protected override IEnumerable<object> GetEqualityComponents()
    {
        yield return Value;
        yield return Unit;
    }
}

Now it is time to move to a more functional approach.

A functional Value Object

The functional approach requires us to make some modifications in our Quantity Value Object:

• Inheritance being absent from functional concepts, we will remove the inheritance from the ValueObject class.

• Functional programming separating data and functions: we will move the Add method into an extension method.

• In functional programming, functions need to be honest. So we will remove the Exception thrown in the constructor and we will use another mechanism.

• And finally, we will define a container to facilitate function chaining.

Removing inheritance and using records

In functional programming, there is normally no inheritance (keep a pragmatic attitude about this statement and use inheritance if necessary): we can remove the one using the ValueObject class. We will instead use records that provide equality comparison out of the box.

public record Quantity
{
    public readonly int Value;
    public readonly string Unit;

    public const int MAX_QUANTITY = 100;

    public Quantity(int quantity, string unit)
    {
        if (quantity > MAX_QUANTITY)
            throw new Exception($"A quantity cannot be more than {MAX_QUANTITY}.");

        Value = quantity;
        Unit = unit;
    }

    public Quantity Add(int increment) {
        return new Quantity(Value + increment, Unit);
    }
}

In the previous code, I let the attributes Quantity and Value readonly. If I turned them in {get; init;} properties like this:

public int Value { get; init; }

Then a developer could use the with copy constructor like the following example, thus violating the rule (the invariant) stating than a Quantity cannot be more than 100 because in such a case, the normal positional constructor is not called:

q = q with { Value = 110 }

So you have to be really really careful when using {get; init;} properties.

Behaviors

Now let's have a look to the Add() function. In functional programming, we don't have objects so behavior does not exist, because, in object programming, a behaviour implies modifying the state of an object. And remember, in functional programming, everything is immutable.

So we need to move the Add() function from the record to a static extension class:

public static class QuantityExtensions {
    public static Quantity Add(this Quantity quantity, int increment) {
        return new Quantity(quantity.Value + increment, quantity.Unit);
    }
}

Some may think of Martin Fowler's Anemic Data Model reading this: for me, it is not a problem as long as the methods are named using domain knowledge and as long as the codebase remains well structured.

A ValueObject container

To chain function as studied in the previous part of this series, we need a container. Let's have a look.

Get the code

To follow this article, you will need the ValueObject<T> container in my Grenat.Functional.DDD project repository.

A ValueObject with two states: one valid, one invalid

A classic programming approach leads to the use of exceptions. However, exceptions should only be used to handle exceptional cases. What's more, they are forbidden in functional programming (see honest functions in the first article of this series).

So ValueObject<T> is a two states container:

• A valid state: the inner value of ValueObject<T> is accessible.

• An invalid state: the inner value of ValueObject<T> is unaccessible and only the error causing this invalid state is available.

A static constructor for Quantity

To ensure every one will use the ValueObject<T> container, we will replace the public constructor by a static one that returns a ValueObject<Quantity>:

// Make standard constructor private
private Quantity(int quantity)
{
    Value = quantity;
    Unit = unit;
}

// Use instead a public constructor
public static ValueObject<Quantity> Create(int quantity)
{
    if (quantity > MAX_QUANTITY)
    {
        // The Error class is embeded in Grenat.Functionnal.DDD.
        // An implicit conversion is also defined in the library to convert an Error to an invalid ValueObject<T>.
        return new Error($"Quantity cannot be more than {MAX_QUANTITY}");
    }
    else 
    {
        // An implicit conversion has been defined to convert a T to a valid ValueObject<T>.
        return new Quantity(quantity);
    }
}

We also need to change the Add() extension method accordingly:

public static class QuantityExtensions {
    public static ValueObject<Quantity> Add(this Quantity quantity, int increment) {
        return Quantity.Create(quantity.Value + increment, quantity.Unit);
    }
}

Getting the inner value of ValueObject<T>

Remember the previous article, getting the inner value of a container means that you need to go back to the normal world using a Match. Because a ValueObject<T> has two states, one valid and one invalid, we will use Match() to retrieve the inner value by providing it two functions:

• One for the valid state. The inner value of the ValueObject<T> will be injected into it.

• One for the invalid state. An IEnumerable<T> containing the errors will be injected into it.

var quantity = Quantity.Create(10, "Liters");
var value = quantity.Match(
                Valid: v => v.Value,
                Invalid: e => 0);
Console.WriteLine(value); //10

Chaining functions with Bind()

Now let's move to binding. If necessary, I recommend you have a refresher about Bind reading the previous Article of this series: "The elevated world".

I have defined a Bind() function for ValueObject<T> in Grenat.Functional.DDD. Using it allows us chain calls to other functions like this:

var result = Quantity.Create(10, "Liters")
            .Bind((q) => q.Add(10))
            .Bind((q) => q.Add(30))
            .Match(Valid: v => new { value = v.Value, errors = Enumerable.Empty<Error>()},
                    Invalid: e => new { value = 0, errors = e});

Console.WriteLine(result.value); //50

A superpower of Bind(): easily handling errors

Bind makes function chaining much easier. It also gets rid of all the plumbing needed for handling Error cases, because in case of an error in the execution pipeline, Bind() automatically switches the normal execution path to the error execution path. This will prevent you from writing tons of conditional logic.

Let's take an example using a functional approach:

var resultInError = Quantity.Create(10, "Liters")
                        .Bind((q) => q.Add(10))
                        .Bind((q) => q.Add(100))
                        .Bind((q) => q.Add(10))
                        .Match(Valid: v => new { Value = v.Value, Errors = Enumerable.Empty<Error>()},
                                Invalid: e => new { Value = 0, Errors = e});

Console.WriteLine(resultInError.Errors); //Error { Message = A quantity cannot be more than 100 }

Now let's try to rewrite an equivalent using imperative approaches.

Attempt 1: a pure imperative way, without using a ValueObject<T> container:

Quantity q;
try 
{
    q = new Quantity(10, "Liters");
    q = q.Add(10);
    q = q.Add(100);
    q = q.Add(10);
}
catch (Exception e) 
{
    Console.WriteLine(e);
    q = new Quantity(0,""); //wrote this to avoid the following code that needs quantity to crash
}

Attempt 2: handling a ValueObject<T> container in an imperative way:

var quantity = Quantity.Create(10, "Liters");

if (quantity.IsValid)
{
    quantity = quantity.Value.Add(10);
    if (quantity.IsValid) 
    {
        quantity = quantity.Value.Add(100);
        if (quantity.IsValid)
        {
            quantity = quantity.Value.Add(10);
        }
        else 
        {
            Console.WriteLine(quantity.Errors);
        }
    }
    else
    {
        Console.WriteLine(quantity.Errors);
    }
}
else 
{
    Console.WriteLine(quantity.Errors);
}

So, which approach do you prefer? I think the purely functional approach using Bind is simply the best and the clearest. What's more, we've been using far fewer lines of code.

Summary

• Value Objects are the building blocks of any application made using DDD thinking.

• To create a functional approach of Value Objects:

  • We removed inheritance and we used records.

  • The functional Value Object no longer throws an exception.

  • Behaviors are moved to static extension methods.

  • Constructors return a Value Object wrapped in a ValueObject<T> container. This will make it easier to chain functions and make it easier to write conditional logic with Bind.

  • If ValueObject<T> is invalid, then the encapsulated value is inaccessible thus forcing the programmer to handle the error case.

About the cover image

An aurora near Kiruna in Swedish Lapland. The solar wind particles, very energetic, reached the lower layers of the atmosphere: the bottom part of the aurora was rosy (due to a combination of red - ionized nitrogen - and blue - nitrogen -). This color was perfectly visible to the naked eye.

See it in large size in my portfolio.

In the two previous articles, we talk about the fundamentals of functional programming and functional architecture. But before moving to functional DDD, we need to talk about another fundamental of functional programming: the elevated world.

What is the elevated world?

In functional programming, the elevated world is a world in which objects are wrapped in a container Elevated<T> or, more concisely, E<T>. You unknowingly use the elevated world when you deal with asynchronous programming: Task<T>.

So we can write:

• int -> E<int>

• string -> E<string>

And so on.

What is it for?

The elevated world has a lot of interests. The main one is that it makes it easier to chain functions.

Chaining functions bring out what software does: a succession of operations that transforms data into other data. Halas, too often, we first think about implementation details instead of thinking about a flow: structures, classes, interfaces, inheritance, algorithms, data tables and so many other details in which we drown.

Let's see how the elevated world helps us with functions chaining with a LINQ example. The following code gets the average of the 5 best scores. Look how comprehensive the program is using function chaining:

var scores = new List<int> { 12, 18, 17, 14, 13, 20, 8, 9, 14 };

var averageOf5BestScores = scores.OrderByDescending(x => x)
                                    .Take(5)
                                    .Average();

Console.WriteLine(averageOf5BestScores); //16.6

This chaining works because each function returns a value in the elevated world of enumerable integers: IEnumerable<int>.

Writing functions that chain well

Writing a function that chains well requires 4 criteria:

• It must be pure. If it produces side effects, it will be complicated to chain other functions;

• It must take an input parameter in the elevated world, for example, IEnumerable<T>;

• It must be defined as an extension method of the input value (this IEnumerable<T>);

• And it must return a result in an elevated world (IEnumerable<T>).

Let's take an example using the previous example:

• I define a method TakeTopValuesOrderedByDescending() that extends IEnumerable<T>. It has no side effects.

• It returns an IEnumerable<T> to chain calls of other functions.

public static class IEnumerableExtensions
{
    public static IEnumerable<T> TakeTopValuesOrderedByDescending<T>(this IEnumerable<T> values, int top) 
    {
        return values
                .OrderByDescending(m => m)
                .Take(top);
    }
}

Now I can rewrite the very first example by replacing the calls to OrderByDescending() and Take() with TakeTopValuesSortedByDescending():

var scores = new List<int> { 12, 18, 17, 14, 13, 20, 8, 9, 14 };

var averageOf5BestScores = scores
                            .TakeTopValuesOrderedByDescending(5)
                            .Average();

Console.WriteLine(averageOf5BestScores); //16.6

Working with the normal and the elevated world

During your work, you will have to jump from the normal world to the elevated world and vice-versa.

This is done by 3 types of operations:

• An operation called Return in functional programming, which raises a value from the normal world to the elevated world;

• An operation called Match to move back from the elevated world to the normal world and get the embedded value;

• An operation to chain function calls in the elevated world: Bind, Map or Apply.

Writing our elevated world: Option<T>

Let's take an example and let's write our first elevated world: Option<T>. It is a very useful and very well-known pattern embedded in F# to model the absence of data (instead of using null which is a terrible idea).

A first definition

Option<T> has two possible values: Some and None. Here is its first definition:

public record Option<T>
{
    public readonly bool IsSome;

    private readonly T? _value;

    //a private constructor to force the use of static constructors (see below)
    private Option(T v, bool isSome) => (_value, IsSome) = (v, isSome);
}

Next, we need to write the 3 basic operations described before: elevating to Option<T>, returning from Option<T> and getting its inner value, and a chaining-functions helper Bind() or Map().

Operation 1: elevating a value to Option<T>

To elevate a value t to Option<T>, we will write two functions: Some(T t) and None().

First, we add two static constructors:

internal static Option<T> CreateSome(T v) => new(v, true);
internal static Option<T> CreateNone() => new(default!, false);

But they are not practical to use (Option.CreateSome(value)), that is why I keep them internal. I want to write Some(value). So let's do a small helper static class:

public static class Option
{  
    public static Option<T> Some<T>(T value) => Option<T>.CreateSome(value);

    public static Option<T> None<T>() => Option<T>.CreateNone();
}

Now we have two "Return" functions to elevate a value to Option<T>. Here is how to use them:

//define some value
Option<string> someString = Some("foo");
//define the absence of value, instead of using null
Option<string> none = None<string>();

Operation 2: returning to the normal world

Next, we need to move back to the normal world and read the inner value of Option<T>. We will use a Match function. It unwraps the inner value of Option<T> and fires 2 functions that are set as parameters: one if the value is defined and the other one if it is not.

public R Match<R>(Func<R> None, Func<T, R> Some) => IsSome ? Some(_value!) : None();

Here is how to use it. Important: the returned value of provided functions for Some and None cases must be of the same type (string in this example).

public static string GetOptionValue<T>(Option<T> value)
{
    return value.Match(
            None: () => "Empty",
            Some: (value) => $"{value}");
}

Operation 3: chaining functions in the elevated world

We need a generic mechanism to chain operations in the elevated world. In the world of Option<T>, chaining operations must be done only if the inner value of Option<T> is defined. This will be the purpose of the Bind() function.

It takes 2 parameters :

• A value in the elevated world (Option<T> in our example);

• And a function that operates in the normal world T and returns another value in the world of Option. The returned value wrapped in Option<> can be of another type (R for "result type"): the signature of this function is therefore T => Option<R>.

So here is the definition of Bind() for Option<T>:

public static Option<R> Bind<T, R>(this Option<T> option, Func<T, Option<R>> func)
{
    return option.Match(
                Some: v => func(v),
                None: () => None<R>());
}

What we see is that Bind applies func on the inner value of option only if it exists. Else, the result will be None<R>.

Let's give it a try :

[TestMethod]
public void When_binding_a_AddOne_function_on_some_zero_value_then_the_result_is_one()
{
    var addOne = (int i) => Some(i + 1);
    var sut = Some(0);

    var result = sut.Bind(addOne)
                    .Match(
                            Some: v => v,
                            None: () => 0);

    Assert.AreEqual(1, result);
}

Now let's test the chaining:

[TestMethod]
public void When_binding_three_AddOne_functions_on_some_zero_value_then_the_result_is_three()
{
    var addOne = (int i) => Some(i + 1);
    var sut = Some(0);

    var result = sut.Bind(addOne)
                    .Bind(addOne)
                    .Bind(addOne)
                    .Match(
                            Some: v => v,
                            None: () => 0);

    Assert.AreEqual(3, result);
}

But what if one of the chained functions returns a None because something wrong happened? Well, the final result of the chain will be a None because Bind applies the parameterized function only if the value of Option<T> is Some.

[TestMethod]
public void When_binding_a_function_that_returns_none_then_the_result_is_none()
{
    var addOne = (int i) => Some(i + 1);
    var funcNone = (int i) => None<int>();
    var sut = Some(0);

    var result = sut.Bind(addOne)
                    .Bind(funcNone)
                    .Bind(addOne);

    Assert.IsFalse(result.IsSome);
}

What is great is that Bind uses a "railway" management of problems: if one function in the chain returns a None, then the final result will be None. This mechanism is extremely well explained by Scott Wlaschin here. Managing errors in the domain become then very easy because you don't have to write any conditional logic. We will use it a lot in the application layer of our functional architecture.

What about Map()?

Map() is the same than Bind() instead that it takes as a parameter a function that returns a value in the normal world. As a result, it needs to lift it the elevated world.

Map() for Option<T> looks like this:

public static Option<R> Map<T, R>(this Option<T> option, Func<T, R> func)
{
    return option.Match(
             Some: v => Some(func(v)), // Lifting func's result in the elevated world
             None: () => None<R>());
}

Stick to the elevated world as long as you can

Given the power of the Bind and Map to chain functions and their efficient way of handling errors, I highly recommend sticking to the elevated world for as long as you can.

Get the code

You can get Option<T> and its unit tests in my Grenat.Functional.DDD library here.

Summary

• The elevated world makes it easier to write functions that can be chained together.

• 3 types of operations allow you to work between the elevated world and the real world:

  • A Return operation (Some and None in this example) to raise a value from the normal world to the elevated world.

  • A Match operation to return to the normal world.

  • Operations to chain functions in the elevated world: Bind, Map, Apply.

• Bind and Map are great to manage errors without having to write conditional logic.

• Stay in the elevated world as long as you can to benefit from the power of Bind and Map.

About the cover image

Light pillars on the city of Kiruna in Swedish Lapland. This phenomenon of the polar regions is caused by the reflection of the intense light sources of the cities in the millions of ambient air crystals.

See it in large size on my portfolio.

In part 1 of this series, we understood why an application core should be designed using functional thinking. To achieve this, we need to encapsulate the performing of side effects in external layers: communicating with a message bus, calling APIs… This architecture is called functional architecture. Its goal is to maximize the amount of code written in the functional style.

Let's talk about it and let's start with a schema, I will explain it in the rest of this article:

The functional core

The functional core contains all the business logic: price calculation, discount calculation, input validation... Its role to make decisions and give instructions to the external layers to perform side effects. In the DDD world, all this work is done by aggregates, entities, value objects and services.

Your application heritage resides here, it has to cross the ages and survive any technological change. So:

• Take great care of it by minimizing its technical dependencies and guaranteeing bulletproof reliability,

• Maximize the amount of code that resides in this functional core. You will gain very good reliability and easily achievable automated tests.

Input and output gates

Communication between the functional core and the outside world (API, bus, database, etc.) must be done by using input and output gates. Their roles will be as follows:

• Validating the input data before it enters your functional core,

• Transforming the data that goes out to the outside world to hide implementation details. This is also necessary for security reasons so that confidential data does not leak out.

The outside world

The role of outer layers is to generate side effects: querying a database, sending an email, a message on an application bus... It also contains all the technological dependencies.

Because it produces side effects, uses technological libraries and interacts with other systems or users, this outside world is dangerous. That is why:

• It is important to isolate it in its layer,

• It is important to verify its data before any communication with the functional core thanks to the gates.

Finally, the outer layers must contain no or very little logic: they should be as dumb as possible and must act upon requests of the functional core.

A parallel with clean architecture

Functional architecture and clean architecture (or onion architecture or hexagonal architecture, the principles are the same) are very close:

• The application and domain layers of clean architecture (left image below) correspond to the functional core,

• The infrastructure layer of clean architecture corresponds to the outside world of functional architecture.

Finally, functional architecture is a rigorous clean architecture. Its domain and application layers are written by applying the principles of functional programming: immutability, function composition, etc.

Choose your architecture wisely

Adopting the functional architecture can be overkill for some very simple needs because it requires additional work to manage immutability (see previous article),

Be pragmatic and do not over-engineer your applications. The functional architecture is very well suited for core business areas, complex functionalities or functionalities requiring a high level of reliability.

Summary

• The functional architecture consists of two layers: the functional core and the external world.

• The functional core layer makes the decisions, the outside world layer applies them.

• The functional core can be divided into an application layer and a domain layer like clean architecture.

• Functional architecture can be seen as a rigorous version of clean architecture.

• Choose your architecture pragmatically and do not overdesign your software (YAGNI!).

About the cover image

In 2015, at the very maximum of the Geminid meteor shower. A celestial fireworks happened above the Fuencaliente lighthouse on the Palma island in Canary Islands, on a red airglow background.

See it in large size on my portfolio.

DDD (Domain Driven Design) and functional programming have become increasingly popular to master the complexity of our modern applications.

But how DDD tactical object patterns (entities, aggregates, value objects) apply in functional programming? And how to do it in C# which is an object language? Lots of questions I searched for and found answers to.

I will explain my functional DDD C# journey throughout this series. I wrote a small library for that: Grenat.Functional.DDD. I hope you will learn new useful techniques for your daily work to write less and more sustainable code.

Let's dive in!

Why you should adopt functional thinking

Functional programming is not complicated

A few words first about functional programming. Of course, it is a very large topic. But if we focus on its more important concepts, it is not so complicated. It is just an all-rounder programming style based on functions and on the avoidance of side effects.

Every developer knows what a function is and every developer knows what a side effect is. So everyone can use it. Functional programming is just a rigorous procedural programming style. It is another way to think about our programs, which is why I like to talk about "functional thinking".

Functional thinking is applicable in any language

What I find interesting is that the fundamental principles of functional thinking are simple and can be used in many languages. In an object language like C# or Java, it is even possible to find a subtle balance between object and functional thinking.

Say goodbye to unwanted side effects

Let's go back to side effects. For a refresher, a function does a side effect if it modifies a state outside of its local state. It can be something like sending an email or persisting data in a database. A side effect can also be more localized, like modifying an object attribute or a function parameter.

Here is a simple side effect that can happen everywhere, especially in large teams and large codebases: the reference parameter is modified by accident.

var names = new List<string>() {"Emmanuel", "Justin", "Joe"};

void DoASideEffectByAccident(List<string> names) 
{
    // do something...
    names.Add("Donald");
    // do something...
}

DoASideEffectByAccident(names);

Console.WriteLine(names); // Output : Emmanuel, Justin, Joe, Donald

We will see in the rest of the article how functional thinking will help to avoid this problem.

However, a program has no interest if it does not perform a side effect. So what is functional thinking for? Well, we will use functional thinking fundamentals at the core of our programs while other layers will be in charge of performing side effects.

The fundamentals of functional thinking

Pure functions

A pure function is a function that produces the same result when called multiple times with the same parameter.

This function is not pure because when called several times it will produce a different result:

int NewRandom() {
    var r = new Random();
    return r.Next();
}

The following function is also unpure because it calls the database: there is no guarantee that at its next call you will get the same result.

public static async Task<Price> GetProductPrice(DbContext context, int id)
{
    return await context.Product.AsNoTracking()
                        .Where(p => p.ProductId == id)
                        .Select(p => Price.Create(p.Price))
                        .FirstOrDefaultAsync();
}

And finally, this other RemoveItem() function is also unpure because if modifies one of the Cart's attribute. Also, if it is called multiple times, the result will be different because her behavior depends on a shared state (the Items and CartTotal attributes):

public class Cart
{
    public List<CartItem> Items { get; private set; }
    public int CartTotal { get; private set; }

    public int RemoveItem(int cartItemId, int units) 
    {
        Items.RemoveAll(i => i.ItemId == cartItemId);
        return Items.Sum(i => i.Price);
    }
}

The behavior of a pure function depends exclusively on its input parameter and therefore:

• It doesn't produce side effects,

• It is easily testable,

• It is parallelizable.

Immutability

Immutability is one of the most important principles of functional programming. It requires a "copy on write" discipline, i.e. you have to make a copy of the object before modifying its data.

Avoiding side effects

The biggest advantage of immutability is that it avoids creating accidental side effects. When a developer modifies an existing code, he no longer has to identify all its potential side effects. Combined with pure functions, immutability allows the developer to focus only on the code that he needs to modify. It saves time, energy and avoids accidents.

A simple action is to use immutable collections using a C# immutable list:

var immutableNames = ImmutableList.Create("Emmanuel", "Justin", "Joe");

int DoSomethingWithoutSideEffect(ImmutableList<string> names) {
    // With Immutable Lists, a copy of the modified object is returned when calling the Add function, thus avoiding a side effect.
    var newNames = names.Add("Donald");

    // Do something...
    return result;
}

DoSomethingWithoutSideEffect(immutableNames);

Console.WriteLine(immutableNames); //Output : Emmanuel, Justin, Joe

More predictable code in multi-threaded environments

Immutable code is automatically thread-safe because we can only read the values. And concurrent reads by multiple threads pose no problems.

Honest functions

An honest function (or a total function) is a function that for any value of a starting set matches a value in the destination set.

This function is not honest (it is partial) because it has no matching result in the integer destination set for a negative parameter:

public static int AddOne(int number)
{
    if (number <0) 
        throw new ArgumentException($"{number} cannot be negative.");
    else 
        return number++;
}

Honest functions are less restrictive than pure functions: a function that performs a side effect like an input/output but which in any case returns a value of the declared type in its signature is honest.

However, writing honest functions requires a mindset change: you must forget exceptions and favor tangible results in case of an error. Exceptions should only occur in exceptional cases as its name suggests. In C#, the Fluent Results library is perfectly suited for writing honest functions: it avoids throwing exceptions.

Some other benefits of functional thinking

Make unit testing easier

By creating a maximum of pure and honest functions, we make the writing of automated tests easier: it is enough to compare the function output with what is expected.

On the other hand, if your code base contains procedures that produce side effects, creating automated tests becomes more difficult since:

• You have to test the side effect,

• You may have to mock the class to test an outcoming interaction (with a database for example).

Of course, testing side effects would still be necessary because each application produces side effects. But you have to minimize them to the maximum.

Less code in critical parts of the codebase

In functional programming, we use declarative programming: we write what the program should do. Imperative programming remains however necessary because almost all processors work this way: they are designed to execute sequences of elementary instructions.

For example, SQL is a declarative language. Take the following query:

Select Sum(amount) Order_total from Order 
Inner join OrderLine on OrderLine.Id = Order.Id
Where Order.Id = @OrderId

I did not write all the necessary loops because the declarative statement was translated into a set of imperative statements by the compiler: the execution plan. A similar example could be made with .Net Linq to Objects query: the compiler generates all the imperative code for us.

Here is another example: adding a product in the orchestrating layer of the application (see part 6 of this series). This code deals with all of the error cases without writing any conditional "glue":

var p = await Product.Create(addProductDto.Reference, addProductDto.Name, addProductDto.Price, addProductDto.FamilyId)
        .BindAsync(VerifyProductReference, () => CountProductReferences(addProductDto.Reference))
        .BindAsync(VerifyFamilyId, () => CountFamilyIds(addProductDto.FamilyId))
        .MapAsync(SaveProduct);

In these examples, we wrote very little code which drives to produce fewer bugs. Nevertheless, do not believe that you'll write less code everywhere in your codebase with functional thinking. Some parts of your application will indeed require to write more code, especially to deal with immutability.

What's important is that functional thinking allows you to write less code in the critical parts of your codebase: the domain and application layers (see next post).

Less interfaces boilerplate code

In the object paradigm, developers tend to create too much interfaces. Sometimes to abstract things that will finally have only one implementation. But sometimes we really need to write interfaces to abstract an out-of-process resource like a database. The good news is that we can get rid of most of them using functional thinking: just inject functions.

Let's compare the object and functional approaches to write a repository. Both are perfectly suitable depending on your needs.

Let's begin with the classical object approach:

public interface ICatalogRepository 
{
    public Task<List<Product>> GetProducts();

    public Task SaveProduct(Product product);

    /*...*/
}

Now we need to implement this interface:

public class CatalogRepository : ICatalogRepository
{ 
    public Task<List<Product>> GetProducts() 
    {
        /*...*/
    }

    public Task SaveProduct(Product product)
    {
       /*...*/
    }
}

Eventually, you will have some extra work with your dependency injection tool:

Services.AddScoped<ICatalogRepository, CatalogRepository>();

Then, pass an ICatalogRepository as a parameter in a Save method:

public void async Save(ICatalogRepository catalogRepository, Product product) 
{
    /*Do some verifications before saving product in database...*/
    await catalogRepository.SaveProduct(product);
}

Now, let's switch to a more functional approach. You can write a static function that performs the save in the database :

public static Task SaveProduct(DbContext context, Product product)
{
   /*...*/
}

Then, inject it in a Save method:

public static async void Save(Func<DbContext, Product, Task> SaveProduct, DbContext context, Product product) {
     /*Do some verifications before saving product in database...*/
    await SaveProduct(context, product);
}

As you can see, the functional approach can save you some work: less boilerplate interface code, no dependency injection mechanism to deal with and easier testing with on-the-fly declared lambda functions. Think about it before writing interfaces.

Some drawbacks

Watch out for external libraries

Some libraries may not be compatible with the fundamentals of functional thinking such as immutability. This is particularly the case of EF Core which needs write Therefore, avoid calling external libraries in your functional core as much as possible.

Some additional work to deal with immutability

Since dealing with immutability implies making copies of data structures to modify them, more work has to be done on the constructors:

• Default constructors must be banned,

• Depending on the call context, you may need to create several constructors to take into account the optional parameters,

• It is necessary to check all the invariants in constructors to ensure the created data structure is valid.

Immutability also involves more work in client code: creating a new object to modify it involves more code than directly updating it. This will be especially true for more complex data structures like DDD aggregates.

Immutability also means being constantly vigilant. For an object to be truly immutable, all of its attributes must be immutable. Particular care should be taken with reference types: collections, objects, etc. If one of a class's attributes is mutable then that class is not immutable.

Performance that may be a little worse

Creating a new instance of an object to modify it creates a performance hit, especially on immutable collections in C#. But these problems will only appear if you manipulate large amounts of data or perform complex calculations. In this case, it will be necessary to create optimized code by putting aside immutability.

Summary

• Functional thinking is simple and can be seen as a rigorous procedural programming style. It's a new way to think about our programs.

• Functional thinking is applicable in any language. If it is an object language, it is possible to benefit from both paradigms.

• Functional thinking brings a synergy of benefits to master our complex modern applications.

• Be careful with external libraries that could be incompatible with the functional thinking fundamentals.

• Some functional thinking fundamentals like immutability may require you to write more code, so use it wisely: in your core business areas, on features that require high reliability or in complex features.

About the cover image

Messier 94, the Croc-eye galaxy, is located in the Canes Venatici constellation, about 16 million light-years from us. Its heart is extremely brilliant: it is a starburst galaxy. It means it exhibits an exceptional new star formation rate compared to other galaxies.

See it in large size on my portfolio.

As an introduction, I must quickly talk about my experience. I live in France, and I have two jobs. The first one is CTO and the second one is about my passion: astrophotography.

My work as CTO is quite common. The other, astrophotographer, is not. It is about taking pictures of stars for entire nights: I had to travel the world in search of the most beautiful starry skies. Unfortunately, I have seen the damage that our modern societies inflict on the environment during my adventures. And digital is a big part of that.

I will not change things. But my experience allows me to activate a lever: to ensure that the software we develop is of high quality and that it lasts a long time.

What is sustainability?

Sustainability is officially defined by three pillars of decreasing importance:

1. Environment.

2. Society.

3. Economy.

   

There is no official definition of sustainable software

There is no official definition of sustainable software because it is a complicated topic. And I think those that are found on the Internet focus too much on performance and energy consumption.

In reality, energy consumption is one impact factor amongst others. A special case on one of the most visited website in France Le Monde.fr shows that after several optimizations, only approximately 70 trees are saved per year. It is very good, but we have to admit that software optimization is not a truly efficient lever.

Other factors will harm the environment to a greater extent. One of the biggest is that some modern software only run on recent devices. The old ones will then become obsolete and will go to the trash. Windows 11 is a perfect example.

The other pillars (people, profit) are also forgotten in sustainable software definitions. For example, security and GDPR are related to the social pillar and I did not spot references to them. Yet it is a very important concern of modern computing because our data is shared and centralized in the cloud.

That is why I thought about my own definition of sustainable software.

Implementing sustainability pillars

So, as developers, how can we implement the three pillars of sustainability to create sustainable software? As discussed before, performance and energy consumption are not the only problems. I think we should keep these three principles in mind:

1. Usefulness (environment, society and economy pillars).

2. Security (society and economy pillars).

3. Extensibility (economy pillar).

We can create nested a view of sustainable software principles based on the sustainability pillars:

Let's examine these principles in detail now.

Usefulness

Useful software is the most important principle because it embeds answers to all the pillars of sustainability. Useful software is efficient, ergonomic and compatible with a maximum of networks and hardware, from the oldest to the most recent. This makes our digital equipment last which is the most powerful lever to reduce the impact of digital on the environment. For example, 83% of the total smartphone CO2 emissions will come from manufacture, shipping, and first-year use. The more software is useful and lasts, the less people buy new digital devices, the better it is for the planet.

Useful software can however degrade over time, it is necessary to remain vigilant. Two phenomena need to be monitored:

• The "Feature Creep" phenomenon: software is enriched with features that affect its usefulness.

• The functional debt phenomenon: it is becoming more and more difficult to bring new features to the software while ensuring its current quality.

Useless software is an evil in our industry. A study by consulting firm Standish Group "Modernization" claims that only 20% of software features are used. This value should be handled with care, but it shows the trend.

Security

Security is a very important principle to answer the social pillar, especially today because a lot of our data is stored and shared in the cloud. To implement security in our software, we must think of the CIA cybersecurity triad:

• Confidentiality: it concerns secret data that no one wishes to be made public. Our banking information for example.

• Integrity: only authorized processes should modify our data. A software bug or a vulnerability that leads our data to be changed is a security issue.

• Availability: our data must be available quickly. If our medical data is unavailable due to poor software performance during emergency care, we are in serious trouble.

The security principle is also an answer to the economic pillar: security issues can lead to massive money losses. The famous Equifax data breach cost 1.4 billion dollars to the company.

Extensibility

Extensibility principle is an answer to the economy pillar: poorly extensible software may be phased out because of its rising maintenance costs. Productivity also decreases due to increasing technical debt, which leads to economic losses for companies.

Summary

Sustainable software integrates principles of usefulness, security and extensibility into each decision made all along its lifetime.

This is my vision of software sustainability. Some may not agree, but it is the one that, as a developer, best suits me at the moment. Throughout this blog, I will illustrate my posts using examples made with Microsoft environments (Azure, .Net).

About the cover image

IC 1848 is a pretty nebula located in the Cassiopeia constellation. It has the shape of a heart. The total exposure time is about 30 hours.

See it in large size in my portfolio.