NexJob 0.4.0

<div align="center">

<br/>

███╗   ██╗███████╗██╗  ██╗     ██╗ ██████╗ ██████╗
████╗  ██║██╔════╝╚██╗██╔╝     ██║██╔═══██╗██╔══██╗
██╔██╗ ██║█████╗   ╚███╔╝      ██║██║   ██║██████╔╝
██║╚██╗██║██╔══╝   ██╔██╗ ██   ██║██║   ██║██╔══██╗
██║ ╚████║███████╗██╔╝ ██╗╚█████╔╝╚██████╔╝██████╔╝
╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝ ╚════╝  ╚═════╝ ╚═════╝

Background jobs for .NET that stay out of your way.

<br/>

</div>

What is NexJob?

NexJob is a modern, open-source background job framework for .NET built for predictable execution, time-sensitive workflows, and explicit failure handling.

Unlike Hangfire — which relies on serialization magic and delayed async — NexJob is async/await native, fully type-safe, and stateless. Jobs run in isolated DI scopes with zero hidden state. Storage is the source of truth. Failures are explicit.

⚡ 30-Second Quick Start

1. Define a job

public class SendInvoiceJob : IJob<SendInvoiceInput>
{
    private readonly IEmailService _email;
    public SendInvoiceJob(IEmailService email) => _email = email;

    public async Task ExecuteAsync(SendInvoiceInput input, CancellationToken ct)
        => await _email.SendAsync(input.Email, "Invoice attached", ct);
}

2. Register

builder.Services.AddNexJob(builder.Configuration)
                .AddNexJobJobs(typeof(Program).Assembly);

3. Enqueue

await scheduler.EnqueueAsync<SendInvoiceJob, SendInvoiceInput>(
    new(orderId, email));

Done. The job executes immediately on an available worker.

🔥 Why NexJob?

⚔️ NexJob vs Hangfire

📦 Installation

# Core
dotnet add package NexJob

# Storage (pick one — all free)
dotnet add package NexJob.Postgres
dotnet add package NexJob.SqlServer
dotnet add package NexJob.Redis
dotnet add package NexJob.MongoDB

# Dashboard
dotnet add package NexJob.Dashboard

Features in Depth

Scheduling

Fire and forget

await scheduler.EnqueueAsync<SendInvoiceJob, SendInvoiceInput>(new(orderId, email));

Delayed

await scheduler.ScheduleAsync<SendInvoiceJob, SendInvoiceInput>(
    new(orderId, email), 
    delay: TimeSpan.FromMinutes(5));

Recurring (cron)

await scheduler.RecurringAsync<ReportJob, ReportInput>(
    id: "monthly",
    input: new(DateTime.UtcNow.Month),
    cron: "0 9 1 * *");

Continuations (chaining)

var paymentId = await scheduler.EnqueueAsync<ProcessPaymentJob, PaymentInput>(input);
await scheduler.ContinueWithAsync<SendReceiptJob, ReceiptInput>(paymentId, receiptInput);

Reliability

Global retry policy

By default, jobs retry with exponential backoff. Configure via appsettings.json:

{ "NexJob": { "MaxAttempts": 5 } }

Per-job retry

[Retry(5, InitialDelay = "00:00:30", Multiplier = 2.0, MaxDelay = "01:00:00")]
public class PaymentJob : IJob<PaymentInput> { ... }

Dead-letter handler

Automatically handle jobs that exhaust retries:

public class PaymentDeadLetterHandler : IDeadLetterHandler<PaymentJob>
{
    public async Task HandleAsync(JobRecord failedJob, Exception lastException, CancellationToken ct)
        => await _alerts.SendAsync($"Payment failed", ct);
}

builder.Services.AddTransient<IDeadLetterHandler<PaymentJob>, PaymentDeadLetterHandler>();

Graceful shutdown

Jobs complete naturally on SIGTERM. Strays are requeued by orphan watcher.

Deadlines

Jobs not executed within the deadline are marked Expired and skipped:

await scheduler.EnqueueAsync<PaymentJob, PaymentInput>(
    input,
    deadlineAfter: TimeSpan.FromMinutes(5));

Observability

OpenTelemetry (zero config)

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource("NexJob"))
    .WithMetrics(m => m.AddMeter("NexJob"));

Metrics: nexjob.jobs.enqueued, nexjob.jobs.succeeded, nexjob.jobs.failed, nexjob.jobs.expired, nexjob.job.duration.

Job context

public class ImportJob : IJob<ImportInput>
{
    private readonly IJobContext _ctx;
    public ImportJob(IJobContext ctx) => _ctx = ctx;

    public async Task ExecuteAsync(ImportInput input, CancellationToken ct)
    {
        await _ctx.ReportProgressAsync(0, "Starting...", ct);
        // ... do work ...
        await _ctx.ReportProgressAsync(100, "Done.", ct);
    }
}

Job tags

await scheduler.EnqueueAsync<SendInvoiceJob, SendInvoiceInput>(
    input,
    tags: ["tenant:acme", $"invoice:{invoiceId}"]);

var jobs = await scheduler.GetJobsByTagAsync("tenant:acme");

Concurrency & Throttling

Resource throttling

[Throttle(resource: "stripe", maxConcurrent: 3)]
public class ChargeCardJob : IJob<ChargeInput> { ... }

Execution windows

Restrict queues to specific times:

{
  "NexJob": {
    "Queues": [
      {
        "Name": "reports",
        "Workers": 2,
        "ExecutionWindow": {
          "StartTime": "22:00",
          "EndTime": "06:00",
          "TimeZone": "America/Sao_Paulo"
        }
      }
    ]
  }
}

Payload Versioning

Handle evolving job inputs gracefully:

[SchemaVersion(2)]
public class SendInvoiceJob : IJob<SendInvoiceInputV2> { ... }

public class Migration : IJobMigration<SendInvoiceInputV1, SendInvoiceInputV2>
{
    public SendInvoiceInputV2 Migrate(SendInvoiceInputV1 old)
        => new(old.OrderId, old.Email, Language: "en-US");
}

builder.Services.AddJobMigration<SendInvoiceInputV1, SendInvoiceInputV2, Migration>();

Dashboard

Web API:

app.UseNexJobDashboard("/dashboard");

Worker Service / Console App:

services.AddNexJobStandaloneDashboard(configuration);
// Dashboard at http://localhost:5005/dashboard

Configuration

appsettings.json

{
  "NexJob": {
    "Workers": 10,
    "MaxAttempts": 5,
    "PollingInterval": "00:00:05",
    "ShutdownTimeoutSeconds": 30,
    "DefaultQueue": "default",
    "Queues": [
      { "Name": "critical", "Workers": 3 },
      { "Name": "default",  "Workers": 5 }
    ]
  }
}

Code configuration

builder.Services.AddNexJob(builder.Configuration, opt =>
{
    opt.UsePostgres(connectionString);
    opt.Workers = 10;
    opt.MaxAttempts = 5;
});

Storage Providers

All open-source. No license walls.

Testing

The in-memory provider is built-in:

services.AddNexJob();  // InMemory by default

Project

Roadmap

v0.4.0  ✅ Wake-up channel · Deadlines · Dead-letter handlers · README updated
v1.0.0  ○ Stable API · production-ready

Contributing

NexJob is open-source. Issues, PRs, and ideas welcome.

git clone git@github.com:oluciano/NexJob.git
cd NexJob && dotnet test

See CONTRIBUTING.md for details.

License

MIT © 2025 Luciano Azevedo

<div align="center"> <br/>

Built with obsession over developer experience.

If Hangfire is the past, NexJob is what comes next.

<br/> </div>