Print

Returning data from command handlers

This article extends the architectural design of command handlers to allow command handlers to return data.

A few months back I described the command / handler architecture that I (and many others) use to effectively model business operations in a system. Once in a while a question pops up in my mail or at Stackoverflow about returning data from a command.

It seems strange at first to return data from commands, since the whole idea of the Command-query separation is that a function should either return a value or mutate state, but not both. So without any more context, I would respond to such question with: separate the returning of the data from the operation that mutates the state. Execute that command and execute a query after the command has finished.

When we take a closer look at the question however, we will usually see that the data being returned is an Identifier of some sort, which is the result of the creation of some entity in the system. Take a look at the following command:

public class CreateCustomerCommand
{
public string Name { get; set; }
public Address Address { get; set; }
public DateTime? DateOfBirth { get; set; }
}

Since the command will create a new customer, it’s not unlikely for the caller to need the id of the customer, for instance to redirect to another page:

public ActionResult CreateCustomer(
CreateCustomerCommand command)
{
this.handler.Handle(command);
int customerId = [get the customer Id here];
return this.RedirectToAction("Index",
new { id = customerId });
}

Still, do we really want to return values from commands? A few things to note here. First of all, returning values from commands does mean that a command can never be executed asynchronously anymore, something that architectures such as CQRS promote. Besides this, the CreateCustomerCommand seems very CRUDy, and probably doesn’t really fit an architecture like CQRS. In a CQRS like architecture, you are likely to report to your user the message “your request is being processed” or might want to poll until the operation has executed asynchronously.

For the systems I’m working on, for my customers, my fellow developers, and even myself, CQRS is a bridge too far. The idea of having all commands (possibly) execute asynchronously –and CQRS itself- is a real mind shift that I’m currently not willing to make (yet), and I can’t expect other developers to do to. With my current state of mind, it is simply too useful to have commands handlers return data to the caller. So how do we do that?

The answer is actually very simple: Define an ‘output’ property on a command:

public class CreateCustomerCommand
{
public string Name { get; set; }
public Address Address { get; set; }
public DateTime? DateOfBirth { get; set; }

// output property
public int CustomerId { get; internal set; }
}

When a command handler sets this property during the execution, the caller can use it as follows:

public ActionResult CreateCustomer(
CreateCustomerCommand command)
{
this.handler.Handle(command);
int customerId = command.CustomerId;
return this.RedirectToAction("Index",
new { id = customerId });
}

We can set this id from within the command handler:

public class CreateCustomerCommandHandler 
: ICommandHandler<CreateCustomerCommand>
{
IUnitOfWorkFactory<NorthwindUnitOfWork> factory;

public CreateCustomerCommandHandler(
IUnitOfWorkFactory<NorthwindUnitOfWork> factory)
{
this.factory = factory;
}

public void Handle(CreateCustomerCommand command)
{
using (var unitOfWork = this.factory.CreateNew())
{
var customer = new Customer
{
Name = command.Name,
Street = command.Address.Street,
City = command.Address.City,
DateOfBirth = command.DateOfBirth,
};

unitOfWork.Customers.InsertOnSubmit(customer);

unitOfWork.Commit();

// Set the output property.
command.CustomerId = customer.Id;
}
}
}

As you can see, the CustomerId property of the CreateCustomerCommand is set at the end of the Handle method of the handler. This sounds too good to be true, and well… it depends ;-).

When the Customer.Id is generated by the database, the Commit will ensure that the Customer is persisted and will retrieve the auto-generated key and it will become available immediately after the Commit. We can therefore simply set the command’s CustomerId property after calling Commit.

The previous command handler was in complete control over the unit of work. It created that unit of work, it committed that unit of work, and it disposed that unit of work. This is a simple model I effectively used in the past, and I know others are still using this today. Letting the command handler control the unit of work however, has its short comes.

