DDD & CQRS & Event Sourcing. Part 3: Test Domain Model

Before we start, I recommend checking my previous post where I described designing a domain model with events and which benefits it brings for business and engineers.

Let’s start with the basic class for domain model, let’s call it Aggregate (you could find more about this keyword in DDD here):

public abstract class Aggregate
{
public Guid Id { get; private set; }
private readonly IList<object> _events = new List<object>();

public ICollection<object> DequeueEvents()
{
    var events = _events.ToList();
    _events.Clear();
    return events;
}

private void Enqueue(object @event)
{
    _events.Add(@event);
}

protected void Process(object @event)
{
    Type thisType = GetType();
    if (thisType == null) throw new NotSupportedException($"Current this type is null!");
    
    MethodInfo methodInfo = thisType.GetMethod("Apply",  BindingFlags.NonPublic | BindingFlags.Instance, Type.DefaultBinder, new [] { @event.GetType()}, null );
    if (methodInfo == null) throw new NotSupportedException($"Missing handler for event {@event.GetType().Name}");
    
    try
    {
        methodInfo.Invoke(this, new[] { @event } );
    }
    catch(TargetInvocationException ex)
    {
        ExceptionDispatchInfo.Capture(ex.InnerException).Throw();
    }
    Enqueue(@event);
}
}

As you could see, we have 3 main methods here:

  • Enqueue – simply add a new event to private event collection
  • Dequeue – returns the private event collection and clean the queue, so Aggregate event collection could not be changed in any way from outside.
  • Process – Try to find and call a proper method Apply (by method parameter type) and add anew event to the private event collection.

Also you could see private _events variable for storing events and Id property, which is common for every Aggregate object.

So our specific Aggregate will look like this:

public class User: Aggregate
{
public string Email { get; private set; }

public User(Guid id, string email) => Process(new Events.V1.UserCreated(userId:id, email: email ));

public void ChangeEmail(string userEmail) => Process(new Events.V1.UserEmailChanged(userId: Id, email: userEmail));

private void Apply(Events.V1.UserCreated @event)
{
    Id = @event.UserId;
    SetUserEmail(@event.Email);
}

private void Apply(Events.V1.UserEmailChanged @event) => SetUserEmail(@event.Email);

private void SetUserEmail(string email)
{
    email = email?.Trim();
    CheckNullOrEmpty(email, "Email");
    CheckMaxLength(50, email, "Email");
    CheckIsMatch(Constants.EmailTemplate, email, "Email");
    Email = email;
}
}

* For the simplicity of the example, I’ve omitted implementation details of methods CheckNullOrEmpty, CheckMaxLength, and CheckIsMatch. Anyway, if you are interested, you could find it in Github Repo here.

User domain model contains:

  • Email property (in addition to Id property from Aggregate class). Please be sure it has a private setter
  • SetUserEmail – a method for set and check if the email is correct
  • 2 private Apply methods for changing the internal state of the Domain Model
  • Public constructor
  • public ChangeEmail method for changing the email property

So when are speaking about the testing, we could check several things in the domain model:

  • It has a proper state – eg. User has not empty id and email
  • It generates a proper event – e.g. User generates UserCreated Event
  • Generated event has a proper state – UserCreated Event contains User Id and Email

Let’s see an example of such tests. I’m using Xunit, but you could use any test framework you like:

public class UserCreateTests
{
private readonly Domain.User _createdUser;
private readonly (Guid Id, string Password, string Email) _userData;

public UserCreateTests()
{
    _userData = (Id: Guid.NewGuid(), Password: "Testing123!", Email: "test@email.com");
}

[Fact]
public void ShouldBeCreatedWithCorrectData()
{
    Assert.NotNull(_createdUser);
    Assert.Equal(_userData.Id, _createdUser.Id);
    Assert.Equal(_userData.Email, _createdUser.Email);
}

[Fact]
public void ShouldGenerateUserCreatedEvent()
{
    var events = _createdUser.DequeueEvents();
    Assert.Single(events);
    Assert.Equal(typeof(Events.V1.UserCreated), events.Last().GetType());
}

[Fact]
public void UserCreatedEventShouldContainsCorrectData()
{
    var @event = (Events.V1.UserCreated) _createdUser.DequeueEvents().Last();
    Assert.Equal(_createdUser.Id, @event.UserId);
    Assert.Equal(_userData.Email, @event.Email);
}
}

Firstly, ShouldBeCreatedWithCorrectData checks if the User object is in a valid state after creation. Next, there are 2 tests for the events: ShouldGenerateUserCreatedEvent – checks if the event which has been generated has an expected type, and UserCreatedEventShouldContainsCorrectData checks if this event contains correct data.

