This separation ensures your scheduler remains decoupled and testable.

2. Core

Contains the main engine classes:

• JobScheduler: Central class managing job lifecycles and execution loops. Uses DI to resolve job instances scoped per execution.
• JobRunner: Handles execution of jobs applying configured policies.
• JobContext: Carries execution metadata and state for each job run.
• JobDescriptor: Holds metadata such as job ID, type, schedule, policy, and custom metadata.
• JobResult: Represents the outcome of a job execution, including success or failure details.

3. Jobs

Predefined job types like:

• RecurringJob: Jobs scheduled to run repeatedly on a defined interval.
• OneTimeJob: Jobs scheduled to run once.

You can extend and create your own job types based on IJob.

⏰ Scheduling Intervals and Calendar Considerations

This framework provides convenient extension methods to specify recurring job intervals:

• EverySeconds(int seconds)
• EveryMinutes(int minutes)
• EveryHours(int hours)
• EveryDays(int days)
• EveryWeeks(int weeks)
• EveryMonths(int months) (approximate)
• EveryYears(int years) (approximate)

Important:

For EveryMonths and EveryYears, the scheduling uses a fixed TimeSpan approximation:

• Months are treated as 30 days each.
• Years are treated as 365 days each.

This means the actual calendar variation (months of 28-31 days, leap years) is not accounted for.

TimeSpan represents a fixed duration and does not natively support calendar-aware intervals. Therefore, using these methods schedules jobs at approximately these intervals, which is usually acceptable for many scenarios but not suitable when precise calendar dates/times are critical (e.g., running on the 1st day of each month).

If your use case requires precise calendar scheduling — accounting for variable month lengths or leap years — a different scheduling logic must be implemented, such as calculating the next run date explicitly using calendar-aware APIs (e.g., DateTime.AddMonths(), DateTime.AddYears()).

4. Builders

Fluent API classes and extension methods to build and configure jobs cleanly, for example:

• .EveryMinutes(int) to define recurring schedules.
• .WithSimpleRetry() to add a retry policy with default settings.

5. Policies

Execution policies control how jobs are run:

• RetryPolicy: Retries job execution upon failure, configurable by attempts and delay.
• TimeoutPolicy: Cancels jobs running longer than a specified time.
• CompositePolicy: Enables composing multiple policies for complex behaviors (e.g., retry with timeout).

Policies implement IJobPolicy and wrap job executions, enforcing constraints or behaviors.

6. Stores

Implementations of IJobStore. The default:

• InMemoryJobStore: Stores job descriptors in-memory for simplicity. Can be replaced with database-backed stores.

7. Extensions

Helpers for integrating the scheduler with the .NET DI and Hosting ecosystem, including extension methods to register scheduler services and start the scheduler when the host runs.

Core Concepts and Interfaces in Detail

IJob

The fundamental unit of work.

• ExecuteAsync contains the logic your job performs.
• The JobContext provides metadata like job ID and user-defined info.
• Cancellation support is built-in via CancellationToken.

IJobScheduler

Manages jobs and their execution lifecycle:

• Register adds jobs to the scheduler.
• StartAsync launches all scheduled jobs asynchronously.
• StopAsync requests cancellation and graceful shutdown.

IJobPolicy

Defines how jobs are executed beyond just calling ExecuteAsync:

Allows behaviors like retrying, timing out, logging, or other cross-cutting concerns without modifying job code.

IJobStore

Storage abstraction for job metadata:

Allows persisting job schedules and metadata, decoupling scheduling logic from persistence.

Defining and Registering Jobs

Jobs are defined as classes implementing IJob. For example:

Register the job with the scheduler using the fluent builder API:

Scheduling Models

• RecurringJob: Runs on a fixed interval (e.g., every 5 minutes).
• OneTimeJob: Runs only once at the next scheduling opportunity.

Both job types can be extended or customized.

Execution Policies

RetryPolicy

Retries job execution on failure.

TimeoutPolicy

Cancels job execution after a timeout period.

CompositePolicy

Combine multiple policies for advanced behavior.

Dependency Injection & Scoped Execution

The scheduler resolves job instances from the DI container, creating a new scope for each execution. This allows using scoped services inside jobs (e.g., DbContext). Internally, this is done via IServiceScopeFactory.CreateScope() to ensure clean scope lifetimes.

Integration with Microsoft.Extensions.Hosting

Designed to integrate naturally with IHost:

• Register scheduler and jobs in ConfigureServices.
• Start scheduler in StartAsync or via extension method.
• Use host’s lifetime and cancellation handling for graceful shutdown.

Example:

Extensibility

• Add custom job policies by implementing IJobPolicy.
• Create new job stores by implementing IJobStore to persist to database or distributed caches.
• Define custom job types for special scheduling or execution needs.
• Extend builders with your own fluent API methods.

Typical Use Cases

• Batch processing pipelines
• Scheduled data cleanup or archival
• Email or notification dispatchers
• Legacy system background jobs modernization
• Microservice background tasks with retry and timeout control

Troubleshooting & Tips

• Job never runs? Ensure you call StartAsync() after registering jobs.
• Scoped services not resolving? Make sure you use DI scopes properly; the scheduler creates a scope per job execution.
• Job stuck or long-running? Use TimeoutPolicy to limit execution time.
• Multiple policies? Use CompositePolicy to combine retry and timeout logically.

Contributing

Contributions are welcome! Please follow the usual GitHub flow:

1. Fork the repo
2. Create a descriptive branch
3. Write tests and update docs
4. Submit a PR for review