pkg

JonasG/Hangfire.Mongov1.13.1

.NET FW4.8.NET Std2.1

MongoDB storage implementation for Hangfire (background job system for ASP.NET applications).

License

—

Deps

4

Install Size

—

Vulns

✓ 0

Published

Feb 15, 2026

Get Started

$ dotnet add package Hangfire.Mongo

Readme

Hangfire.Mongo

A MongoDB storage provider for Hangfire. Use MongoDB-compatible servers (including Azure Cosmos DB configured with the MongoDB API, and AWS DocumentDB) to persist and process Hangfire jobs.

Why Hangfire.Mongo?

Reliable job storage and state management in MongoDB.
Multiple queue notification strategies (change streams, tailable collections, polling).
Schema migration and backup strategies with configurable behavior.
Extension points to customize collection creation, serialization and UTC handling.
Works with ASP.NET Core and console-hosted Hangfire servers.

Prerequisites

.NET Standard / .NET Core compatible runtime used by your application.
MongoDB server (community, Atlas, or other compatible servers). For Cosmos DB use the MongoDB API endpoint.

Hangfire (project and docs)

Website: https://www.hangfire.io/
Documentation: https://docs.hangfire.io/en/latest/

Installation

Install from NuGet (recommended):

dotnet add package Hangfire.Mongo

Or via the Package Manager Console in Visual Studio:

PM> Install-Package Hangfire.Mongo

Quick start — ASP.NET Core

Add Hangfire and Hangfire.Mongo in your Startup/Program configuration:

// Program.cs or Startup.cs
var mongoUrl = new MongoUrl("mongodb://localhost:27017/jobs");
var mongoClient = new MongoClient(mongoUrl.ToMongoUrl());

services.AddHangfire(configuration => configuration
    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
    .UseSimpleAssemblyNameTypeSerializer()
    .UseRecommendedSerializerSettings()
    .UseMongoStorage(mongoClient, mongoUrl.DatabaseName, new MongoStorageOptions
    {
        Prefix = "hangfire.mongo",
        CheckConnection = true,
        MigrationOptions = new MongoMigrationOptions
        {
            MigrationStrategy = new MigrateMongoMigrationStrategy(),
            BackupStrategy = new CollectionMongoBackupStrategy()
        }
    }));

services.AddHangfireServer();

var options = new MongoStorageOptions
{
    MigrationOptions = new MongoMigrationOptions
    {
        MigrationStrategy = new DropMongoMigrationStrategy(),
        BackupStrategy = new NoneMongoBackupStrategy()
    }
};

using var storage = new MongoStorage(
    MongoClientSettings.FromConnectionString("mongodb://localhost:27017"),
    "jobs",
    options);

using var server = new BackgroundJobServer(storage);

using Hangfire.Mongo.CosmosDB;

var mongoUrl = new MongoUrl("mongodb://<user>:<password>@<your-account>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb");
var client = new MongoClient(mongoUrl.ToMongoUrl());

var options = new CosmosStorageOptions
{
    // CosmosStorageOptions already sets recommended defaults for Cosmos
    // You can still tweak other options here if necessary (timeouts, prefix, migration options...)
    Prefix = "hangfire",
    MigrationOptions = new MongoMigrationOptions
    {
        MigrationStrategy = new MigrateMongoMigrationStrategy(),
        BackupStrategy = new CollectionMongoBackupStrategy()
    }
};

// ASP.NET Core pattern: use the Hangfire configuration lambda and call the Cosmos-specific
// extension method `UseCosmosStorage` provided in `CosmosBootstrapperConfigurationExtensions`.
// This registers the storage with Hangfire and returns the created `CosmosStorage` instance.
services.AddHangfire(cfg => cfg.UseCosmosStorage(client, "<database>", options));
services.AddHangfireServer();

// Non-ASP.NET Core / GlobalConfiguration pattern:
using Hangfire;
using Hangfire.Mongo.CosmosDB;

// Register Cosmos storage on the global Hangfire configuration and capture the returned storage
var storage = GlobalConfiguration.Configuration.UseCosmosStorage(client, "<database>", options);

// Create a server that uses the registered storage
using var server = new BackgroundJobServer(storage);

using Hangfire.Mongo.DocumentDB;

var client = new MongoClient("mongodb://<user>:<password>@<your-docdb-host>:27017/?ssl=true");

var options = new DocumentDbStorageOptions
{
    // You can still customize prefix, migration options, and other MongoStorageOptions members
    Prefix = "hangfire",
    MigrationOptions = new MongoMigrationOptions
    {
        MigrationStrategy = new MigrateMongoMigrationStrategy(),
        BackupStrategy = new CollectionMongoBackupStrategy()
    }
};

