Delayed Delivery

Component: NServiceBus
NuGet Package NServiceBus (7-pre)
This page targets a pre-release version and is subject to change prior to the final release.

The message doesn't have to be dispatched immediately after sending, it can be delivered at a later time if necessary.

Only send operations can be deferred. Publish and reply operations cannot be deferred.

Delaying message dispatching

Delaying a message is done using SendOptions and the DelayDeliveryWith method. This allows to defer the sending of a message to any endpoint. The behavior of delayed handling using DelayDeliveryWith can be seen in Delayed Delivery Sample.

Similar to SendLocal, Defer will also change the message's reply-to address to the endpoint deferring the message. Calling Reply on a deferred message will send the reply to itself.

Using a TimeSpan

Delays delivery of a message for a specified duration.

var sendOptions = new SendOptions();

sendOptions.DelayDeliveryWith(TimeSpan.FromMinutes(30));

await handlerContext.Send(new MessageToBeSentLater(), sendOptions)
    .ConfigureAwait(false);
// OR
await endpoint.Send(new MessageToBeSentLater(), sendOptions)
    .ConfigureAwait(false);

Using a DateTime

Delays delivery of a message until a specified point in time.

var options = new SendOptions();
options.DoNotDeliverBefore(new DateTime(2016, 12, 25));

await handlerContext.Send(new MessageToBeSentLater(), options)
    .ConfigureAwait(false);
// OR
await endpoint.Send(new MessageToBeSentLater(), options)
    .ConfigureAwait(false);

Caveats

Delayed delivery of messages is supported when one of the following requirements are met:

  • The transport supports delayed delivery natively.
  • The Timeout Manager feature is enabled and the endpoint is not a send-only endpoint.

When deferring a message, it is sent to the Timeout Manager requesting it to deliver the message at a later time or deferred by using the transports native capability to defer messages.

The Timeout Manager is enabled by default. However, it is automatically disabled for send-only endpoints and transports that support delayed delivery natively (i.e. Azure Service Bus).
When relying on Timeout Manager, the sending endpoint must be running when the timeout is reached in order for the message to be sent. If the endpoint is not running when the timeout is reached then the message will be sent when the endpoint is next started.
If specifying a negative timeout or a time that is in the past then the message will still be slightly delayed. The message will not be sent until the Timeout Manager has processed the request.

How it works

NServiceBus provides delayed deliver feature for transports that don't have native support for delayed message delivery, i.e. for MSMQ and SQL Server transports. Transports that support delayed message delivery natively don't require persistence. To learn more about NServiceBus delayed message store refer to the Timeout Manager article.

Samples

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

Last modified