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

Writing an event class

In terms of source code, commands and events are both classes derived from Message. Dealing with commands and events through different classes makes the design of the system more logical and simpler overall. Here’s a sample command class:

public class CheckoutCommand : Message
{
public string CartId { get; private set; }
public string CustomerId { get; private set; }

public CheckoutCommand(string cartId, string customerId)
{
CartId = cartId;
CustomerId = customerId;
}
}

Conversely, here’s the layout of an event class.

public class DomainEvent : Message
{
// Common properties
...
}

public class OrderCreatedEvent : DomainEvent
{
public string OrderId { get; private set; }
public string TrackingId { get; private set; }
public string TransactionId { get; private set; }

public OrderCreatedEvent(string orderId, string trackingId, string transactionId)
{
OrderId = orderId;
TrackingId = trackingId;
TransactionId = transactionId;
}
}

As you can see, the structure of event and command classes is nearly the same except for the naming convention. A fundamental guideline for designing domain events is that they should be as specific as possible and clearly reveal intent.

As an example, consider the form through which a customer updates the default credit card he uses in transactions. Should you fire a rather generic CustomerUpdated event? Or is a more specific CreditCardUpdated event preferable? Both options lead to a working solution, but which option works for you should be evident and stand on its own. It depends on the ubiquitous language and the level of granularity you have in place. We believe that a finer granularity here is a significant asset.

We generally recommend that the intent of the event be made clear in the name and all ambiguity be removed. If some ambiguity around a single event surfaces, you’ll probably find that it’s safer to have two distinct events.

Which properties should you have in the base class DomainEvent?

We’d say that at a minimum you want to have a timestamp property that tracks the exact time at which the event was fired. Moreover, you might want to have a property containing the name (or ID) of the user who caused the firing of the event. Another piece of data you might want to have is a version number that handlers can use to determine whether they can or cannot handle the event. The point here is that the definition of an event might change over time. A version number can help in this regard.

The implementation of the version number is completely up to the team. It can be a Version object as well as a string or a number. It can be bound to the application build number, or it can even be referred to the version of the event class:

public class DomainEvent : Message
{
public DateTime TimeStamp { get; private set; }
public DomainEvent()
{
TimeStamp = DateTime.Now;
}
}

An event class should be considered immutable for the simple reason that it represents something that has already happened. Immutable here means that there should be no way to alter the value of properties. The combination of private setters, no write methods, and a plain constructor will do the trick.

Handling commands and events

Commands are managed by a processor that usually is referred to as a command bus. Events are managed by an event bus component. It is not unusual, however, that commands and events are handled by the same bus. Figure 10-3 presents the overall event-based architecture of a CQRS solution. This architecture is more standard and is an alternative to the one we mentioned earlier that was based on the TS pattern.

FIGURE 10-3 The command stack of an event-based CQRS architecture.

Any interaction that takes place in the user interface generates some requests to the system. In an ASP.NET MVC scenario, these requests take the form of controller actions and methods in the application layer. In the application layer, a command is created and pushed to some machinery for actual processing.

The bus component

The command bus holds a list of known business processes that can be triggered by commands. Active instances of such processes can be further advanced by commands. Processing a command can sometimes generate an event within the domain; the generated event is published to the samecommand bus or to a parallel event bus, if any. Processes that handle commands and related events are usually referred to as sagas.

The command bus is a single class that receives messages (requests of executing commands and notifications of events) and finds a way to process them. The bus doesn’t actually do the work itself; instead, it selects a registered handler that can take care of the command or event. Here’s a possible template for a bus class that handles commands and events. We use the interface IHandles as a placeholder for actions. The interface has a single void method:

public interface IHandles
{
void Handle(T message);
}

The bus uses the interface to handle both commands and events:

