Command Functions

Commands and Queries make up the two behaviours of CQRS. Today it’s Command Functions’ turn to go under the microscope. 

Unlike Queries, Commands change the state of a system. The way this works is Command Functions receive a ‘Command Message’ containing information to be used to update the system state. 

In a wider sense, that Command Message could be an HTTP POST payload, or an event in an event store, or one or more parameters in an in-process command function call. This post is concerned with the last of these; the Command Function call.

As mentioned before, Commands intend to change the state of the system. They create a side effect. When discussing the nature of Queries, where we are requesting data, we discovered that Queries shouldn’t have side effects. Commands are different – here we explicitly want side effects. And since we only want side effects, no return value should be required. Commands should return void. Well, usually – we’ll come to that.

Example Commands:

  bool IsActive { set; } // C# property setter called via assignment. Eg. IsActive = true;
  void Update(CustomerRevision revision);
  void SetOrderStatus(OrderStatus newStatus)

In a minority of cases, it does make sense for Commands to return a value:

  Customer Register(CustomerRegistation registration);

The call to register a new customer, if successful, will create entirely new state, that is, a new Customer object with presumably a customer identifier. The caller will want to receive the latest customer so that it can reference the customer when, for example, creating orders for it.

One reason we do not need a return value from a Command Function is for error return values. Error return codes are out. I recommend you avoid them.

So, how does a Command communicate errors back to its caller?

We’ll look at that next time in Command Functions (Part 2).