As you could see, there is no big difference between unit testing regular objects, and those which are using Events for building their state. I hope this article helped you to understand better the philosophy of Event Sourcing. In the next post, I will describe the persistence of the aggregate using the Marten library. CU 🙂

The latest code base version of the project could be found on Github Org Page.

Always remember about IQueryable when using Expressions in LINQ!

Today I’ve faced unexpected behavior during querying data and JSON deserialization while playing with Marten library which uses PostgreSQL Database as storage. So let’s imagine we have a very dummy 2 classes, one for saving data (in JSON format) and one class for the projection (as a response of some Web API for instance):

Origin class for data storing:

public class User
{
    private User() { }

    public User(int id, string name)
    {
        Id = id;
        Name = name;
        Status = "Pending";
    }

    public int Id { get; private set; }
    public string Name { get; private set; }
    public string Status { get; private set; }
}

Projection class

public class ReadOnlyUser
{
    public string Name { get; set; }
    public string Status { get; set; }
}

So as you see, the User class has private setters and due to MSDN Deserialization behavior, JSON Serializer ignores read-only properties. This means that this code will always create a User instance with Status Pending

var stringData = "{\"Id\": \"1\", \"Status\": \"Active\",\"Name\": \"John\"}";

var stream = new MemoryStream(Encoding.ASCII.GetBytes(stringData));
var textReader = new JsonTextReader(new StreamReader(stream));

var user = new JsonSerializer().Deserialize<User>(textReader);
Result: 

Output object:
User Id: 1 
User Name: John 
User Status: Pending

So if we follow the example above, making a projection from such class, will produce the ReadOnlyUser which also will have a Status Pending:

 var stringArrayData = "[{\"Id\": \"1\", \"Status\": \"Active\",\"Name\": \"John\"}]";
 JsonSerializer serializer = new JsonSerializer();

 var stream = new MemoryStream(Encoding.ASCII.GetBytes(stringArrayData));
 var reader = new JsonTextReader(new StreamReader(stream));

 var user = serializer
   .Deserialize<IEnumerable<User>>(reader)
   .Where(usr => usr.Id == "1")
   .Select(usr => new ReadOnlyUser {Name=usr.Name, Status=usr.Status})
   .FirstOrDefault();

 Console.WriteLine($"\r\nOutput object:\r\nUser Name: {user.Name} \r\nUser Status: {user.Status}");
Result:

Output object:
User Name: John 
User Status: Pending

But what if we are not querying from a string variable, but rather from the database? Most probably instead of IEnumerable, IQueryable interface will be used.

In a nutshell, IQueryable brings 1 huge benefit – it knows how to execute expressions on special data sources. (For instance Where statement will be implemented in the database, not on the memory side)

So, coming back to the previous example, this code will also return User with Status Pending, won’t it?

return await _session.Query<User>() //Returns IQueryable<User> from db
   .Where(usr => usr.Id == "1")
   .Select(usr => new ReadOnlyUser {Name=usr.Name, Status=usr.Status})
   .FirstOrDefaultAsync();
Result:

Output object:
User Name: John 
User Status: Active
Me at that moment

So how did it happen, why Status is Active if the User has a private setter on that field?

In the first example, as we used IEnumerable, all of the operations are processed in our App memory. The order of commands was like that:

  1. Deserialize the JSON to IEnumerable list of Users (by using the only 1 public constructor which set Status to Pending without possibility to set it to Active because of private setter)
  2. Use Where statement to filter the Users with Id = “1”
  3. Use the Select projection for creating a new ReadOnlyUser

In the example with an IQueryable interface, steps 1 and 2 were “outsourced” to the database. So commands look so:

  1. Find by Object Type a proper table from which data should be fetched and create a query like “Select * from User”
  2. Add Where the statement “Where Id = ‘1’ ” to the query from step 1
  3. Execute a query in the database and return the result as a JSON object
  4. Use JsonSerializer for deserialization from JSON to ReadOnlyUser

So as you see, in the second scenario, many steps executed on the database side, but in that particular case, we gain even more profit because we could omit the limitation of Newtonsoft.Json of ignoring read-only fields during deserialization. In fact, we are not creating a User object but just go directly to the creation of ReadOnlyUser projection.

Please be aware, that every implementation of an IQueryable interface has its own rules of converting command and using expression tree. So before relying on “outsourcing processing”, just spend a few minutes to check what exactly will be executed.

DDD & CQRS & Event Sourcing. Part 1: Creating a basic domain model