This design works great when commands are small and contain little logic. It starts to fall apart however, when commands get more complex and start to depend on other abstractions that need to run in the same context / unit of work. When the unit of work is controlled by the command handler, it is the handler's responsibility of passing it on to its dependencies, and since those dependencies are already created at the time the handler creates the unit of work, constructor injection is out of the picture. The only thing left is passing the unit of work through method arguments (method injection). Although it doesn’t seem that bad, I worked on a system where we actually did this, but the call stacks were deep and passing around the unit of work from method to method, from class to class was just tedious. To make our lives easier we started creating a new unit of work for some operations, but this actually made things worse, since a single use case / request resulted in multiple unit of works, which sometimes lead to very strange behavior, or even deadlocks.

For this reason, I stepped away from this design and instead I inject a unit of work instance into classes that need it. Though, somebody somewhere in the system must manage the unit of work. This can be solved by registering the unit of work with a Per Thread or Per Web Request lifetime and implementing a command handler decorator that will ensure the unit of work is committed after the handler completed successfully (note that committing the unit of work on the end of the web request is typically a bad idea, since there is no way to tell whether the unit of work should actually be committed at that point). You have to realize that, although simplifying your application code, the complexity is moved into the composition root. The size and complexity of your application must promote this. Although I must admit that once familiar with these types of constructions and configurations of your composition root, you will find it easy to apply in small systems as well.

One note about database generated keys. CQRS models the business around aggregate roots (a DDD concept), and each aggregate root gets a unique key, usually generated as a Guid, which can be generated in .NET. This means that when using CQRS, you will never run into the problem of database generated keys, which is great of course.

Aggregates in DDD are a group of domain objects that belong together. The Aggregate Root is the thing that holds them together. An Order for instance, may have order lines and those order lines cannot live without that order. The order is therefore the aggregate root and has a unique (global) identifier. An order line does not need a (global) identifier (although they might have an local identifier, only known inside the aggregate), since it will never be referenced directly; other aggregates will only reference the order, never the lines. They may need an identitier in your relational database, but you would probably never return them from a command, since they are purely internal to the Aggregate. If such identitier is needed, returned, or referenced from other aggregates, they are probably not part of that aggregate and the system is incorrectly modeled, accordingly to DDD. This also means that the system will have not as many primary keys as a non-DDD system will have. In a normal relational database, each order line will usually get its own auto number primary key. In that case, it will be much more likely to get into performance problems when using Guids. A Guid is 16 bytes (12 bytes bigger than an Int32) and every database index of a certain table will contain the primary key of that table, making each index 12 bytes times the number of records in the table bigger. Disk space is cheap, but I/O isn’t. When doing complex queries over large amounts of data, lowering the amount of I/O is important. And don’t forget the clustered index fragmentation that random Guids cause.

Long story short, you might be in the situation where you don’t use DDD / CQRS, want to return a database generated value from your command handlers, while having a design were command handler don’t control the unit of work. How do we do this?

Since database generated IDs only come available after the data is saved to the database, and committing happens after the handler executed, we need a construct that allows the handlers to execute some code after the commit operation. We can introduce a new abstraction to the system, where command handlers can depend upon, which allows them to register some post-commit operation:

public interface IPostCommitRegistrator
{
event Action Committed;
}

This interface defines a single event, which command handlers can depend upon and register their post commit operation. The previously defined CreateCustomerCommandHandler will now look like this:

public class CreateCustomerCommandHandler 
: ICommandHandler<CreateCustomerCommand>
{
private readonly UnitOfWork unitOfWork;
private readonly IPostCommitRegistrator postCommit;

public CreateCustomerCommandHandler(
UnitOfWork unitOfWork,
IPostCommitRegistrator postCommit)
{
this.unitOfWork = unitOfWork;
this.postCommit= postCommit;
}

public void Handle(CreateCustomerCommand command)
{
var customer = new Customer
{
Name = command.Name,
Street = command.Address.Street,
City = command.Address.City,
DateOfBirth = command.DateOfBirth,
};

this.unitOfWork.Customers.InsertOnSubmit(customer);

// Register an event that will be called after commit.
this.postCommit.Committed += () =>
{
// Set the output property.
command.CustomerId = customer.Id;
};
}
}

This command handler registers a delegate to the IPostCommitRegistrator, which is injected through the constructor (note that you should only inject the IPostCommitRegistrator into a handler that actually needs it).

