Command

A command is sent to a peer asking for an action to be performed. The naming convention here is to use an action verb suffixed by Command (ex: SaveMyBusinessObjectCommand).

A command can be sent using the Task<CommandResult> Send(ICommand message) method, and only one peer can be listening to a given command (if multiple peers listen to the same command, Send will throw). In order to handle more complex scenarios where a command could be handled by different peers depending on its content, it is possible to use the Routing features of the Bus.

Command results

Since only one peer is designated to handle a command, it has the ability to reply, and the command sender gets this information back in the CommandResult.

The following data is supplied in CommandResult:

• int ErrorCode
  Every command returns an error code. Success is indicated by an error code of 0 (you may also use the IsSuccess property for convenience). The code 1 designates an unexpected error.

• string ResponseMessage
  This property will return an error message when one is available. This is primarily meant to be displayed to the user.

• object Response
  A general-purpose response object for situations when the command handler needs to return structured data to the caller. Use this sparingly, prefer events where applicable.

On the handler side, several ways are available to supply a result:

• Complete successfully without exception: an implicit result with code 0, no message and no reply will be provided.

• Throw a DomainException from the handler: an error result will be provided. The exception's error code and message will be used. This is the recommended method to return an error code / message.

• Throw a different exception type: an error result with code 1 and no message will be provided (since we cannot assume the message will be user-friendly).

• Call bus.Reply(int errorCode, string message) or bus.Reply(int errorCode): this sets an error code and message which will be used when the handler completes.

• Call bus.Reply(IMessage response): this sets the custom response which will be sent back to the caller. The supplied object needs to be a ProtoBuf contract. This can be combined with the other Reply overloads.