Messages, events and commands

Component: NServiceBus
NuGet Package NServiceBus (3.x)
Standard support for version 3.x of NServiceBus has expired. For more information see our Support Policy.

A message is the unit of communication for NServiceBus. There are two types of messages, commands and events, that capture more of the intent and help NServiceBus enforce messaging best practices. This enforcement is enabled by default, but can be disabled.

A message must be a reference type (class). An attempt to send a message which is a value type (struct) will result in a runtime exception.
CommandEvent
Used to make a request to perform an action.Used to communicate that an action has been performed.
Has one logical owner.Has one logical owner.
Should be sent to the logical owner.Should be published by the logical owner.
Cannot be published.Cannot be sent.
Cannot be subscribed to or unsubscribed from.Can be subscribed to and unsubscribed from.
Can be sent using the gateway.Cannot be sent using the gateway.
In a request and response pattern, reply messages are neither a command nor an event.

Validation

There are checks in place to ensure best practices are followed. Violations of the above guidelines generate the following exceptions:

  • "Pub/Sub is not supported for Commands. They should be sent direct to their logical owner." - this exception is being thrown when attempting to publish a Command or subscribe to/unsubscribe from a Command.
  • "Events can have multiple recipient so they should be published." - this exception will occur when attempting to use 'Send()' to send an event.
  • "Reply is neither supported for Commands nor Events. Commands should be sent to their logical owner using bus.Send and bus. Events should be Published with bus.Publish." - this exception is thrown when attempting to reply with a Command or an Event.
  • "Reply is not supported for Commands. Commands should be sent to their logical owner using bus.Send and bus." - this exception is thrown when one use reply with a Command.
  • "Reply is not supported for Events. Events should be Published with bus.Publish." - this exception will occur when one tries to use reply with an Event.

Designing messages

Messages represent data contracts between endpoints. They should be designed according to the following guidelines.

Messages should:

  • be simple POCO types.
  • be as small as possible.
  • satisfy the Single Responsibility Principle. Types used for other purposes (e.g. domain objects, data access objects, or UI binding objects) should not be used as messages.

Defining messages

Messages can be defined either by interfaces or conventions.

Interfaces

The simplest way to define messages is to use interfaces.

  • NServiceBus.ICommand for a command.
  • NServiceBus.IEvent for an event.
  • NServiceBus.IMessage for any other type of message (e.g. a reply in a request response pattern).
public class MyCommand : ICommand { }

public class MyEvent : IEvent { }

public interface MyEvent : IEvent { }

public class MyMessage : IMessage { }
This approach has some drawbacks, as described in Unobtrusive mode messages.

Conventions

See Conventions.

Related Articles


Last modified