From the application design, this really is all there’s to it. However, there is some more work to do inside the composition root. For instance, we need an implementation of this IPostCommitRegistrator:

private sealed class PostCommitRegistratorImpl 
: IPostCommitRegistrator
{
public event Action Committed = () => { };

public void ExecuteActions()
{
this.Committed();
}

public void Reset()
{
// Clears the list of actions.
this.Committed = () => { };
}
}

This implementation is very simple. It just implements the Committed event and defines an OnCommitted method, which will be called from the code that manages the transactional behavior of the command handlers. In my previous post I defined an TransactionCommandHandlerDecorator<T>, which allowed executing the commands in a transactional manner. Although we can extend this class to add this post commit behavior, I like my classes to be focused, and have a single responsibility. Let’s define a PostCommitCommandHandlerDecorator<T>, that has the sole responsibility of executing the registered post commit delegates, after a transaction was committed successfully:

private sealed class PostCommitCommandHandlerDecorator<T>
: ICommandHandler<T>
{
private readonly ICommandHandler<T> decorated;
private readonly PostCommitRegistratorImpl registrator;

public PostCommitCommandHandlerDecorator(
ICommandHandler<T> decorated,
PostCommitRegistratorImpl registrator)
{
this.decorated = decorated;
this.registrator = registrator;
}

public void Handle(T command)
{
try
{
this.decorated.Handle(command);

this.registrator.ExecuteActions();
}
finally
{
this.registrator.Reset();
}
}
}

This decorator depends on the PostCommitRegistratorImpl directly and during the Handle method -after the transaction completes successfully- the ExecuteActions method of the PostCommitRegistratorImpl is called. Note that this decorator depends on the PostCommitRegistratorImpl implementation and not on the IPostCommitRegistrator interface. The interface does not implement the ExecuteActions method, and we don’t want it to, since we don’t want any command handler to call that method directly. We do however want this class to be able to execute the registered delegates, so we need it to access the implementation. Since both classes are part of the composition root, this is fine. The application code itself has no notion of the PostCommitRegistratorImpl nor the PostCommitCommandHandlerDecorator<T>.

Our last task is to wire up all the dependencies correctly. This isn’t really difficult, but does need a certain state of mind, since you need to carefully consider the lifestyle of PostCommitRegistratorImpl. Up until this point this article was container agnostic. Here is an example of how to configure this using the Simple Injector:

using SimpleInjector;
using SimpleInjector.Extensions;

container.RegisterManyForOpenGeneric(
typeof(ICommandHandler<>),
typeof(ICommandHandler<>).Assembly);

container.RegisterDecorator(
typeof(ICommandHandler<>),
typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
typeof(ICommandHandler<>),
typeof(PostCommitCommandHandlerDecorator<>));

container.RegisterPerWebRequest<PostCommitRegistratorImpl>();
container.Register<IPostCommitRegistrator>(
() => container.GetInstance<PostCommitRegistratorImpl>());

The previous registration does a few things:

  • First it registers all public ICommandHandler<T> implementations that live in the same assembly as the ICommandHandler<T> does.
  • Next it registers the TransactionCommandHandlerDecorator<T> to be wrapped around each command handler implementation.
  • Next it registers the PostCommitCommandHandlerDecorator<T> to be wrapped around each TransactionCommandHandlerDecorator<T> implementation. It is important that the post commit decorator is wrapped around the transaction decorator, since the system will behave incorrectly when they are decorated the other way around, since that means that the registered delegates would be called before the transaction is committed.
  • The PostCommitRegistratorImpl is registered. Since we want to inject the same instance in both the command handler and the post commit decorator, we can’t use the transient lifestyle, since that will new up a new instance each time it is injected. Using a single instance for the whole application however, is only possible when the application is single-threaded (which can be the case if you run the handlers in a Windows Forms application or a Windows Service). In this case I assume a web application, which is inherently multi-threaded. I therefore register it on a Per Request basis (using the RegisterPerWebRequest extension method).
  • Since the application does not depend on PostCommitRegistratorImpl but on the IPostCommitRegistrator interface, we need to map that interface to the previous registration. This is done by registering a delegate that requests the PostCommitRegistratorImpl. This may look odd, but is an effective way to map multiple interfaces to the same implementation. The delegate is called every time an IPostCommitRegistrator is injected, but since it requests a PostCommitRegistratorImpl, which is registered on a Per Web Request basis, it will always return the same instance for a single request.
