Getting Started

Glossary of messaging terms

A glossary of terms used in distributed systems related to NServiceBus.


A Message is the unit of communication for NServiceBus. Messages are sent and received by endpoints. There are two general types of messages:

  • Command: Used to request that an action should be taken.
  • Event: Used to communicate that some action has occurred.

Message types can be set either using interfaces ICommand and IEvent or via conventions (so-called unobtrusive mode).


The payload of the message is also called the body. It travels between the endpoints in a serialized form (either textual or binary).


Additional information about a message is communicated over the transport in a collection of key-value pairs. Message headers are similar to HTTP headers in the sense that they define how messages should be transmitted and processed. NServiceBus uses headers to implement some of its features. Users can also add custom headers.


An Endpoint is a logical entity that communicates with other Endpoints via messaging. Each Endpoint has an identifying name and contains a collection of Message Handlers and Sagas. An Endpoint can be deployed to a number of machines and environments. Each deployment of an endpoint is an instance.

Endpoint Instance

An Endpoint Instance is a run-time object that allows interaction with the bus. Endpoint Instances can send, receive, and publish messages. It runs associated Message Handlers and Sagas to process incoming messages. An Endpoint Instance has a single Input Queue.


The act of Hosting refers to running an Endpoint Instance in some process. This can be any .NET process, such as a console application, a website, a Windows service, or a container instance. Multiple Endpoint instances can be hosted in a single process.


The Transport is the mechanism that NServiceBus Endpoint Instances use to communicate with each other. NServiceBus supports many different transports in a pluggable manner. For Endpoint Instances to communicate, they need to share a common Transport technology.

Input Queue

Each endpoint instance is assigned a single Input Queue. This queue can be shared among instances of the same Endpoint but never with other Endpoints.

Publish Subscribe

Publish-Subscribe is the interaction of

  • Registering interest in being notified about an event (subscriber).
  • That event being delivered to the endpoint that registered itself (publisher).


A Message Handler (sometimes referred to as a "Handler") is a piece of code that processes a message of a given type. Message handlers are stateless.


A Saga can be thought of as a long-running Handler that handles multiple Messages and shared states. It is the NServiceBus equivalent of a Process Manager pattern.


A Timeout is a message a Saga sends to its future self to indicate the fact that some action needs to be performed. A timeout can contain the state which provides the context for that action.


NServiceBus has retry logic surrounding all calls to user code. This allows failing business code to be retried in a sensible way in order to resolve any interim problems (such as a database server restart). Messages that fail all retries are sent to an error queue for triage for either a retry or discarding.


The Pipeline refers to the series of actions taken when an incoming message is processed and an outgoing message is sent.


A Behavior is a single step in the Pipeline.

Message Property Encryption

NServiceBus has both built-in encryption and extension points to create fully customized encryption models.


Allows forwarding every message successfully processed by an endpoint to a configured queue.


Serialization is the process of converting an in-memory object representing a message into a stream of bytes to transmit it via the Transport. For Endpoint Instances to communicate, they need to share a common serialization technology.


Several NServiceBus features rely on persistent storage to function. This includes Sagas, Timeouts, Gateway, Outbox, and Subscriptions (with transports that do not support Pub/Sub natively).

Dependency injection

NServiceBus relies heavily on Inversion of Control Containers and Dependency Injection to manage services and state.

Assembly Scanning

NServiceBus leverages assembly scanning to implement several features.


NServiceBus has some sensible defaults for logging built-in and for more advanced scenarios, it supports routing log events to an external logging library.


An alternative to Distributed Transactions is to provide exactly-once message processing semantics when accessing user data stored as part of message processing.

Ghost Message

Message handlers that modify business data in a database can run into problems when the messages that are sent become inconsistent with the changes made to business data, resulting in ghost messages or phantom records.


The ability to call the same message handler more than once without causing inconsistent business results.