This is the very first post in a series about using DDD (Domain Driven Design), CQRS (Command Query Responsibility Segregation), and Event Sourcing. I’m going to create a small project, which will use the above-mentioned approaches for solving some real-life scenarios. Before we start, I want to underline, that this posts series among the code project will be created for presentational purposes only. That means, that the business challenges which will be handled here could be solved without any above described practices. At this point, I’m not sure how far and deep this will go, so I will start with very simple and naive examples. It is always better to go in direction of complication, rather than simplification.

I’ve not decided so far what problem this project will solve, but I’m sure that we will need registered users for it. So let’s start with a User Service.

First of all, we have to create a User Entity class with some basic properties

Entity – an object that is not defined by its attributes, but rather by a thread of continuity and its identity.

    public class User
    {
        public string FirstName { get; private set; }
        public string LastName { get; private set; }
        public string Email { get; private set; }
        public string Status { get; private set; }
        
        public User(Guid id, string firstName, string lastName, string email)
        {
            FirstName = firstName;
            Id = id;
            LastName = lastName;
            Email = email;
            Status = UserStatus.Awaiting;
        }

        public static class UserStatus
        {
            public const string Awaiting = "AWAITING";
            public const string Confirmed = "CONFIRMED";
        }
    }

As you could see above, all properties have a private setter. In such a way, we could guarantee, that entity will be created with all necessary information and will not be in a non-valid state (for example User without FirstName).

We could check if all necessary parameters are valid in the constructor.

   public class User
    {
        public string FirstName { get; private set; }
        public string LastName { get; private set; }
        public string Email { get; private set; }
        public string Status { get; set; }
        
        public User(Guid id, string firstName, string lastName, string email)
        {
            CheckNullOrEmpty(firstName, nameof(firstName));
            FirstName = firstName;

            CheckNullOrEmpty(lastName, nameof(lastName));
            LastName = lastName;

            CheckNullOrEmpty(id, nameof(id));
            Id = id;

            CheckNullOrEmpty(email, nameof(email));
            Email = email;

            Status = UserStatus.Awaiting;
        }

        private void CheckNullOrEmpty(string paramValue, string paramName)
        {
            if (string.IsNullOrWhiteSpace(paramValue))
                throw new ArgumentException($"{paramName} could not be null or empty");
        }

...

I believe that now you have a question “So if properties have private setters, how could change their value?”. Very reasonable one, the answer is that we are going to create methods, which will describe the business perspective of that operations. For example, we are going to create a method, which will change the first and last names. This method will check if it is not empty and also that it does not break the business requirement of max length 100 characters:

...

public void ChangeName(string firstName, string lastName)
{
    CheckNullOrEmpty(firstName, nameof(firstName));
    CheckMaxLength(100, firstName, nameof(firstName))
    FirstName = firstName;

    CheckNullOrEmpty(lastName, nameof(lastName));
    CheckMaxLength(100, lastName, nameof(lastName))
    LastName = lastName;
}

private void CheckMaxLength(int maxLength, string paramValue, string paramName)
{
    if (paramValue.Length > maxLength)
        throw new ArgumentException($"{paramName} could not be longer the {maxLength} characters");
}

...

After that, we could reuse this method in a constructor, to be sure, that our Entity has a valid state during the creation and change of the name properties:

...

public User(Guid id, string firstName, string lastName, string email)
{
    ChangeName(firstName, lastName);

    CheckNullOrEmpty(id, nameof(id));
    Id = id;

    CheckNullOrEmpty(email, nameof(email));
    Email = email;

    Status = UserStatus.Awaiting;
}

...

The ChangeEmail method also should be implemented (with some email regex etc), but I’m going to omit that for simplicity for now. The important thing is that the User Entity will not have a ChangeId method, because it would break the business requirement and the User just could not change its own identification number. So in a such way, we guarantee that Entity will always be in a valid state.

Below you could find a potential example of usage of such Entity:

...

public void ExampleOfUsage()
{
    var user = new User(Guid.NewGuid(), "John", "Doe", "john.doe@email.com");
    
    //We also could change user name or email if we want
    //But there is not way to change the Id of the user, 
    //because Id has private setter and entity doesn't have ChangeId method
    user.ChangeName("Barbra", "Streisand");
    user.ChangeEmail("barbra.streisand@email.com");

    // Also we could check the user status, which has been set to Awaiting,
    // as the Entity has been created in a valid s
    Console.WriteLine(user.Status)
}

...

So now we have a basic Domain Entity, which ensures a valid state and encapsulates business logic inside.

The last but not least, if you an interested to go deeper into the topic of DDD, which we touched on today (in a very very superficial way) I would like to recommend a few resources, which could be useful for a deeper understanding of key concepts like Value Objects, Bounded Context, Aggregates, etc. :

The latest code base version of the project could be found on Github Org Page.

In the next post, we will get familiar with the Events, and how we could use them in Entities.