Conclusion

Again, one simple abstraction can solve the problem we have effectively. Nice about this design is that it keeps the code of the commands handlers pretty clean, and although not shown, it is easy to write unit tests for this as well.

- .NET General, Architecture, C#, Dependency injection, O/RM, Simple Injector - 17 comments / No trackbacks - §

The code samples on my weblog are colorized using javascript, but you disabled javascript (for my website) on your browser. If you're interested in viewing the posted code snippets in color, please enable javascript.

17 comments:

Very good article on CQRS. I really like your down to earth approach to the architecture. The previous two articles on commands and querying were equally informative.

I will be switching from Autofac to Simple Injector thanks to the ease of setting up configuration (ie. decorators). Really powerful stuff!

I hope more post will be coming soon!
Jakub Konecki - 08 09 12 - 10:42

I would suggest some naming convention over resulting properties (for example, Result***).

Also, why not using this approach for queries? This would allows us not only to return multiple data sets from queries without necessity of creating class for result, but also allows us reusing of decorators between commands and queries.

What do you think?
Michael - 28 11 12 - 09:04

I've given this a lot of thought, but came to the conclusion that they deserve their own abstraction. Commands and queries are two completely separate concepts and therefore need to be handled differently. For instance, queries can never be queued while commands can never be cached.

The amount of code you will save by allowing a single decorator to both wrap queries and commands is minimal. And if there is a lot of code duplication between decorators, you are definitely missing an abstraction anyway. For instance, a ValidationQueryDedocator and a ValidationCommandDecorator should delegate the validation to a IValidator abstraction, instead of doing the validation their selves.

One could argue whether a command should in fact ever return a value. Still, most commands will never return a value. Queries on the other hand always return a value. This difference is so significant that they deserve a their own abstraction. Because queries always return a value, it would be awkward to mix the input and output. It would be awkward for the consumer that calls the query and it would be awkward for the decorator that caches this query.
Steven (URL) - 28 11 12 - 09:55

What decorator can wrap what command/query - it's decided uppon DI setup anyway - so yeah, you can put some inappropriate decorator around query or command but it's a kind of problem like giving wrong database ISession to handler.

Caching is indeed a valid point, but it still can be done with abstraction (cached data provider) which is also allowed handlers to tell the system if their result can be cached or not.

I think if we did follow full CQRS principles (event sourcing, bus, async support, ect.) then we indeed could not mix queries/commands into one abstraction. But I thought if we simplifying or view on archeticture a bit, we could also simplify their abstraction. So did you really found any crucial bonuses that separating query/commands abstractions gives? Because otherwise it's against YAGNI :)
Michael - 28 11 12 - 10:20

The fact that commands and queries have a different purpose should be enough to justify having two abstractions.
Steven (URL) - 28 11 12 - 13:39

First of all I like your approach of your command handling without returning data in your previous article.
But reading this article i don't like the combination of input and output parameters in the command.
It is not a good thing not to separate the "input" and "output" parameters in the command. Now it is very hard to serialise the command over a WCF service without serializing the whole class with all information in both ways.
Further it's not clear which parameter is an input or an output parameter. This is very confusing for the consumer of the commands.
Arien Hartgers - 26 04 13 - 08:14

Arien, what you suggest then? Events? But using events to only call commands inside you own code seems like overkill for me.
Michael - 26 04 13 - 08:50

Arien,

The points you note are valid.

For me it's not a big deal to have both input and output in a command, since the output should hardly ever be more than a generated ID. If you really wish to separate input and output, you can apply the same model for commands as I did in my previous article about queries (but even better of course is to simply not return anything). I think however that the benefits of this separation does not compensate for the extra complexity that defining the output type brings (since you should only return an ID).

The confusion between input and output parameters in the API of the commands can be solved by defining better names for the output properties, such as 'GeneratedCustomerId' or by using a convention to start a name with 'Output...'. Another option is to mark output properties with a special [CommandResult] or [Output] attribute. This communicates the intend of the property clearly.

