ToolWheel.Extensions.JobManager.Abstractions 1.0.0-preview6

ToolWheel.Extensions.JobManager.Abstractions

Public API, contracts and DTOs for the ToolWheel Job Manager. This package contains no implementations � consumers and extension packages reference these abstractions.

Package Info

Core Interfaces

IJob

Describes a registered job � an immutable identifier, the MethodInfo to invoke and optional metadata.

public interface IJob
{
    string Id { get; init; }
    MethodInfo TargetMethod { get; init; }
    object? TargetObject { get; init; }
    string Name { get; }
    string Description { get; }
    bool Enabled { get; }
    bool UseSingletonInstance { get; }
    ILogger? JobLogger { get; }
}

IJobTask

Runtime handle for a single execution of a job.

public interface IJobTask
{
    IJob Job { get; }
    string Id { get; }
    JobTaskStatusEnum Status { get; }
    CancellationTokenSource CancellationToken { get; }
    Task? Task { get; }
    object? Result { get; }
    IReadOnlyCollection<JobTaskJournalEntry> Journal { get; }
}

JobTaskStatusEnum values: Pending, Running, Success, Canceled, Failed, NotReady.

IJobService

Central service for registering, querying and executing jobs.

public interface IJobService
{
    IJob Add(IJobDescription jobDescription);
    IJob? FindById(string jobId);
    IJob ReadById(string jobId);
    IEnumerable<IJob> ReadAll();
    bool Remove(IJob job);
    ValueTask<IJobTask> ExecuteAsync(IJob job, CancellationToken cancellationToken = default);
}

After a job is registered, Add calls IJobManagerFeature.Apply on every feature attached to the IJobDescription. This is the unified hook for extension packages to register job-specific configuration (triggers, retry policies, �) both at startup and at runtime.

IJobTaskService

Manages the lifecycle of IJobTask instances at runtime.

public interface IJobTaskService
{
    ValueTask<IJobTask> ExecuteAsync(IJob job, CancellationToken cancellationToken = default);
    void Remove(IJobTask jobTask);
    IEnumerable<IJobTask> ReadAll();
    IEnumerable<IJobTask> ReadByJob(IJob job);
    IEnumerable<IJobTask> ReadByJob(IJob job, params JobTaskStatusEnum[] status);
    Task CancelAllAndWaitAsync(CancellationToken cancellationToken = default);
}

CancelAllAndWaitAsync signals cancellation on all tracked tasks and awaits their completion � used during graceful shutdown.

Configuration API

IJobDescriptionCollection

Typed collection with extension methods for convenient job registration:

// Explicit ID + delegate
collection.Add("my-job", worker.DoWork)
    .Name("My Job")
    .Description("Does the work")
    .Enabled();

// Auto-generated ID
collection.Add(worker.DoWork).Name("My Job");

// Expression � method resolved via reflection, ID auto-generated
collection.Add<MyWorker>(w => w.DoWork).Name("Expression Job");

// Expression with explicit ID
collection.Add<MyWorker>("my-job", w => (Delegate)w.DoWork).Name("Expression Job");

IJobDescriptionBuilder

Fluent builder for configuring a single job description:

collection.Add("job-1", handler.Run)
    .Id("custom-id")          // override the job ID
    .Name("Custom Name")
    .Description("Processes items")
    .Enabled()                // set Enabled = true
    .Disabled()               // set Enabled = false
    .AsSingleton()            // reuse the same target instance
    .WithLogger(myLogger)     // attach a per-job logger
    .WithFeature<MyFeature>(f => f.Setting = true);  // attach an extension feature

IJobManagerConfigurationBuilder

Top-level builder used inside AddJobManager(configure => �):

services.AddJobManager(configure =>
{
    configure
        .ConfigureJobs(jobs => { /* add jobs */ })
        .AddExecutionCondition<MyCondition>()
        .AddExecutionConditionController<MyController>()
        .AddMiddleware<MyMiddleware>()
        .ConfigureServices(svc => svc.AddSingleton<IMyService, MyService>())
        .ConfigureService(ServiceLifetime.Singleton, (sp, cfg) => new MyService(cfg));

    configure.SetFeature(new MyFeature());
    var feature = configure.GetFeature<MyFeature>();
});

Extensibility Interfaces

IJobManagerFeature

Base interface for feature objects attached to job descriptions or the configuration builder. Override Apply to self-register job-specific data with the appropriate runtime service when IJobService.Add is called.

public interface IJobManagerFeature
{
    // Default no-op � override to register with runtime services.
    void Apply(IServiceProvider serviceProvider, IJobDescription jobDescription, IJob job) { }
}

IAutoFeatureConfigurator

Implementations are auto-discovered at startup by AddJobManager. Each is called once to register services into the DI container (middleware, conditions, singletons). Per-job data is handled separately through IJobManagerFeature.Apply.

public class MyConfigurator : IAutoFeatureConfigurator
{
    public void AutoConfigure(IJobManagerConfigurationBuilder builder)
    {
        builder.ConfigureServices(services =>
            services.AddSingleton<IMyService, MyService>());
        builder.AddMiddleware<MyMiddleware>();
    }
}

Middleware

IExecutionMiddleware

Pipeline component invoked around each job task execution:

public class LoggingMiddleware : IExecutionMiddleware
{
    public async Task InvokeAsync(IJobTaskContextBuilder context, Func<Task> next, CancellationToken ct)
    {
        Console.WriteLine($"Before: {context.Job.Name}");
        await next();
        Console.WriteLine($"After: {context.JobTask.Status}");
    }
}

Register via configure.AddMiddleware<LoggingMiddleware>().

Execution Conditions

IExecutionCondition

Evaluated before a job runs. Set context.SetNotReady(reason) to block execution:

public class BusinessHoursCondition : IExecutionCondition
{
    public Task EvaluateAsync(ExecutionConditionContext context, CancellationToken ct)
    {
        if (DateTime.Now.Hour < 8 || DateTime.Now.Hour > 18)
            context.SetNotReady("Outside business hours");

        return Task.CompletedTask;
    }
}

Register via configure.AddExecutionCondition<BusinessHoursCondition>().

IExecutionConditionController

Coordinates multiple IExecutionCondition instances and produces a combined JobConditionStatus. The default implementation (JobConditionController) stops on the first not-ready result. Override via configure.AddExecutionConditionController<T>().

Job Task Journal

Each IJobTask exposes a Journal of JobTaskJournalEntry records. When a per-job logger is configured via .WithLogger(...), journal entries are forwarded to it through JobTaskJournalLoggerAdapter.