public class Bus
{
private static readonly Dictionary<Type, Type> SagaStarters =
new Dictionary<Type, Type>();
private static readonly Dictionary<string, object> SagaInstances =
new Dictionary<string, object>();

public static void RegisterSaga<TStartMessage, TSaga>()
{
SagaStarters.Add(typeof(TStartMessage), typeof(TSaga));
}

public static void Send<T>(T message) where T : Message
{
// Publish the event
if (message is IDomainEvent)
{
// Invoke all registered sagas and give each
// a chance to handle the event.
foreach(var saga in SagaInstances)
{
var handler = (IHandles<T>) saga;
if (handler != null)
handler.Handle(message);
}
}

// Check if the message can start one of the registered sagas
if (SagaStarters.ContainsKey(typeof (T)))
{
// Start the saga creating a new instance of the type
var typeOfSaga = SagaStarters[typeof (T)];
var instance = (IHandles<T>) Activator.CreateInstance(typeOfSaga);
instance.Handle(message);

// At this point the saga has been given an ID;
// let's persist the instance to a (memory) dictionary for later use.
var saga = (SagaBase) instance;
SagaInstances.Add(saga.Data.Id, instance);
return;
}

// The message doesn't start any saga.
// Check if the message can be delivered to an existing saga instead
if (SagaInstances.ContainsKey(message.Id))
{
var saga = (IHandles<T>) SagaInstances[message.Id];
saga.Handle(message);

// Saves saga back or remove if completed
if (saga.IsComplete())
SagaInstances.Remove(message.Id);
else
SagaInstances[message.Id] = saga;
}
}
}

The bus has two internal dictionaries: one to map start messages and saga types, and one to track live instances of sagas. In the latter dictionary, you can typically have multiple instances of the same saga type that are bound to different IDs.

The saga component

In general, a saga component looks like a collection of logically related methods and event handlers. Each saga is a component that declares the following information:

A command or event that starts the process associated with the saga

Commands the saga can handle and events the saga is interested in

Whenever the bus receives a command (or an event) that can start a saga, it creates a new saga object. The constructor of the saga generates a unique ID, which is necessary to handle concurrent instances of the same saga. The ID can be a GUID as well as a hash value from the starter command or anything else, like the session ID. Once the saga is created, it executes the command or runs the code that handles the notified event. Executing the command mostly means writing data or executing calculations.

At some point in the lifetime of the saga instance, it might be necessary to send another command to trigger another process or, more likely, fire an event that advances another process. The saga does that by pushing commands and events back to the bus. It might also happen that a saga stops at some point and waits for events to be notified. The concatenation of commands and events keeps the saga live until a completion point is reached. In this regard, you can also think of a saga as a workflow with starting and ending points.

Events raised by sagas pass through the bus, and the bus passes them as messages to whomever subscribed to that event. Raising an event from within the saga requires code like that shown here:

// Raise the PaymentCompleted event
var theEvent = new PaymentCompletedEvent( /* add transaction ID */ );
theEvent.SagaId = message.Cart.Id;
Bus.Send(theEvent);

From the application layer, you invoke the bus as shown in the following example. This example simulates a scenario in which an ASP.NET MVC application is called back from the payment page on a bank service gateway:

public ActionResult CompleteProcessOrder(String transactionId)
{
// Retrieve shopping cart from session state
var cart = RetrieveCurrentShoppingCart();

// Prepare and queue a Process-Order command
var command = new ProcessOrderCommand(transactionId, cart.CartId);
Bus.Send(command);

// Refresh view: in doing so, results of previous command might be captured, if ready.
return RedirectToAction(“Done”);
}

As you might have noticed, the command bus doesn’t return a response. This is not coincidental. The refresh of the user interface—wherever necessary—is left to a subsequent read command that queries data from any place—storage, cache, or whatever—where output is expected to be.

What we mostly want from a command bus is to decouple the application layer from the domain services. Doing so opens up new opportunities, such as handling domain service calls asynchronously. Other scenarios that the command bus can simplify are adding cross-cutting filters along the way, such as transactions, logging, and general injection points for optional logic. In any of these cases, all you need to do is change the command-bus class—no changes are required to the application layer and domain services.