Marking such property as [Output] is also a good solution when you want to minimize the trafic over the wire. The solution I take in the "SOLID Services" reference architecture application (https://solidservices.codeplex.com/) is to simply send the whole (possibly unchanged) command back over the wire. In the common case, commands should be fairly small and for most applications the overhead would be small enough for you to don't care about this. If your application is a special case where this performance or transport costs actually do matter, you can optimize the communication by using the [Output] attributes to determine which properties to return to the client (if any). I actually took this approach in the initial version of the reference architecture application, but I changed this to returning the whole command (in changeset 94202) to make the model simpler and more appealing to developers. If you look back in the changeset history (https://solidservices.codeplex.com/SourceControl/list/changesets) you can see how this was implemented. It's no rocket science.
Steven (URL) - 26 04 13 - 10:18

How about using 'out' keyword for getting back an Id in synch scenarios ?

this.handler.Handle(command, out customerId);

I came across an article http://epic.tesio.it/doc/manual/command_.. where they claim it to be a good practice.

Also domain logic validation which happens in the command handler which is a part of an application service might throw a custom exception with BrokenRules collection which could be caught by the client (MVC controller -> catch BrokenRulesException and append error list to ModelState)

Is it is safe path ?

Thanks
Dimitri - 30 05 13 - 12:15

Using an out parameter is just obfuscation and has no advantages over having a Handle method with a return value, i.e.:

int customerId = this.handler.Handle(command);

But consequence of a design with an out or return value is that the design of your command handlers will equal that of the Query Handlers (http://www.cuttingedge.it/blogs/steven/pivot/entry.php?id=92).

Such design for queries makes a lot of sense, because all queries return a value. For commands however, such design is rather awkward, since in general, commands should return void anyway. So why should we complicate this part in the design? Besides that, how do we handle the common void case? We can't define a command as ICommand, since C# (and the CLR) do not allow this. We could define our own Void type (something like DbNull) and have an ICommand, but that would still be awkward, and command handler in that case still have to do "return MyVoid.Instance;".

To conclude, don’t do this. Stick to using return properties, or here is another idea: Don't use database generated IDs! That solves the problem completely. Instead let the client generate an ID (most likely a GUID). In this case, since the client creates the ID, they already have that value, and you don't have to return anything. This btw has other advantages, for instance, it allows commands to be executed asynchronously (or queued), without the need for the client to wait.

When using GUIDs, you can either use sequential GUIDs (but in that case the client must know how to generate them) or you will have to defragment your database indexes once in a while (something you should probably be doing anyway).
Steven (URL) - 03 06 13 - 11:42

Steven,

How would you handle an UpdateCustomer method where I wanted to return the updated customer?

My first try is the following, but it looks really cumbersome, especially the repeated query calls

public ActionResult UpdateCustomer(UpdateCustomerCommand command) {
    var customer = this.queryProcessor.Process(
        new FindCustomerByIdQuery(command.CustomerId));
    if (customer == null) return 404...;

    this.handler.Handle(command);

    var updatedCustomer = this.queryProcessor.Process(
        new FindCustomerByIdQuery(command.CustomerId));
    return Json(updatedCustomer);
}

Given that commands are one way, can thery throw exceptions?

If so you could do the following

public ActionResult UpdateCustomer(UpdateCustomerCommand command) {
    try {
        this.handler.Handle(command);
    } catch (CustomerNotFoundException) {
        return 404...;
    }

    var updatedCustomer = this.queryProcessor.Process(new FindCustomerByIdQuery(command.CustomerId));
    return Json(updatedCustomer);
}

However neither way look particular elegant

Any help would be much appreciated, thank you for this great series of articles.

Peter
Peter Leigh - 05 07 13 - 05:58

>> where I wanted to return the updated customer?

Commands should do nothing more than return the id, so if you need that customer after the command has executed, you will need to fetch that customer. An FindCustomerByIdQuery however seems like overhead to me. I'd rather use an IRepository<Customer>.

When using MVC on the other hand, you should redirect after a post instead of returning any data, so in that case you'll never have to fetch that record. I'm not sure what the the rules are when creating a Web API.

>> Given that commands are one way, can thery throw exceptions?

Of course!!!! Any operation that does not deliver or do what it promisses to do should throw an exception. If that command can't update the customer, it should throw an exception. However, if you find yourself implementing many action methods with simple try-catch blocks where you return a custom error message, it becomes time to rethink your design. You might be able to implement a decorator or other mechanism that allows translating certain common exception messages to HTTP response codes. For instance, take a look at this example in the "Highly Maintainable Web Services" reference architecture project: https://solidservices.codeplex.com/Sourc..

For this to work, prevent creating a specific exception per command. In other words, prevent creating CustomerNotFoundException, OrderNotFoundException, OrderLineNotFoundException, CustomerAddressNotFoundException etc. Rather, throw one single KeyNotFoundException for instance and translate this to a HttpStatusCode.NotFound code.
Steven (URL) - 05 07 13 - 09:59

Hi, interessting stuff.
What I currently cannot determine: Where and how to handle checks like 'new Product: Name already exists?'.

Should this be checked within an AddNewProductCommand and this command throws an excepton if the rule is violated? Or should this be checked before the command executes within Controller (asp.net mvc scenario). Or should the controller call a service thats checkes business rules like this and the service executes the command?
At this point i'am undecided whats the best code organizaton... Any (short) hint? Thanks a lot.
meco - 27 07 13 - 11:58

@Meco, there are many possible solutions when implementing validation. You can let the AddNewProductCommandHandler do its own validation, but I personally like to implement validations using an IValidator<T> interface and have an IValidator<AddNewProductCommand> implementation that validates the command by using its values and querying the database.

Although the AddNewProductCommandHandler could than depend on the IValidator<AddNewProductCommand> abstraction, a much nicer approach is to implement an ValidationCommandHandlerDecorator<TCommand> that wraps any command handler and depends on IValidator<TCommand>. An example of such decorator (The ValidationQueryHandlerDecorator) is given in the following article: http://www.cuttingedge.it/blogs/steven/p..
Steven (URL) - 28 07 13 - 22:04

Very good read, I'm starting a new project and looking for a different way to go about things. I really like the Command / Handler pattern, but when it comes to returning Id's / Objects - I have a question. When using entity framework, in your controller say you map from your ViewModel to your Domain entity (I'm planning on using Onion architecture), why not pass in the mapped core domain entity to the command handler? Example:

My entity is in Core.Domain.Customer

public class CreateCustomerCommandHandler
: ICommandHandler<Customer>
{
IUnitOfWorkFactory<NorthwindUnitOfWork> factory;

public CreateCustomerCommandHandler(
IUnitOfWorkFactory<NorthwindUnitOfWork> factory)
{
this.factory = factory;
}

public void Handle(Customer customer)
{
using (var unitOfWork = this.factory.CreateNew())
{

unitOfWork.Customers.InsertOnSubmit(customer);

unitOfWork.Commit();

}
}
}

This should give you the ID back in the controller without specifying extra "Output" parameters. Can you think of any pitfalls to this?
Josh (URL) - 17 10 13 - 05:23

Hi Josh,

Seems to me that what you need is an IRepository<TEntity> instead of an ICommandHandler<TCommand> (the repository pattern, see: http://bit.ly/19cpyX).
Steven (URL) - 17 10 13 - 15:17

Hrmm ... I guess what I am getting at is that I want to move away from using repositories / God like service classes to using the command / query handlers. Do you see a problem with using my actual Domain Entity with the CommandHandler instead of a "UpdateCustomerCommand" which is just a DTO? Since I am using EF, the objects ID is populated by EF and I don't have to worry about returning anything - its on my entity after the Insert.
Josh (URL) - 17 10 13 - 16:34


No trackbacks:

Trackback link:

Please enable javascript to generate a trackback url


  
Remember personal info?

/

Before sending a comment, you have to answer correctly a simple question everyone knows the answer to. This completely baffles automated spam bots.
 

  (Register your username / Log in)

Notify:
Hide email:

Small print: All html tags except <b> and <i> will be removed from your comment. You can make links by just typing the url or mail-address.