Scheduling

The scheduler is a lightweight/non-durable API that helps schedule tasks that need to be executed repeatedly at a specified interval. To benefit from NServiceBus features such as built-in retries and forwarding to the error queue, scheduled tasks should only Send or SendLocal a single message to perform the actual work. One example is to query the database for orders that need some action to be taken and emit individual messages for each order found.

How the scheduler works

The scheduler holds a list of tasks scheduled in a non-durable in-memory dictionary which is scoped per endpoint instance.

When a new scheduled task is created, it is given a unique ID and stored in the endpoint's in-memory dictionary. The ID for the task is sent in a message to the timeout manager, setting the message to be deferred with the specified time interval. When the specified interval has elapsed, the timeouts dispatcher returns the message containing the ID to the endpoint with the scheduled task ID. The endpoint then uses that ID to fetch and invoke the task from its internal list of tasks and executes it.

Example usage

The difference between the following two examples is that in the latter a name is given for the task. The name can be used for logging.

// To send a message every 5 minutes
await endpointInstance.ScheduleEvery(
        timeSpan: TimeSpan.FromMinutes(5),
        task: pipelineContext =>
        {
            // use the pipelineContext parameter to send messages
            var message = new CallLegacySystem();
            return pipelineContext.Send(message);
        });

// Name a schedule task and invoke it every 5 minutes
await endpointInstance.ScheduleEvery(
        timeSpan: TimeSpan.FromMinutes(5),
        name: "MyCustomTask",
        task: pipelineContext =>
        {
            log.Info("Custom Task executed");
            return Task.CompletedTask;
        });

When not to use it

• As soon as the task includes branching logic (if or switch statements) or business logic is added, consider moving to a saga and using saga timeouts instead of a simple message send.
• Sometimes, instead of polling for a certain state using the Scheduler API, it is more appropriate to publish an event when the expected state transition occurs and the necessary action is then taken by a message handler that is subscribed to it.
• When there are requirements that are not currently supported by the Scheduler API. For example, scaling out the tasks, canceling or deleting a scheduled task, or doing a side-by-side deployment of a scheduled task as outlined in the following section.

Current limitations

• Since the scheduler is non-durable, if the process restarts, all scheduled tasks (that are created during the endpoint's startup) are recreated and given new identifiers. Tasks scheduled before the restart that arrive at the endpoint queue will not be found although a message will be written to the log as information.
• Scheduled tasks, once created, cannot be canceled or changed.
• While the task repeat interval can be specified, setting a specific time for the task to run is not supported by the scheduler.
• The task is executed as part of the incoming message pipeline and the max duration is limited by the receive transaction timeout.
• If the time for a task is longer than the configured interval, then the same action may be executed concurrently. If an action is not thread-safe then the action needs to handle any synchronization logic. For example, using a semaphore.
• Since the scheduler uses the queuing mechanism, it does have some side effects on the timelines of scheduled tasks. When a task is scheduled to be run at a given time it may not be executed at exactly that time, instead, it becomes visible at that time and will be executed when it appears in the queue. In most cases, this distinction will have no noticeable effect on the behavior of the scheduling API. However, in high-load systems where the transport does not support native delayed delivery, the fact that a scheduled task is added to the back of the queue can result in a noticeable delay between the "time the task has been requested to be run" and the "time the task is actually executed".
• The Scheduler API does not support scaling out the endpoint or doing a side-by-side deployment of an endpoint. When there are multiple instances of the endpoint that are running on the same machine, while using a non-broker transport such as MSMQ, or when there are scaling out the endpoint instances while using a broker transport such as RabbitMQ, these endpoint instances share the same input queue. Since each endpoint maintains its own created tasks in memory when the specified time is up and the task is queued at the endpoint, any of the endpoint instances that are currently running can dequeue that message. If an endpoint that did not originally create this task happens to dequeue this message in order to execute it, it will not find the task in its list.

Exception handling

When an exception is thrown inside a schedule callback, the exception will be logged as an error and the endpoint will not shutdown.