Redis with Hangfire

Run .NET background jobs with Hangfire and the community Redis storage package.

Hangfire runs background jobs in .NET applications. It stores jobs in a pluggable storage, and its default is SQL Server. See the job queue use case for when to choose this pattern.

Choose a Redis storage package

Hangfire's core package doesn't include Redis storage. You can get it in two ways:

  • Hangfire.Redis.StackExchange is a community package, listed on Hangfire's extensions page. It is licensed under the LGPL v3 and built on the StackExchange.Redis client. Hangfire OÜ doesn't provide official support for community extensions. This page uses this package.
  • Hangfire.Pro.Redis is part of Hangfire Pro, which is distributed through a private NuGet feed under paid subscriptions. See the Hangfire Pro documentation.

The two have different configuration APIs, so the code on this page is for the community package.

Requirements

The examples on this page were run with Hangfire.Core 1.8.25 and Hangfire.Redis.StackExchange 1.12.0 on .NET 9 against Redis 7.2. Add the packages to your project:

dotnet add package Hangfire.Core
dotnet add package Hangfire.Redis.StackExchange

You also need a running Redis server. You can run one locally with Redis Open Source, use Docker, or connect to Redis Cloud.

Configure the storage and enqueue jobs

Call UseRedisStorage with a connection string, then use BackgroundJob to create jobs:

using Hangfire;
using Hangfire.Redis.StackExchange;

GlobalConfiguration.Configuration
    .UseRedisStorage("<your-redis-host>:6379");

// Run as soon as a worker is free.
BackgroundJob.Enqueue<Jobs>(j => j.Welcome(42, "hello"));

// Run no sooner than 3 seconds from now.
BackgroundJob.Schedule<Jobs>(j => j.Welcome(43, "later"), TimeSpan.FromSeconds(3));

A job is a method on a class. Use AutomaticRetry to control retries:

public class Jobs
{
    public void Welcome(int userId, string greeting) =>
        Console.WriteLine($"Sending welcome to {userId}: {greeting}");

    [AutomaticRetry(Attempts = 3, DelaysInSeconds = new[] { 1 })]
    public void Flaky()
    {
        // Throw an exception here to trigger a retry.
    }
}

Run a server

A BackgroundJobServer fetches and runs jobs. You can host it in any .NET process:

using var server = new BackgroundJobServer(new BackgroundJobServerOptions { WorkerCount = 2 });
await Task.Delay(Timeout.Infinite);
Note:

Hangfire's scheduler moves delayed and retried jobs to the queue on a polling cycle. In these runs the cycle was about 15 seconds. In a test, a job scheduled 3 seconds ahead ran about 12 seconds after it was created, and a retry with a 1-second delay ran 12 and then 15 seconds later. Don't rely on Schedule or the retry delay for second-level accuracy.

What Hangfire stores in Redis

Hangfire's keys start with the prefix {hangfire}:. You can change it with the Prefix option.

Key Type Contents
{hangfire}:queue:<name> list The IDs of jobs that are ready to run.
{hangfire}:queues set The names of the queues.
{hangfire}:schedule sorted set Delayed jobs, scored by run time.
{hangfire}:job:<id> hash The job: Type, Method, Arguments, ParameterTypes, State, CreatedAt, and so on.
{hangfire}:queue:<name>:dequeued list The IDs of jobs that a server has fetched and is running.

A succeeded job's hash expires after about 24 hours by default.

What happens to a job when a server is killed

A server moves a job to the dequeued list when it fetches it, and removes it when the job finishes. If the server dies, the job stays there until it passes the InvisibilityTimeout of the storage options, and then another server fetches it again. The default is 30 minutes. In a test with InvisibilityTimeout set to 10 seconds, a new server ran the job 62 seconds after the first server was stopped with kill -9, so recovery is not instant even with a short timeout.

Set the option to longer than your longest job, or a healthy job will be fetched twice:

GlobalConfiguration.Configuration.UseRedisStorage("<your-redis-host>:6379",
    new RedisStorageOptions { InvisibilityTimeout = TimeSpan.FromMinutes(30) });

Write jobs so that running one twice is safe.

More information

RATE THIS PAGE
Back to top ↑