TAF.BackgroundJobExecutors.SDK 1.0.0

TAF.BackgroundJobExecutors.SDK

Client for the TAF background job executor (scheduler) service. Create recurring and one-time jobs, and consume the event the scheduler publishes when they fire.

Install

<PackageReference Include="TAF.BackgroundJobExecutors.SDK" Version="1.0.0" />

Register

builder.Services.AddSchedulerClient(builder.Configuration);

{
  "SchedulerService": {
    "BaseUrl": "http://taf-backgroundjobexecutors",
    "TimeoutSeconds": 30
  },
  "ServiceAuth": { "ApiKey": "<shared service key>" }
}

ApiKey is read from the caller's own ServiceAuth:ApiKey and sent as X-API-Key, so token-less service-to-service calls pass the scheduler's auth gate.

Create a job

Jobs carry a callback describing what the scheduler does when they fire. Prefer EventCallbackRequest for TAF services — it publishes an event, so your service needs no publicly reachable endpoint.

var callback = new EventCallbackRequest
{
    EventType     = "ReportJobFired",
    TargetService = "Reports",
    JobData       = new Dictionary<string, object?> { ["scheduleId"] = scheduleId }
};

var result = await _scheduler.CreateRecurringJobAsync(
    "0 9 * * MON", callback, context, timezone: "Asia/Kolkata", ct);

if (result.IsSuccess)
    jobId = result.Value;   // keep this — it is how you delete the job later

One-time jobs take a UTC instant instead of a CRON expression:

await _scheduler.CreateOneTimeJobAsync(runAtUtc, callback, context, ct);

Deleting is idempotent enough to call during a re-registration:

await _scheduler.DeleteJobAsync(jobId, context, ct);

Keep JobData small — an identifier, not a snapshot. Re-read the rest from your own store when the job fires, or editing a schedule leaves stale data baked into a job that already exists.

Consume the fired event

Bind to the type in this package. Do not declare your own.

MassTransit derives the publish exchange from the message's namespace-qualified URN. A local class with identical properties binds to a different exchange, so the job registers cleanly, fires on time, and your handler is never called. There is no error to see.

using TAF_BackgroundJobExecutors_Contracts.Events;

public class ReportJobFiredHandler : IEventHandler<JobFiredEvent>
{
    public async Task HandleAsync(JobFiredEvent @event, BusContext context, CancellationToken ct)
    {
        // The event is broadcast to every service — filter to your own.
        if (!string.Equals(@event.TargetService, "Reports", StringComparison.OrdinalIgnoreCase))
            return;

        if (!@event.JobData.TryGetValue("scheduleId", out var raw)
            || !Guid.TryParse(raw?.ToString(), out var scheduleId))
            return;

        await _runner.RunAsync(scheduleId, context, ct);
    }
}

Handlers are discovered automatically by AddMessageBus(); no explicit registration.

JobFiredEvent carries EventType, TargetService, JobId, JobData, FiredAt, and the TenantId / AppId / EnvironmentId the job was created with.

BusContext extensions

For call sites that already carry a BusContext and nothing else:

serviceProvider.InitializeSchedulerExtensions();   // once, at startup
await context.CreateRecurringJobAsync(cron, callback);

Injecting ISchedulerClient is equivalent and preferred in new code.

Results

Every method returns OperationResult<T> — check IsSuccess before reading Value. Transport failures, non-success status codes and unparseable bodies all come back as a failed result with code SCHEDULER_UNAVAILABLE; nothing throws except OperationCanceledException.