Soenneker.Flywheel.Core 4.0.16

Soenneker.Flywheel.Core

Background jobs for .NET with Redis storage, retries, scheduling, and job chains.

Background work. Everything in view.

Queue a typed job, coordinate workers across instances, and follow each execution in the live Blazor dashboard.

The optional Flywheel Dashboard, shown with illustrative demo data.

Explore Flywheel · Dashboard · Run the demo

Setup

Requires .NET 10 and Redis 6.0.9 or newer. Add these packages to your app:

dotnet add package Soenneker.Flywheel.Core
dotnet add package Soenneker.Flywheel.Redis
dotnet add package Soenneker.Flywheel.Generators

Add PrivateAssets="all" to the Generators package reference in your project file.

Usage

In an ASP.NET Core app's Program.cs, register Flywheel and enqueue a job:

using Soenneker.Flywheel.Core.Attributes;
using Soenneker.Flywheel.Core.Registrars;
using Soenneker.Flywheel.Core.Services.Abstract;
using Soenneker.Flywheel.Generated;
using Soenneker.Flywheel.Redis;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFlywheel(options => options.Workers = 4)
    .AddRedis(options => options.ConnectionString = "localhost:6379")
    .AddGeneratedJobs();

var app = builder.Build();
var client = app.Services.GetRequiredService<IJobClient>();

await client.Enqueue(FlywheelJobs.MessageJobs_Write,
    new Message("Hello from Flywheel"));

await app.RunAsync();

public sealed record Message(string Text);

public sealed class MessageJobs(ILogger<MessageJobs> logger)
{
    [FlywheelJob("message.write.v1")]
    public Task Write(Message message, CancellationToken cancellationToken)
    {
        logger.LogInformation("{Message}", message.Text);
        return Task.CompletedTask;
    }
}

When hosting the optional dashboard API, register its credentials with AddDashboard, map controllers for its HTTP endpoints, and let Flywheel map its authenticated real-time endpoint:

builder.Services.AddFlywheel()
    .AddRedis(options => options.ConnectionString = "localhost:6379")
    .AddDashboard(options =>
    {
        options.Username = builder.Configuration["Flywheel:Dashboard:Username"] ?? "";
        options.PasswordPhc = builder.Configuration["Flywheel:Dashboard:PasswordPhc"] ?? "";
    });

var app = builder.Build();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.MapControllers();
app.MapFlywheelDashboard();

Enqueue returns after saving the job. Workers run it in the background. In other services, inject IJobClient to submit jobs.

Handlers can inject IJobProgress and publish durable progress while they run:

public sealed class ImportJobs(IJobProgress progress)
{
    [FlywheelJob("contacts.import.v1")]
    public async Task Import(ImportRequest request, CancellationToken cancellationToken)
    {
        for (var i = 0; i < request.Contacts.Count; i++)
        {
            await Import(request.Contacts[i], cancellationToken);
            await progress.Report((i + 1d) / request.Contacts.Count * 100, $"Imported {i + 1} contacts", cancellationToken);
        }
    }
}

Declare distributed execution limits with the job so every server applies the same generated policy before workers start:

[FlywheelJob("contacts.import.v1", MaxConcurrency = 1)]
public Task Import(ImportRequest request, CancellationToken cancellationToken) => // ...

IJobClient.ConfigureMethod remains available for limits that genuinely need to change at runtime.

Queue and schedule jobs

Use IJobClient for immediate, delayed, scheduled, recurring, cron, or chained jobs:

await client.Enqueue(FlywheelJobs.MessageJobs_Write, new Message("Later"),
    delay: TimeSpan.FromMinutes(10));

await client.Recurring("hourly-message", FlywheelJobs.MessageJobs_Write,
    new Message("Every hour"), TimeSpan.FromHours(1));

await client.Schedule("weekday-message", FlywheelJobs.MessageJobs_Write,
    new Message("Good morning"), "0 9 * * MON-FRI",
    timeZoneId: "America/Chicago");

See IJobClient for the full API.

Jobs can run more than once; make handlers safe to retry and pass cancellation tokens to async work. Keep job names stable. Reusing a recurring or cron schedule ID leaves the existing schedule unchanged.

Related

• Redis: storage configuration.
• Generators: job method requirements.
• Dashboard: view jobs and logs.
• Demo: run a complete app.