Getting Started

Timeout Manager

Component: NServiceBus
NuGet Package: NServiceBus (7.x)

NServiceBus provides a delayed-delivery implementation for transports that don't support it natively. All transports except MSMQ support delayed delivery natively.

The delayed-delivery feature uses a built-in persistent store and requires using NServiceBus persistence. The timeout data is stored in three different locations at various stages of processing: [endpoint_queue_name].Timeouts queue, timeouts storage location specific for the chosen persistence (e.g. dedicated table or document type) and [endpoint_queue_name].TimeoutsDipatcher queue. The queues are automatically created by NServiceBus installers when setting up the endpoint.

Storing timeout messages

When NServiceBus detects that an outgoing message should be delayed, the message is routed to the [endpoint_queue_name].Timeouts queue instead of directly to the destination queue. The ultimate destination address is preserved in a header.

The [endpoint_queue_name].Timeouts queue is monitored by an internal receiver. The receiver picks up timeout messages and stores them using the selected NServiceBus persistence.

Delayed messages are stored for the specified delay time, using persistance implementation specified in the configuration:

endpointConfiguration.UsePersistence<InMemoryPersistence, StorageType.Timeouts>();

Retrieving expired timeouts

NServiceBus periodically retrieves expiring timeouts from persistence. When a timeout expires, then a message with that timeout ID is sent to the [endpoint_queue_name].TimeoutsDipatcher queue. That queue is monitored by NServiceBus internal receiver. When the receiver picks up a message, it looks up the corresponding timeout in the storage. If it finds it, it dispatches the timeout message to the destination queue.

Handling of persistence errors

If there are any connection problems with the timeout storage then NServiceBus waits for 2 minutes (by default) to allow the storage to come back online. If the problem is not resolved within that time frame, then a critical error is raised.

The default wait time can be changed:

    timeToWait: TimeSpan.FromMinutes(5));

When this happens the following critical error message will be raised:

Repeated failures when fetching timeouts from storage, endpoint will be terminated.

If the NServiceBus.Host is used, the host will execute a fail-fast as documented in the default critical error behavior for the NServiceBus.Host.

Migrating timeouts to native delayed delivery

If a persistence that supports native delayed delivery is used, and the system still contains timeouts that were scheduled using the timeout manager, use the timeout migration tool to migrate these timeouts to the native-delay delivery implementation.


  • Delayed Delivery
    A simple ordering system that defers handling or delivery of a message.

Related Articles