The message doesn't have to be dispatched immediately after sending, it can be delivered at a later time if necessary.
HandleCurrentMessageLater() method was primarily used to defer messages when using Versions 2.x and below, before the Defer functionality was introduced in Versions 3 and above. While this API is still supported in Versions 6 and below, there are significant caveats in using this API.
- Calling this method would create a copy of the message that has the same identifier, header, and body. This message would then be put at the end of the queue. The endpoint will eventually pick up this message once all the other messages in its queue have been processed. To make this work, the message pipeline will not abort which means any business transaction that's part of calling this method will also get committed.
- If the endpoint's queue is empty, or the condition to put the message back into the queue is incorrect, the message goes back into the queue immediately causing the endpoint to process the same message without any delay. This behavior can cause an endless loop which will manifest itself as a high system resource utilization by the endpoint.
Delaying a message is done using
SendOptions and the
DelayDeliveryWith method. This allows to defer the actual sending of a message to any endpoint. The behavior of delayed handling using
DelayDeliveryWith can be seen in Delayed Delivery Sample.
Deferwill also change the message's reply-to address to the endpoint deferring the message. Calling
Replyon a deferred message will send the reply to itself.
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);
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);
Delayed delivery of messages is supported when the one 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.
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.