RepletoryLib.BackgroundJobs.Abstractions 1.0.0

RepletoryLib.BackgroundJobs.Abstractions

Background job abstractions and interfaces for the RepletoryLib ecosystem.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.BackgroundJobs.Abstractions defines the contracts for background job scheduling in the RepletoryLib ecosystem. It provides interfaces for enqueueing fire-and-forget jobs, scheduling delayed jobs, and managing recurring jobs with cron expressions.

By programming against these interfaces, your application code stays decoupled from the job processing engine. You can switch between Hangfire, Quartz, or any future implementation without modifying business logic.

This package contains interfaces only -- no implementations. Choose an implementation package based on your needs.

Choosing an Implementation

Key Features

• IBackgroundJobService -- Enqueue, schedule, and manage recurring background jobs
• IJobFilter -- Hook into job lifecycle (executing, executed, failed)
• JobContext -- Rich metadata for job execution (ID, name, attempt number, creation time)
• Expression-based API -- Jobs defined as Expression<Func<Task>> for type safety

Installation

dotnet add package RepletoryLib.BackgroundJobs.Abstractions

Or add to your .csproj:

<PackageReference Include="RepletoryLib.BackgroundJobs.Abstractions" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Usage Examples

Fire-and-Forget Jobs

Enqueue a job to run immediately in the background:

using RepletoryLib.BackgroundJobs.Abstractions.Interfaces;

public class OrderController : ControllerBase
{
    private readonly IBackgroundJobService _jobs;

    public OrderController(IBackgroundJobService jobs) => _jobs = jobs;

    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        var order = await _orderService.CreateAsync(request);

        // Send confirmation email in background (don't block the response)
        await _jobs.EnqueueAsync(() =>
            _emailService.SendOrderConfirmationAsync(order.Id));

        return Created($"/orders/{order.Id}", order);
    }
}

Scheduled (Delayed) Jobs

Schedule a job to run after a delay:

// Send a follow-up email 24 hours after order creation
await _jobs.ScheduleAsync(() =>
    _emailService.SendFollowUpAsync(orderId),
    TimeSpan.FromHours(24));

// Cancel a pending reservation if not confirmed within 15 minutes
await _jobs.ScheduleAsync(() =>
    _reservationService.CancelIfPendingAsync(reservationId),
    TimeSpan.FromMinutes(15));

Recurring Jobs

Set up recurring jobs with cron expressions:

// Run a daily report at 6:00 AM
await _jobs.AddOrUpdateRecurringAsync(
    "daily-sales-report",
    () => _reportService.GenerateDailySalesReportAsync(),
    "0 6 * * *");

// Process expired subscriptions every hour
await _jobs.AddOrUpdateRecurringAsync(
    "expire-subscriptions",
    () => _subscriptionService.ProcessExpiredAsync(),
    "0 * * * *");

// Run cleanup every Sunday at midnight
await _jobs.AddOrUpdateRecurringAsync(
    "weekly-cleanup",
    () => _cleanupService.RunWeeklyCleanupAsync(),
    "0 0 * * 0");

// Remove a recurring job
await _jobs.RemoveRecurringAsync("daily-sales-report");

Job Filters

Implement IJobFilter to hook into the job lifecycle for logging, metrics, or error handling:

using RepletoryLib.BackgroundJobs.Abstractions.Interfaces;
using RepletoryLib.BackgroundJobs.Abstractions.Models;

public class JobTelemetryFilter : IJobFilter
{
    private readonly ILogger<JobTelemetryFilter> _logger;

    public JobTelemetryFilter(ILogger<JobTelemetryFilter> logger) => _logger = logger;

    public void OnJobExecuting(JobContext context)
    {
        _logger.LogInformation(
            "Job {JobName} ({JobId}) starting, attempt #{Attempt}",
            context.JobName, context.JobId, context.AttemptNumber);
    }

    public void OnJobExecuted(JobContext context)
    {
        _logger.LogInformation(
            "Job {JobName} ({JobId}) completed successfully",
            context.JobName, context.JobId);
    }

    public void OnJobFailed(JobContext context, Exception exception)
    {
        _logger.LogError(exception,
            "Job {JobName} ({JobId}) failed on attempt #{Attempt}",
            context.JobName, context.JobId, context.AttemptNumber);
    }
}

API Reference

IBackgroundJobService

public interface IBackgroundJobService
{
    Task<string> EnqueueAsync(Expression<Func<Task>> job);
    Task<string> ScheduleAsync(Expression<Func<Task>> job, TimeSpan delay);
    Task AddOrUpdateRecurringAsync(string jobId, Expression<Func<Task>> job, string cronExpression);
    Task RemoveRecurringAsync(string jobId);
}

IJobFilter

public interface IJobFilter
{
    void OnJobExecuting(JobContext context);
    void OnJobExecuted(JobContext context);
    void OnJobFailed(JobContext context, Exception exception);
}

JobContext

public class JobContext
{
    public string JobId { get; }
    public string JobName { get; }
    public int AttemptNumber { get; }
    public DateTime CreatedAt { get; }
}

Integration with Other RepletoryLib Packages

Testing

Mock IBackgroundJobService with Moq or a simple in-memory implementation:

using Moq;

public class OrderControllerTests
{
    [Fact]
    public async Task CreateOrder_enqueues_email_job()
    {
        var mockJobs = new Mock<IBackgroundJobService>();
        mockJobs
            .Setup(j => j.EnqueueAsync(It.IsAny<Expression<Func<Task>>>()))
            .ReturnsAsync("job-123");

        var controller = new OrderController(mockJobs.Object);

        var result = await controller.CreateOrder(new CreateOrderRequest());

        mockJobs.Verify(
            j => j.EnqueueAsync(It.IsAny<Expression<Func<Task>>>()),
            Times.Once);
    }
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.