Microsoft .NET Architecting Applications for the Enterprise, Second Edition (2014)

Part III: Supporting architectures

Chapter 11. Implementing CQRS

Computers are useless. They can only give you answers.

—Pablo Picasso

The fundamental aspect of a CQRS solution is the neat separation between the command stack and query stack. This means that each stack is designed separately; such a distinct design potentially can lead to having two distinct domain layers and even two distinct databases.

At the end of the day, there are several different flavors of CQRS.

There are CQRS implementations in which the read domain layer is nearly empty and consists only of plain SQL queries run against the database and data-transfer objects used to carry data up to the presentation layer. In other implementations, you have a read domain model that, overall, looks like a subset of a full domain model and a full domain model for the command stack where most of the business logic is contained. The command stack can be lightweight too and sometimes result from a basic implementation of the Transaction Script pattern. In this case, you have no domain layer whatsoever.

More likely, though, the command stack of a CQRS architecture is based on a command bus and handles events on top of a domain model and a database. If two databases exist—one to store the state of the application, and one to contain data in a format highly optimized for reading—then in some way the overall architecture should include a trigger—mostly events—that keeps the databases in sync and updates the read database whenever something is written.

In the end, CQRS is an architectural point. The benefits of the architecture that we listed in Chapter 10, “Introducing CQRS,” apply as long as you keep the query and command stacks distinct. In this chapter, we’ll first review a few possible CQRS implementations and then proceed with extending the sample application with a CQRS implementation where distinct stacks are used for querying and issuing commands.

CQRS implementations

CQRS doesn’t mandate any design choice. Even though the idea of CQRS is often associated with the idea of domain models and Domain-Driven Design (DDD), actually CQRS has just one principle: keep the command and query stacks segregated. Such a core principle can be implemented at least in a couple of ways. One consists of a plain and simple separation of stacks; the other consists of designing the business logic through commands and events.

We feel that a plain and simple CQRS approach is a scenario that often gets overshadowed by the use of command buses and events. Yet it delivers all the architectural benefits of CQRS in terms of simplified design and scalability

Plain and simple CQRS

The architectural benefits of CQRS—primarily the potential for scalability and greatly simplified handling of complex business scenarios—can be delivered even without an explicit focus on domain modeling. As mentioned in Chapter 10, CQRS is not a top-level architectural pattern, but it works beautifully within a bounded context. In a given bounded context, you identify the ideal pattern to express the business logic you have and the ideal pattern to represent any data behind it that gets moved toward the presentation layer for display purposes.

That’s all of it—you have two distinct stacks to be maintained and operated separately. Let’s review the options you have in case you don’t use domain-modeling techniques and the Domain Model pattern.

Transaction script for the command stack

In Chapter 7, “The mythical business layer,” we mentioned the Transaction Script pattern as one of the simplest, but not less effective, patterns to handle business logic. The Transaction Script pattern pushes a task-based vision of the business logic. In this regard, it works very well within a stack that focuses only on the execution of commands.

As Andrea experienced in a couple of projects—especially if you’re called to help a group of corporate developers finalize a project—you might not want to start using architecture that demands significant development skills. The risk of failing, or just experiencing analysis/paralysis, is too high. Conversely, the command/query separation will deliver the simplicity and scalability that you need.

As a pattern, Transaction Script doesn’t make huge demands of developers—it basically recommends they write methods on classes that focus on a task. By carefully choosing names for those methods and classes that closely mirror the language of the business, well, you’re surprisingly halfway done.

In a Transaction Script implementation, you have nothing as complex as command processors or domain models. All you have is a screen with command buttons and a method executing requested actions. Each action ends with some database writes. Input data travels from screens down to the methods as plain data-transfer objects (DTOs). All of this is simple and effective, and the reason it is so simple is because the command stack is kept separate from the read stack.

Data-transfer objects for the query stack

In CQRS, the query stack should be as simple as possible and use the simplest technology that could possibly work. In the scenario we are considering, you don’t need (or just don’t want) a full-fledged data model for the read stack. You return data to the upper layers via data-transfer objects—typically, view model objects if you’re using ASP.NET MVC. How do you fill those objects with data?

A common approach consists of calling an ad hoc layer from the application layer that wraps up the database context. The application layer essentially sees a read layer with ad hoc query methods that return any of the following:

Data-transfer objects that the application layer will later assemble in view model objects for the presentation layer to display

Data-transfer objects that are already view model objects ready for the presentation layer to display

