Assumptions can not be made in a message-driven environment regarding the order of received messages and exactly when they will arrive. While the connection-less nature of messaging prevents a system from consuming resources while waiting, there is usually an upper limit to a waiting period that the business dictates.
The upper wait time is modeled in NServiceBus as a Timeout
:
public class MySaga :
Saga<MySagaData>,
IAmStartedByMessages<Message1>,
IHandleMessages<Message2>,
IHandleTimeouts<MyCustomTimeout>
{
protected override void ConfigureHowToFindSaga(SagaPropertyMapper<MySagaData> mapper)
{
mapper.ConfigureMapping<Message1>(message => message.SomeId)
.ToSaga(sagaData => sagaData.SomeId);
}
public Task Handle(Message1 message, IMessageHandlerContext context)
{
return RequestTimeout<MyCustomTimeout>(context, TimeSpan.FromHours(1));
}
public Task Handle(Message2 message, IMessageHandlerContext context)
{
Data.Message2Arrived = true;
var almostDoneMessage = new AlmostDoneMessage
{
SomeId = Data.SomeId
};
return ReplyToOriginator(context, almostDoneMessage);
}
public Task Timeout(MyCustomTimeout state, IMessageHandlerContext context)
{
if (!Data.Message2Arrived)
{
return ReplyToOriginator(context, new TiredOfWaitingForMessage2());
}
return Task.CompletedTask;
}
}
After calling RequestTimeout
, a timeout message will be persisted and scheduled to run after a specified delay or at specified time.
If a saga does not request a timeout then its corresponding timeout method will never be invoked.
Task
cannot return a null Task. These APIs must return an instance of a Task, i.e. a pending Task or a CompletedTask
, or be marked async
. For extension points that return a Task<T>
, return the value directly (for async methods) or wrap the value in a Task.FromResult(value)
.Timezones and Daylight Saving Time (DST)
A timeout may be requested specifying either a DateTime
or TimeSpan
. When specifying a DateTime
, the Kind
property must be set. If the timeout specifies a time of day, the calculation must take into account any change to or from DST. Timezone and DST conversion may be done using TimeZoneInfo.
.
Requesting multiple timeouts
Multiple timeouts can be requested when processing a message. The individual timeouts can be different types and different timeout durations.
public async Task Handle(Message1 message, IMessageHandlerContext context)
{
await RequestTimeout<MyCustomTimeout>(context, TimeSpan.FromHours(1));
await RequestTimeout<MyCustomTimeout>(context, TimeSpan.FromDays(1));
await RequestTimeout<MyOtherCustomTimeout>(context, TimeSpan.FromSeconds(10));
await RequestTimeout<MyOtherCustomTimeout>(context, TimeSpan.FromMinutes(30));
}
Revoking timeouts
A timeout that has been scheduled cannot be revoked. This means that when the timeout timestamp has elapsed then this timeout message will be queued and then processed.
A timeout is a regular message and once requested, a timeout message can already be in transit or queued. Once that has happened there is no way to revoke (delete) a timeout. It is common to perform a state check in a timeout handler to see if the timeout is still applicable for processing.
Completed Sagas
It is possible for a timeout to be queued after its saga has completed. Because a timeout is tied to a specific saga instance it will be ignored once the saga instance is completed.
Timeout state
The state parameter provides a way to pass state to the Sagas timeout handle method. This is useful when many timeouts of the same "type" that will be active at the same time. One example of this would be to pass in some ID that uniquely identifies the timeout eg: .
. With this state passed to the timeout handler it can now decrement the bonus correctly by looking up the order value from saga state using the provided id.
Using the incoming message as timeout state
As a shortcut an incoming saga message can be re-used as timeout state by passing it to the RequestTimeout
method and making the saga implement IHandleTimeouts
.
Persistence
Some form of Persistence is required to store the timestamp and the state of a timeout.
In order to learn how delayed delivery works in more detail, refer to the Delayed Delivery - How it works section.