TCM.Tasks 1.0.21

TCM.Tasks

Distributed task scheduling library for TCM services, built on Quartz.NET. Provides persistent, clustered background job scheduling with auto-discovery of job implementations and a MediatR-based management API.

Features

• Quartz.NET Integration — Persistent job store backed by SQL Server
• Kubernetes Clustering — Built-in cluster support for distributed deployments
• Auto Job Discovery — Automatically discovers and registers all IQuartzJob implementations at startup
• Cron & Interval Scheduling — Supports standard cron expressions and time-interval triggers
• Run-Now Support — Trigger any job immediately via MediatR query or REST API
• Execution Tracking — Records last start, last success, and last failure timestamps per job
• CQRS API — MediatR commands and queries to create, update, and query scheduled tasks
• REST API — Optional controllers for CRUD (AddTCMTasksControllers)
• Lease-Based Clustering — Prevents duplicate execution across nodes via machine-name leasing

Installation

dotnet add package TCM.Tasks

Note: TCM.Tasks depends on TCM.Core. Both packages must be installed.

Requirements

• .NET 9.0
• SQL Server (for Quartz persistent store and ScheduleTask table)
• TCM.Core

Getting Started

Register Services

Tasks uses a dedicated SQL Server database shared by EF (ScheduleTask) and Quartz (qrtz_* tables).

builder.Services.AddTCMTasks(builder.Configuration);

// Or pass connection string and/or app id explicitly
builder.Services.AddTCMTasks(builder.Configuration, myConnectionString, appId: "MyApp");

Each host application should set TASK_APP_ID so tasks and Quartz jobs are isolated when multiple apps share the same database. Legacy rows may keep AppId null until you backfill them manually.

Quartz scheduler instance: tcm-tasks-{appId} (or tcm-tasks-default when unset). Job group: {appId}.BackgroundTask (or BackgroundTask when unset).

HTTP API (controllers)

builder.Services.AddControllers()
    .AddTCMTasksControllers();

Ensure the host configures API versioning (v1.0), same as other TCM APIs.

InAppAuth (optional, recommended)

TCM.Tasks references TCM.InAppAuth. Controllers use [AppPermission]; handlers apply data scope on ScheduleTask via IScopedEntity.OrgUnitId.

builder.Services.AddInAppAuthentication(builder.Configuration);
builder.Services.AddTCMTasks(builder.Configuration);

builder.Services.AddControllers()
    .AddInAppAuthControllers()
    .AddTCMTasksControllers();

Align app ids: IN_APP_AUTH_APP_ID and TASK_APP_ID should resolve to the same value (e.g. Tasks → resource slug tasks:schedule-task).

Records without OrgUnitId are only visible when scope is All. On create, OrgUnitId defaults to the user's primary org; returns 400 if missing (unless scope is All).

Connection string

Same database for EF and Quartz. Resolution order:

1. connectionString argument to AddTCMTasks (if provided)
2. Otherwise TASK_CONNTECTION_STRING:
   • Development: appsettings.json key TASK_CONNTECTION_STRING
   • Other environments: environment variable TASK_CONNTECTION_STRING, then appsettings fallback

appsettings.json (Development):

{
  "TASK_CONNTECTION_STRING": "Server=...;Database=TCM.Tasks;User Id=...;Password=...;TrustServerCertificate=True",
  "TASK_APP_ID": "MyApp"
}

Production / container:

TASK_CONNTECTION_STRING="Server=...;Database=TCM.Tasks;..."
TASK_APP_ID="MyApp"

EF migrations

Use TasksDbContext for all migrations.

Package Manager Console (default project = TCM.Tasks or migrations project):

Add-Migration AddScheduleTasks -Context TasksDbContext -Project TCM.Tasks -StartupProject TCM.Tasks
Update-Database -Context TasksDbContext -Project TCM.Tasks -StartupProject TCM.Tasks

dotnet ef:

dotnet ef migrations add AddScheduleTasks --project TCM.Tasks --startup-project TCM.Tasks --context TasksDbContext
dotnet ef database update --project TCM.Tasks --startup-project TCM.Tasks --context TasksDbContext

Design-time: TASK_CONNTECTION_STRING in appsettings.json of the startup project (or env var).

Initialize Quartz Tables

On first run, call DatabaseExtension.InitializeAsync() to create the required Quartz SQL Server tables. The SQL script is embedded in the library.

await app.Services.InitializeTaskDatabaseAsync();

Define a Job

public class SendReportJob : IQuartzJob
{
    public async Task Execute(IJobExecutionContext context)
    {
        // job logic here
    }

    public async Task Execute(string id, bool checkRun)
    {
        await Execute(id);
    }

    public async Task Execute(string id)
    {
        // run with specific task ID
    }
}

All classes implementing IQuartzJob are auto-discovered at startup and synced with the database.

Manage Jobs via MediatR

await mediator.Send(new CreateScheduleTaskCommand { ... });
await mediator.Send(new UpdateScheduleTaskCommand { Id = taskId, Enabled = false });
var tasks = await mediator.Send(new ScheduleTasksQuery());
await mediator.Send(new ScheduleTaskRunNowQuery { Id = taskId });

Project Structure

TCM.Tasks/
├── Domain/               ScheduleTask, IScheduleTaskDefinition
├── Models/               ScheduleTaskModel
├── Infrastructure/       ScheduleTaskRepository
├── TypeConfigurations/
├── Contexts/             TasksDbContext
├── Command/              Create, Update, Delete
├── Query/                List, Get, RunNow
├── Controllers/v1/       ScheduleTaskController
├── Quartz/               QuartzJobExecute, IQuartzJob
└── Extensions/           AddTCMTasks, UseQuartz

ScheduleTask Entity

Key Dependencies