The first scenario is seldom practical; the second is very convenient. The first approach entails using a tool like AutoMapper, or similar handwritten code, that just maps data from database models to memory object models. The real issue here is not the use of extra code and the processing power required by a tool like AutoMapper; instead, the issue is related to design. In a CQRS scenario, the presence of an object model in the query stack is sometimes just the sign that some of the complexity of the read domain model can be moved to an additional bounded context.

Having the read stack return direct view model objects is the essence of what we referred to as a layered expression tree (LET) in the previous chapter. With LET, view model objects are arranged on the fly in the body of a highly idiomatic LINQ query.

In this simple implementation of CQRS, the read stack is based on a simple data-access layer that just performs queries. Based on the available skills and attitude of the developers, you can code this read layer on top of Entity Framework and LINQ using a LET approach to populate data-transfer objects on the fly. In this case, the read layer internally uses a database context object, except that the database context is not publicly visible outside the read layer. If you don’t use Entity Framework and LINQ, the read layer can simply consist of plain ADO.NET or SQL queries and ad hoc data types to bring data back to the client. If you’re using an ASP.NET Web Forms front end, using DataSets to carry data might even be an option.

Single database

Depending on the real complexity of the business scenario, in general you can have CQRS with a single database shared by the command and query stacks, as well as distinct databases that are each managed by stacks autonomously. That mostly depends on the complexity (specifically, the nesting level) of the queries you need to execute.

In the case of a shared database, you typically share the database context between command and read stacks, paying attention to keeping the context private in the read stack. In the read stack, you can use code like that shown here:

public class ReadStack
{
private CommandStackDatabase _context;
public ReadStack()
{
_ context = new CommandStackDatabase();
}

public OrderDto GetById(int orderId)
{
// Use _context to make the query
// and fill the expected DTO
}
}

If, for query performance reasons, you decide to maintain a separate database, you’ll need to have a separate table mapping and a separate database context.

CQRS with command architecture

As more and more people started using CQRS, it became obvious that CQRS is particularly well suited to being coupled with a command-driven strategy and events. By using commands and a command bus, you can split the steps performed in an application service into multiple commands and events sent to the bus.

Orchestrating commands in the command stack

Organizing use-cases and business logic via commands has a number of benefits:

It makes it easy to map commands to the steps of real business processes. At the end of the day, commands are applied because they exist in the ubiquitous language.

You can even draw a flowchart out of a process and discuss that with a domain expert.

It makes far easier to render particularly complex pieces of business logic with events generated by actions that, in turn, generate other domain events.

When you start reasoning in terms of commands, you start feeling the need for another element: events. The execution of a command might generate an event that should be processed by any number of registered handlers. Commands and events go together and represent the real essence of CQRS.

One database or two

When you have two models—one for the command stack and one for the query stack—you need to distinguish whether or not each model refers to its own database. Things are easy to manage if you have distinct databases and rely on architecture like that shown in Figure 11-1.

FIGURE 11-1 CQRS architecture with distinct models and distinct databases.

When distinct databases are used to persist the state of the application and for serving the needs of presentation, you need to have something in between the two that ensures synchronization and consistent data. This is generally accomplished in one of two ways. It can be a scheduled job that operates on the write database periodically and copies data to other tables. It can also be an in-process handler that fires after the termination of each command and either synchronously or asynchronously creates read views, which can be relational tables, OLAP cubes or, why not, tabular data.

When the two stacks share the same database and you have models on both sides, you need to manage two database contexts and apply different mappings. You end up with classes analogous to the classes shown next. These two classes belong to different class libraries:

public class CommandModelDatabase : DbContext
{
...
}
public class ReadModelDatabase : IQueryModelDatabase
{
...
}

The former database context class inherits directly from Entity Framework’s DbContext class. The latter class wraps an instance of DbContext and implements a custom interface—arbitrarily named IQueryModelDatabase. The interface serves the purpose of restricting the DbContextinterface to just a few queryable collections so that the SaveChanges method, which enables changes to the underlying database, is hidden from view.

The database class for the command model also needs to override OnModelCreating to map the content of the database to the physical classes in their own model:

public class CommandModelDatabase : DbContext
{
protected override void OnModelCreating(DbModelBuilder modelBuilder)
{ ... }
...
}

There are a couple of remarks to make here. First, when implementing the read database class, you might want to choose composition over inheritance. Instead of inheriting from DbContext, you can simply create an internal instance. In this way, you prevent undesirable casts to DbContextsomewhere in the code. Second, the name of the class should closely reflect the actual language of the business. Quite simply, this could be Database, indicating (as in the business language) the common name for the container of the business information.

Implementing a query stack

Let’s have a closer look at a CQRS implementation that has two distinct models on top of a single database and uses commands for the organization of the business logic.

