FractalDataWorks.Services.Scheduling.Abstractions 0.4.0-preview.6

FractalDataWorks.Services.Scheduling.Abstractions

Core abstractions and interfaces for the FractalDataWorks scheduling system, providing cron-based scheduling capabilities with flexible trigger types and execution management.

Overview

This package defines the abstractions for the FractalDataWorks scheduling system, implementing a separation between scheduling (WHEN) and execution (HOW). It provides scheduling capabilities including cron expressions, timezone handling, trigger management, and execution tracking.

Installation

<PackageReference Include="FractalDataWorks.Services.Scheduling.Abstractions" Version="x.x.x" />

Target Framework: netstandard2.0

Key Components

Core Interfaces

IGenericSchedulingService

Main service interface for scheduling operations that applications use. Defined in IGenericSchedulingService.cs.

From IGenericSchedulingService.cs:65-66:

public interface IGenericSchedulingService : IGenericService
{

Key methods include:

• CreateSchedule - Create and register a new schedule
• UpdateSchedule - Update an existing schedule
• DeleteSchedule - Remove a schedule from the system
• PauseSchedule / ResumeSchedule - Control schedule execution
• TriggerSchedule - Trigger immediate execution
• GetSchedule / GetSchedules - Query schedules
• GetScheduleHistory - Retrieve execution history

IGenericScheduler

Core scheduling engine that manages WHEN to trigger process execution. Defined in IGenericScheduler.cs.

From IGenericScheduler.cs:19:

public interface IGenericScheduler : IDisposable, IGenericServiceBase

IGenericSchedule

Interface defining a schedule that specifies WHEN a process should execute. Defined in IGenericSchedule.cs.

From IGenericSchedule.cs:15-64:

public interface IGenericSchedule
{
    string ScheduleId { get; }
    string ScheduleName { get; }
    string ProcessId { get; }
    string CronExpression { get; }
    DateTime? NextExecution { get; }
    bool IsActive { get; }
    string TimeZoneId { get; }
    IReadOnlyDictionary<string, object>? Metadata { get; }
}

IGenericTrigger

Defines trigger configuration for when a schedule should execute. Defined in IGenericTrigger.cs.

From IGenericTrigger.cs:14-68:

public interface IGenericTrigger
{
    string TriggerId { get; }
    string TriggerName { get; }
    string TriggerType { get; }
    IReadOnlyDictionary<string, object> Configuration { get; }
    bool IsEnabled { get; }
    DateTime CreatedUtc { get; }
    DateTime ModifiedUtc { get; }
    IReadOnlyDictionary<string, object>? Metadata { get; }
}

TypeCollection: Trigger Types

Trigger types use the TypeCollection pattern for extensible, type-safe trigger implementations.

TriggerTypeBase

Abstract base class for all trigger type implementations. Defined in TriggerTypeBase.cs.

From TriggerTypeBase.cs:11:

public abstract class TriggerTypeBase : TypeOptionBase<int, TriggerTypeBase>, ITypeOption<int, TriggerTypeBase>, ITriggerType

Key members:

• RequiresSchedule - Whether this trigger type needs schedule persistence
• IsImmediate - Whether this trigger executes immediately upon creation
• CalculateNextExecution() - Calculate the next execution time
• ValidateTrigger() - Validate trigger configuration

TriggerTypes Collection

Source-generated TypeCollection for trigger types. Defined in TriggerTypes.cs.

From TriggerTypes.cs:11-12:

[TypeCollection(typeof(TriggerTypeBase), typeof(ITriggerType), typeof(TriggerTypes))]
public abstract partial class TriggerTypes : TypeCollectionBase<TriggerTypeBase, ITriggerType>

Trigger Type Implementations

Cron Trigger

Cron expression-based scheduling with timezone support. Defined in Cron.cs.

From Cron.cs:45-46:

[TypeOption(typeof(TriggerTypes), "Cron")]
public sealed class Cron : TriggerTypeBase

Configuration keys:

• CronExpression - The cron expression (e.g., "0 9 * * *")
• TimeZoneId - Optional timezone identifier (defaults to UTC)

Interval Trigger

Fixed interval-based scheduling. Defined in Interval.cs.

From Interval.cs:52-53:

[TypeOption(typeof(TriggerTypes), "Interval")]
public sealed class Interval : TriggerTypeBase

Configuration keys:

• IntervalMinutes - Interval between executions in minutes
• StartTime - Optional start time for first execution
• TimeZoneId - Optional timezone identifier

Once Trigger

Single execution at a specified time. Defined in Once.cs.

From Once.cs:52-53:

[TypeOption(typeof(TriggerTypes), "Once")]
public sealed class Once : TriggerTypeBase

Configuration keys:

• StartTime - The specific date/time to execute
• TimeZoneId - Optional timezone identifier

Manual Trigger

Manual trigger only (no automatic scheduling). Defined in Manual.cs.

From Manual.cs:52-53:

[TypeOption(typeof(TriggerTypes), "Manual")]
public sealed class Manual : TriggerTypeBase

Configuration keys:

• Description - Optional description
• RequiredRole - Optional role requirement
• AllowConcurrent - Whether concurrent executions are allowed

Model Classes

Schedule

Default implementation of IGenericSchedule with validation and state management. Defined in Schedule.cs.

From Schedule.cs:58:

public sealed class Schedule : IGenericSchedule

Factory methods from Schedule.cs:252-260:

public static Schedule CreateNew(
    string name,
    string processType,
    object processConfiguration,
    IGenericTrigger trigger,
    string? description = null,
    bool isActive = true,
    IReadOnlyDictionary<string, object>? metadata = null)

And from Schedule.cs:336-348:

public static Schedule Create(
    string id,
    string name,
    string processType,
    object processConfiguration,
    IGenericTrigger trigger,
    DateTime createdAt,
    DateTime updatedAt,
    string? description = null,
    bool isActive = true,
    string? processId = null,
    DateTime? nextExecution = null,
    IReadOnlyDictionary<string, object>? metadata = null)

Trigger

Default implementation of IGenericTrigger with factory methods for each trigger type. Defined in Trigger.cs.

From Trigger.cs:57:

public sealed class Trigger : IGenericTrigger

Factory methods:

From Trigger.cs:243-250:

public static Trigger CreateCron(
    string name,
    string cronExpression,
    string? timeZoneId = null,
    string? description = null,
    bool isEnabled = true,
    IReadOnlyDictionary<string, object>? metadata = null)

From Trigger.cs:332-339:

public static Trigger CreateInterval(
    string name,
    int intervalMinutes,
    int startDelayMinutes = 0,
    string? description = null,
    bool isEnabled = true,
    IReadOnlyDictionary<string, object>? metadata = null)

From Trigger.cs:425-431:

public static Trigger CreateOnce(
    string name,
    DateTime executeAtUtc,
    string? description = null,
    bool isEnabled = true,
    IReadOnlyDictionary<string, object>? metadata = null)

From Trigger.cs:507-514:

public static Trigger CreateManual(
    string name,
    string? description = null,
    string? requiredRole = null,
    bool allowConcurrent = true,
    bool isEnabled = true,
    IReadOnlyDictionary<string, object>? metadata = null)

Dependencies

Package References

• Cronos - Cron expression parsing and calculation
• Microsoft.Extensions.DependencyInjection.Abstractions - DI support
• Microsoft.Extensions.Diagnostics.HealthChecks - Health check integration
• Microsoft.Extensions.Logging.Abstractions - Logging contracts

Project References

• FractalDataWorks.Configuration.Abstractions - Configuration contracts
• FractalDataWorks.Configuration - Configuration implementation
• FractalDataWorks.Services.Execution.Abstractions - Process execution contracts
• FractalDataWorks.Messages - Messaging infrastructure
• FractalDataWorks.Results - Result pattern implementation
• FractalDataWorks.Services.Abstractions - Service abstractions
• FractalDataWorks.Services.Abstractions - ServiceType infrastructure
• FractalDataWorks.Services.SecretManagers.Abstractions - Secret management
• FractalDataWorks.MessageLogging.SourceGenerators - Build-time message logging

Usage Examples

Creating a Cron Trigger

From Trigger.cs:243-285 (factory method usage):

// Create a daily backup trigger at 2 AM Eastern Time
var cronTrigger = Trigger.CreateCron(
    name: "Daily Backup Trigger",
    cronExpression: "0 2 * * *",
    timeZoneId: "America/New_York",
    description: "Automated daily backup trigger"
);

Creating a Schedule

From Schedule.cs:252-292 (factory method usage):

// Create a new schedule with a cron trigger
var schedule = Schedule.CreateNew(
    name: "Daily Database Backup",
    processType: "DatabaseBackup",
    processConfiguration: new { DatabaseName = "Production" },
    trigger: cronTrigger,
    description: "Automated daily backup of production database"
);

// Validate the schedule
var validationResult = schedule.Validate();
if (validationResult.Error)
{
    // Handle validation errors
}

Creating Other Trigger Types

From Trigger.cs:332-380 (interval trigger):

// Every 30 minutes
var intervalTrigger = Trigger.CreateInterval(
    name: "Health Check",
    intervalMinutes: 30,
    description: "Regular health check every 30 minutes"
);

From Trigger.cs:425-461 (once trigger):

// One-time execution
var onceTrigger = Trigger.CreateOnce(
    name: "Maintenance Window",
    executeAtUtc: DateTime.UtcNow.AddHours(24),
    description: "Scheduled maintenance"
);

From Trigger.cs:507-549 (manual trigger):

// Manual execution only
var manualTrigger = Trigger.CreateManual(
    name: "Manual Backup",
    description: "On-demand database backup",
    requiredRole: "Administrator",
    allowConcurrent: false
);

Validating Triggers

From Trigger.cs:593-623:

var trigger = Trigger.CreateCron("Daily Report", "0 9 * * *", "UTC");
var validationResult = trigger.Validate();

if (validationResult.Error)
{
    // Handle validation errors
}

Architecture Notes

Separation of Concerns

The scheduling system follows clear separation:

• Scheduling (WHEN): Handled by IGenericScheduler and trigger types
• Execution (HOW): Handled by IGenericScheduledExecutionHandler
• Service Layer: IGenericSchedulingService provides application-facing API

Cron Expression Features

Using the Cronos library, the system supports:

• Standard 5-field cron expressions (minute precision)
• Extended 6-field cron expressions (second precision)
• Cron descriptors (@yearly, @monthly, @daily, @hourly)
• Timezone-aware calculations with DST handling

TypeCollection Pattern

Trigger types use the TypeCollection pattern for:

• Type-safe trigger type definitions
• Extensible trigger implementations
• Source-generated collections and lookups
• Compile-time validation

Related Packages

• FractalDataWorks.Results - Result pattern
• FractalDataWorks.Services.Abstractions - Service contracts
• FractalDataWorks.Services.Execution.Abstractions - Execution contracts