Masterly.NightShift documentation
Masterly.NightShift runs background jobs in .NET applications: fire-and-forget, delayed, recurring and continuation jobs. Jobs are stored in a database you already run (SQL Server ships in the box), so they survive restarts and deploys, and a built-in dashboard shows what is happening.
New here? Read Core concepts, then follow the ASP.NET Core quick start or the console and Worker Service quick start. You'll have a job running and visible in the dashboard in a few minutes.
Coming from Hangfire? Start with Migrating from Hangfire. Your existing SQL Server data keeps working.
A first look
using Masterly.NightShift;
var builder = WebApplication.CreateBuilder(args);
var connectionString = builder.Configuration.GetConnectionString("NightShift")
?? throw new InvalidOperationException("Connection string 'NightShift' is missing.");
builder.Services.AddNightShift(config => config
.SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
.UseRecommendedSerializerSettings()
.UseSqlServerStorage(connectionString));
builder.Services.AddNightShiftServer();
var app = builder.Build();
app.MapNightShiftDashboard();
app.MapPost("/users/{id:int}/welcome", (int id, IBackgroundJobClient jobs) =>
{
jobs.Enqueue<EmailService>(email => email.SendWelcome(id));
return Results.Accepted();
});
app.Run();
AddNightShift configures the storage, AddNightShiftServer starts the workers that run jobs, and Enqueue stores a call to EmailService.SendWelcome(id) that a worker runs as soon as it is free. If it throws, it is retried automatically.
Remastered from Hangfire
Masterly.NightShift is a remastered fork of Hangfire 1.8.25. It keeps Hangfire's programming model and reads your existing Hangfire SQL Server data. It was refactored for .NET 8 and later, and a source generator writes direct calls to your job methods instead of calling them through reflection. It is an independent project, not affiliated with or endorsed by Hangfire OÜ.
| Hangfire 1.8.25 | NightShift 1.0 |
|---|
| Platforms | .NET Framework 4.5.1 and later, .NET Standard | .NET 8 and later only |
| Calling your job method | MethodInfo.Invoke | Source-generated direct call, with compiled and reflection fallbacks |
| JSON | Newtonsoft.Json | System.Text.Json |
| Batches and fan-in | Paid (Hangfire Pro) | Included |
| Semaphores and rate limits | Paid (Hangfire Ace) | Included |
| Circuit breaker, duplicate prevention | Not included | Included |
| Timeouts, deadlines, run windows | [LatencyTimeout] only | Included |
| Progress, console, resume after failure | Community packages | Included |
| OpenTelemetry, Prometheus, health checks, alerts | Community packages | Included |
| Storage | SQL Server, paid Redis, many community storages | SQL Server, Entity Framework Core (PostgreSQL, MySQL, SQLite...), Redis, MongoDB and in memory, all passing one conformance suite |
| Support and track record | Paid support available; more than a decade in production | Community support through GitHub; 1.0 is the first release |
NightShift compared with Hangfire has the full comparison and when to stay on Hangfire.
Benchmarks
Measured on .NET 10 against Hangfire 1.8.25. The SQL Server rows used SQL Server 2022 in a container.
| Operation | Hangfire | NightShift |
|---|
| Call the job method | 17.0 ns | 3.5 ns |
| Serialize a job | 2.38 µs, 10.97 KB | 1.59 µs, 1.84 KB |
| Deserialize a job | 3.34 µs, 17.32 KB | 3.04 µs, 2.08 KB |
| Run an empty job through all filters | 0.58 µs, 1.62 KB | 0.27 µs, 0.63 KB |
Enqueue in a loop, SQL Server | 174 jobs/s | 218 jobs/s |
Enqueue from 64 callers at once | 1,523 jobs/s | 3,179 jobs/s |
| Create many jobs at once | No bulk API | 4,116 jobs/s with EnqueueMany |
| Process from SQL Server | 562 to 648 jobs/s | 606 to 794 jobs/s; 974 to 1,000 with AllowDelayedDurability |
NightShift needs half the round trips to create a job, shares them between concurrent callers, and creates many jobs at once with EnqueueMany. A loop of single Enqueue calls gains the least, because each call waits for the database to store its job. Running a job allocates about 60% less memory, and serializing one over 80% less. Benchmarks has the .NET 8 numbers, what they mean, and how to run them yourself.
Find what you need
| Page | What it covers |
|---|
| Fire-and-forget jobs | Run something now, in the background |
| Delayed jobs | Run something later, including plain-English times like "tomorrow at 9am" |
| Continuations | Run a job after another one finishes, and pass its result along |
| Fan-in and batches | Wait for a whole set of jobs; create jobs as a group |
| Job arguments | What you can pass, how it's serialized, how the job's class is created |
| Cancellation | Cancellation tokens, shutdown, deleting a running job |
| Progress, console and checkpoints | Show a job's progress and log lines live; resume after a failure |
| Tags and notes | Label jobs so you can find them; attach notes |
| Job catalog | Let operators start chosen jobs from the dashboard |
| Managing jobs | Delete, requeue, reschedule, change state, query jobs |
| Source-generated invokers | How job methods are called without reflection |
| Testing | Unit tests for code that creates jobs, job classes and filters; integration tests against LocalDB |
| Page | What it covers |
|---|
| Retries | Automatic retries, retry-later, in-process retries, circuit breakers |
| Concurrency | One at a time, throttling, rate limits, duplicate prevention |
| Timing | Timeouts, deadlines, run windows and blackouts, how long data is kept |
| Behavior | Queues, display names, culture, invocation logging, hiding secrets |
| Custom filters | Writing your own filters, interceptors and state handlers |
| Page | What it covers |
|---|
| Server options | Every BackgroundJobServerOptions property |
| Queues and workers | Worker counts, queues, several servers, graceful shutdown |
| Drain mode | Stop starting new jobs, for the whole system, a queue or a server |
| Keep-alive | Keep IIS-hosted servers from being shut down when idle |
| Dependency injection | What AddNightShift and AddNightShiftServer register; job activation and scopes |
| Background processes | Your own code running in a loop on every server, such as an outbox relay or a cache warmer |
| Page | What it covers |
|---|
| SQL Server storage | Setup, connection strings and factories, permissions |
| SQL Server options | Every SqlServerStorageOptions property and when to change it |
| Schema and upgrades | Tables, schema versions, automatic and manual install, purging |
| Entity Framework Core storage | Any EF Core provider; staging jobs so they commit with SaveChanges |
| Redis storage | Key layout, Lua transactions, pub/sub wake-ups, clusters |
| MongoDB storage | Replica sets, collections, TTL indexes |
| In-memory storage | For development and tests |
| Custom storage | Writing a storage for another database |
| Page | What it covers |
|---|
| Setup | Adding the dashboard to your app; every DashboardOptions property |
| Authorization | Who may see the dashboard, read-only access, a production checklist |
| Pages | Every page and what you can do on it |
| Customization | Your own pages, menu items, metrics, styles and languages |
Help and reference
Working on the library