Creating a read façade

The essence of CQRS is that, as an architect, you mentally separate queries against the back end from actions that you need to write. You should plan to have separate projects for the query and command parts, and you can even have different teams as well. A read façade consists of two main components: a data model and a database context to read data and materialize elements in the domain.

The query model

As mentioned, most of the time you won’t have an object model in the query side. If you have one, however, here’s more about how to write it. The data model of the query stack has the same structure of the domain model we devised for the entire domain in Chapter 8, “Introducing the domain model,” and Chapter 9, “Implementing the domain model.” It’s the same type of collection of related classes except that the classes are fewer and simpler because they focus only on data and behavior that pertains to rendering queried data.

The read-only domain model is a class library project. Figure 11-2 offers an interior view of the class library project for the sample application.

FIGURE 11-2 The QueryModel class library project.

The Order class in the read model, for example, doesn’t have any behavior and looks like a mere container of data:

public class Order
{
protected Order()
{
}
public int OrderId { get; set; }
public ICollection<OrderItem> Items { get; set; }
public Money Total { get; set; }
public OrderState State { get; set; }
public DateTime Date { get; set; }
}

The OrderItem class is nearly the same as in a full domain-model implementation. Also, the Product and Customer classes are, in our example, nearly the same except that they now lack behavior. Another difference is that in the Orders folder of the full domain model, you find a lot more classes, like OrderPaymentConfirmation, that now belong to the command stack.

The read database context

Once you have a domain model, you also have the problem of materializing instances of the classes. Entity Framework does most of the work for you. If you use Code First, as in the example, you access the database using a class derived from DbContext:

public class QueryModelDatabase : DbContext
{
public QueryModelDatabase() : base(“naa4e-11”)
{
...
}
...
}

The DbContext class provides full, read/write access to the database. To secure the read model and eradicate any chance of allowing write access to the database, you might want to use a private instance of DbContext and implement an interface to close the class. TheQueryModelDatabase class is implemented in a new class library that implements the persistence layer for the read layer. In the example, we call it IBuyStuff.QueryModel.Persistence:

public class QueryModelDatabase : IQueryModelDatabase
{
private DbContext _context;
public QueryModelDatabase()
{
_context = new DbContext(“naa4e-11”);
_products = base.Set<Product>();
_orders = base.Set<Order>();
}
...
}

The interface called IQueryModelDatabase just lists the collections of interest so that coders of the query stack are given access only to the data they need for read-only operations:

public interface IQueryModelDatabase
{
IQueryable<Order> Orders { get; }
IQueryable<Product> Products { get; }
}

In the segment of the sample application implemented so far, there’s no function that queries customers: subsequently, there’s no need to have the Customers collection in the public interface of the database context. The QueryModelDatabase class in the end represents the database to the application’s eyes and should expose only data that the application is interested in.

Packaging data for callers

Another difference you might note in a CQRS scenario is that the collections exposed as part of the database context return IQueryable. Returning IQueryable is not strictly required, but it does help in a few ways, as we discussed in Chapter 10.

Creating LET expressions

Here’s the full source code of the database context class in the query stack:

public class QueryModelDatabase : IQueryModelDatabase
{
private DbContext_context;
public QueryModelDatabase()
{
_context = new DbContext(“naa4e-11”);
_products = base.Set<Product>();
_orders = base.Set<Order>();
}

private readonly DbSet<Order> _orders = null;
private readonly DbSet<Product> _products = null;

public IQueryable<Order> Orders
{
get { return this._orders; }
}
public IQueryable<Product> Products
{
get { return _products; }
}
}

Hiding DbContext and exposing table collections as IQueryable removes the risk of finding the SaveChanges method available at some point. In addition, an IQueryable object is just what its type name says—a queryable collection of data. This enables you to write queries as shown here:

using (var db = new QueryModelDatabase())
{
var queryable = from o in db.Orders
.Include(“Items”)
.Include(“Details.Product”)
where o.OrderId == orderId
select new OrderFoundViewModel
{
Id = o.OrderId,
State = o.State.ToString(),
Total = o.Total,
OrderDate = o.Date,
Details = o.Items
};
try
{
return queryable.First();
}
catch (InvalidOperationException)
{
return new OrderFoundViewModel();
}
}

The code just rewrites the basic query we considered in one of the use-cases of the sample application in past chapters. The actual projection of data is specified at the last minute, right in the application layer. In this way, you can move around IQueryable objects and compile and run the query just when you are going to fill up view model objects. Doing so, also saves you from creating and maintaining a bunch of data-transfer objects.