// ASP.NET Core pattern
services.AddHangfire(cfg => cfg.UseDocumentDbStorage(client, "<database>", options));
services.AddHangfireServer();

// Non-ASP.NET Core / GlobalConfiguration pattern
var storage = GlobalConfiguration.Configuration.UseDocumentDbStorage(client, "<database>", options);
using var server = new BackgroundJobServer(storage);

// Example 1: override the database context creation to enforce a custom prefix
public class CustomMongoFactory : MongoFactory
{
    public override HangfireDbContext CreateDbContext(IMongoClient mongoClient, string databaseName, string prefix)
    {
        // Force a different prefix for all Hangfire collections
        var enforcedPrefix = "myapp.hangfire";
        return base.CreateDbContext(mongoClient, databaseName, enforcedPrefix);
    }
}

// Example 2: override the distributed lock creation to change resource naming (or add instrumentation)
public class CustomMongoFactoryWithLocks : MongoFactory
{
    public override MongoDistributedLock CreateMongoDistributedLock(string resource, TimeSpan timeout, HangfireDbContext dbContext, MongoStorageOptions storageOptions)
    {
        // Use an application-specific prefix for the lock resource name
        var customResource = $"MyAppLock:{resource}";

        // You could also wrap the returned lock with your own implementation that adds logging/metrics
        return new MongoDistributedLock(customResource, timeout, dbContext, storageOptions);
    }
}

var options = new MongoStorageOptions
{
    Factory = new CustomMongoFactory(),
};

services.AddHangfire(cfg => cfg.UseMongoStorage(mongoClient, "mydb", options));

public class CustomUtcDateTimeStrategy : UtcDateTimeStrategy
{
    public override BsonValue Serialize(DateTime dateTime)
    {
        // Force DateTime to UTC and store as BsonDateTime
        return new BsonDateTime(DateTime.SpecifyKind(dateTime, DateTimeKind.Utc));
    }

    public override DateTime Deserialize(BsonValue value)
    {
        return value.AsBsonDateTime.ToUniversalTime();
    }
}

var options = new MongoStorageOptions
{
    UtcDateTimeStrategies = new UtcDateTimeStrategy[]
    {
        new CustomUtcDateTimeStrategy(),
        new AggregationUtcDateTimeStrategy(),
        new ServerStatusUtcDateTimeStrategy()
    }
};

services.AddHangfire(cfg => cfg.UseMongoStorage(mongoClient, "mydb", options));

using System;
using System.Collections.Generic;
using System.Threading;
using MongoDB.Bson;
using MongoDB.Driver;
using Hangfire.Mongo.Database;

// 1) Custom transaction with a simple retry around the bulk commit
public class CustomMongoWriteOnlyTransaction : MongoWriteOnlyTransaction
{
    public CustomMongoWriteOnlyTransaction(HangfireDbContext dbContext, MongoStorageOptions storageOptions)
        : base(dbContext, storageOptions)
    {
    }

    protected override void ExecuteCommit(IMongoCollection<BsonDocument> jobGraph, List<WriteModel<BsonDocument>> writeModels, BulkWriteOptions bulkWriteOptions)
    {
        const int maxAttempts = 3;
        int attempt = 0;

        while (true)
        {
            try
            {
                // use base behavior for actual bulk write
                base.ExecuteCommit(jobGraph, writeModels, bulkWriteOptions);
                return;
            }
            catch (MongoException) when (++attempt < maxAttempts)
            {
                // simple backoff; replace with your preferred retry policy or instrumentation
                Thread.Sleep(200 * attempt);
            }
        }
    }
}

// 2) Custom factory that returns the custom transaction
public class CustomMongoFactory : MongoFactory
{
    public override MongoWriteOnlyTransaction CreateMongoWriteOnlyTransaction(HangfireDbContext dbContext, MongoStorageOptions storageOptions)
    {
        return new CustomMongoWriteOnlyTransaction(dbContext, storageOptions);
    }
}

// 3) Wiring via options
var options = new MongoStorageOptions
{
    Factory = new CustomMongoFactory()
};

services.AddHangfire(cfg => cfg.UseMongoStorage(mongoClient, "mydb", options));

var migrationOptions = new MongoMigrationOptions
{
    MigrationStrategy = new MigrateMongoMigrationStrategy(),
    BackupStrategy = new CollectionMongoBackupStrategy()
};

var storageOptions = new MongoStorageOptions
{
    MigrationOptions = migrationOptions,
    InvisibilityTimeout = TimeSpan.FromMinutes(30)
};

GlobalConfiguration.Configuration.UseMongoStorage("<connection string with database name>", storageOptions);