Interface IDispatchScheduler
Defines the contract for scheduling message dispatch operations with support for both one-time and recurring execution patterns.
public interface IDispatchScheduler
- Extension Methods
Remarks
The dispatch scheduler is a fundamental component for time-based message processing in distributed systems, enabling deferred execution, periodic tasks, and complex scheduling scenarios. It provides flexibility for various temporal messaging patterns while maintaining reliability and scalability.
Scheduling Patterns:
The scheduler supports multiple execution patterns:
- One-time scheduling for delayed message processing.
- Cron-based recurring schedules for complex timing requirements.
- Interval-based recurring schedules for simple periodic tasks.
- Timezone-aware scheduling for global distributed systems.
Reliability Features:
Implementations should provide:
- Persistent schedule storage to survive system restarts.
- Missed execution handling for system downtime scenarios.
- Duplicate execution prevention through idempotency mechanisms.
- Monitoring and observability for scheduled job tracking.
Scalability Considerations:
The scheduler should be designed for:
- High-volume scheduling with efficient storage and retrieval.
- Distributed execution across multiple nodes.
- Load balancing for scheduled job processing.
- Graceful degradation under high load conditions.
Methods
ScheduleOnceAsync<TMessage>(DateTimeOffset, TMessage, CancellationToken)
Schedules a message for one-time dispatch at the specified future time.
Task ScheduleOnceAsync<TMessage>(DateTimeOffset executeAtUtc, TMessage message, CancellationToken cancellationToken) where TMessage : class
Parameters
executeAtUtcDateTimeOffsetThe UTC timestamp when the message should be dispatched. Must be in the future.
messageTMessageThe message instance to dispatch at the scheduled time. Cannot be null.
cancellationTokenCancellationTokenToken to observe for cancellation requests during the scheduling operation.
Returns
- Task
A task representing the asynchronous scheduling operation.
Type Parameters
TMessageThe message type to schedule. Must be a reference type to support serialization.
Remarks
One-time scheduling is ideal for scenarios such as:
Use Cases:
- Delayed notification delivery (e.g., reminder emails after registration).
- Timeout handling for long-running processes.
- Scheduled data processing tasks (e.g., report generation).
- Deferred cleanup operations after resource usage.
Execution Guarantees:
The message will be dispatched approximately at the specified time, subject to:
- System clock accuracy and scheduler polling intervals
- Load conditions and processing capacity at execution time
- Network latency and message broker availability
Error Handling:
If scheduling fails, the operation will throw an exception. If execution fails at the scheduled time, the behavior depends on the configured retry policies and dead letter handling strategies.
Exceptions
- ArgumentNullException
Thrown when message is null.
- ArgumentException
Thrown when executeAtUtc is in the past.
- OperationCanceledException
Thrown when the operation is cancelled.
ScheduleRecurringAsync<TMessage>(string, CronRecurrenceProfile, TMessage, CancellationToken)
Schedules cron work using the configured default zone and an explicit transition profile.
Task ScheduleRecurringAsync<TMessage>(string cronExpression, CronRecurrenceProfile profile, TMessage message, CancellationToken cancellationToken) where TMessage : class
Parameters
cronExpressionstringThe cron expression.
profileCronRecurrenceProfileThe explicitly selected supported transition declaration.
messageTMessageThe message to persist.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
The scheduling operation.
Type Parameters
TMessageThe message type.
Remarks
The resolved installed zone and primitive profile pair are persisted; no implicit transition-zone default is chosen.
ScheduleRecurringAsync<TMessage>(string, TimeZoneInfo, CronRecurrenceProfile, TMessage, CancellationToken)
Schedules cron work using an installed named zone and explicit transition profile.
Task ScheduleRecurringAsync<TMessage>(string cronExpression, TimeZoneInfo timeZone, CronRecurrenceProfile profile, TMessage message, CancellationToken cancellationToken) where TMessage : class
Parameters
cronExpressionstringThe cron expression.
timeZoneTimeZoneInfoAn installed timezone that can be resolved from its identifier after restart.
profileCronRecurrenceProfileThe explicitly selected supported transition declaration.
messageTMessageThe message to persist.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
The scheduling operation.
Type Parameters
TMessageThe message type.
Remarks
Custom timezone identifiers cannot roundtrip through the persisted row and are rejected. Existing overloads without a profile remain valid only for installed transition-free zones. Adding this member is an intentional source break for custom scheduler implementations.
ScheduleRecurringAsync<TMessage>(string, TMessage, CancellationToken)
Schedules a message for recurring dispatch based on a cron expression schedule.
Task ScheduleRecurringAsync<TMessage>(string cronExpression, TMessage message, CancellationToken cancellationToken) where TMessage : class
Parameters
cronExpressionstringThe cron expression defining the execution schedule. Must be a valid cron format.
messageTMessageThe message instance template to dispatch on each scheduled execution. Cannot be null.
cancellationTokenCancellationTokenToken to observe for cancellation requests during the scheduling operation.
Returns
- Task
A task representing the asynchronous scheduling operation.
Type Parameters
TMessageThe message type to schedule. Must be a reference type to support serialization.
Remarks
Cron-based scheduling provides powerful flexibility for complex timing requirements:
Cron Expression Support:
Standard cron format: "* * * * * *" (seconds, minutes, hours, day of month, month, day of week).
- "0 0 12 * * ?" - Daily at noon.
- "0 0/15 * * * ?" - Every 15 minutes.
- "0 0 9 * * MON-FRI" - Weekdays at 9 AM.
- "0 0 0 1 * ?" - First day of each month.
Advanced Features:
Implementations may support:
- Timezone-aware execution for global systems
- Missed execution policies for system downtime handling
- Maximum execution count limits for finite recurring schedules
- Dynamic schedule modification during runtime
Message Templating:
The provided message serves as a template. Each execution may create a new message instance with updated timestamps or execution-specific data.
Exceptions
- ArgumentNullException
Thrown when cronExpression or message is null.
- ArgumentException
Thrown when cronExpression is invalid or malformed.
- OperationCanceledException
Thrown when the operation is cancelled.
ScheduleRecurringAsync<TMessage>(TimeSpan, TMessage, CancellationToken)
Schedules a message for recurring dispatch at regular time intervals.
Task ScheduleRecurringAsync<TMessage>(TimeSpan interval, TMessage message, CancellationToken cancellationToken) where TMessage : class
Parameters
intervalTimeSpanThe time interval between consecutive message dispatches. Must be positive.
messageTMessageThe message instance template to dispatch on each scheduled execution. Cannot be null.
cancellationTokenCancellationTokenToken to observe for cancellation requests during the scheduling operation.
Returns
- Task
A task representing the asynchronous scheduling operation.
Type Parameters
TMessageThe message type to schedule. Must be a reference type to support serialization.
Remarks
Interval-based scheduling provides simple, predictable recurring execution:
Interval Patterns:
Common interval scheduling patterns include:
- Health checks every 30 seconds: TimeSpan.FromSeconds(30).
- Data synchronization every 5 minutes: TimeSpan.FromMinutes(5).
- Daily report generation: TimeSpan.FromDays(1).
- Hourly cleanup tasks: TimeSpan.FromHours(1).
Execution Timing:
The first execution occurs after the specified interval from the scheduling time. Subsequent executions are scheduled based on the completion time of the previous execution, preventing overlap and accumulation of delayed executions.
Performance Considerations:
Very short intervals (seconds or less) may impact system performance. Consider the processing time of the message and system capacity when selecting intervals for high-frequency recurring schedules.
Exceptions
- ArgumentNullException
Thrown when message is null.
- ArgumentOutOfRangeException
Thrown when interval is zero or negative.
- OperationCanceledException
Thrown when the operation is cancelled.