Hangfire details

Hangfire Detailed explanation

zero 、 List of articles

One 、 summary

1、 summary

stay .NET and .NET Core A simple way to perform background processing in an application . There is no need to Windows Services or separate processes . Supported by persistent storage . Open source and free for commercial use .

Official website address ：https://www.hangfire.io/

Document address ：https://docs.hangfire.io/en/latest/

2、 Architecture Composition

Hangfire It's made up of three main parts ： client 、 Storage and The server .

（1） requirement

Hangfire For most .NET platform ：.NET Framework 4.5 Or later 、.NET Core 1.0 Or later , Or anything with .NET Standard 1.3 Compatible platforms .

You can integrate it with almost any application framework , Include ASP.NET、ASP.NET Core、 Console Application 、Windows service 、WCF etc. .

（2） Storage

The storage is Hangfire A place to store all information related to background job processing . type 、 Method name 、 All details such as parameters are serialized and put into storage , No data is stored in the memory of the process . The storage subsystem is Hangfire Is well abstracted from , It can be for RDBMS and NoSQL Solution implementation .

This is the only configuration you need before you start using the framework . The following example shows how to use SQL Server Database configuration Hangfire. Please note that , The connection string may be different , It depends on your environment .

GlobalConfiguration.Configuration 
    .UseSqlServerStorage(@"Server=.\SQLEXPRESS; Database=Hangfire.Sample; Integrated Security=True");

（3） client

The client can create any type of background job ： Instant tasks （ Execute now ）, Delayed tasks （ Execute the call after a period of time ）, Timing task （ Every hour 、 Execute the method every day ）.

Hangfire You don't need to create special classes . Background jobs are based on regular static or instance method calls .

// Instance method call 
var client = new BackgroundJobClient();
client.Enqueue(() => Console.WriteLine("Hello world!"));

// Static method calls 
BackgroundJob.Enqueue(() => Console.WriteLine("Hello world!"));

（4） The server

Background jobs are created by Hangfire Server Handle . It is implemented as a set of dedicated （ Not a thread pool ） Background thread , They get jobs from storage and process them . The server is also responsible for keeping the storage clean and automatically deleting old data .

Hangfire Use a reliable retrieval algorithm for each storage back end , So you can go to Web Start processing inside the application , Not when the application restarts 、 The risk of losing background jobs when a process terminates .

You just need to create one BackgroundJobServer Class and start processing ：

using (new BackgroundJobServer())
{
    Console.WriteLine("Hangfire Server started. Press ENTER to exit...");
    Console.ReadLine();
}

3、 characteristic

4、 Distributed

Tasks created by the client can be executed separately from those pulled from the storage by the server .

Exchange data through the same storage , Instead of exchanging data directly , The client and server can be decoupled .

Two 、 Quick start

1、nuget Import assembly

Hangfire As a few NuGet Package distribution , From main package Hangfire.Core Start , It contains all the main classes and abstractions .Hangfire.SqlServer Other packages provide functions or abstract implementations . To start using Hangfire, Please install the main package and select an available storage .

Here I use MySql As Hangfire Of Storage.Hangfire The official version only offers SqlServer Access support , Add one more in the paid version Redis. need MongoDB、SqlServer 、PostgreSql、SQLite Others, such as Storages You can find third-party open source projects by yourself , Here is a list of officially recommended extensions https://www.hangfire.io/extensions.html, The list lists some other kinds of Storages.

Hangfire.Core   edition 1.7.30,Net5
Hangfire.MySqlStorage  mysql Database storage 

2、 mount this database

mount this database

The installation database can use docker Containerization installation , Simple and easy to use , One line command solution ,docker Relevant knowledge can refer to docker Detailed explanation .

docker run --name mysqlserver -v /data/mysql/conf:/etc/mysql/conf.d -v /data/mysql/logs:/logs -v /data/mysql/data:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=123456 -d -i -p 3306:3306 mysql:latest --lower_case_table_names=1

Parameters	explain
–name mysqlserver	The name of the container run
-v /data/mysql/conf:/etc/mysql/conf.d	The host machine /data/mysql/conf Map to container /etc/mysql/conf.d
-v /data/mysql/logs:/logs	The host machine /data/mysql/logs Map to container /logs
-v /data/mysql/data:/var/lib/mysql	The host machine /data/mysql/data Map to container /var/lib/mysql
-e MYSQL_ROOT_PASSWORD=123456	Database initial password 123456
-p 3306:3306	The host machine 3306 The port maps to the container 3306 port
–lower_case_table_names=1	Set table names to ignore case , Can only be modified for the first time , It can't be modified later

Create database hangfiredb

3、 Code implementation

Use GlobalConfiguration Class to execute configuration . its Configuration Property provides many extension methods , Both from Hangfire.Core, Also from other packages .

Method calls can be chained , So there is no need to use the class name again and again . Global configuration is for simplicity , Almost every Hangfire Classes allow you to store 、 Filters, etc. specify overrides . stay ASP.NET Core Environment , The global configuration class is hidden in AddHangfire In the method .

internal class Program
{
    static void Main(string[] args)
    {
        // Configure storage 
        GlobalConfiguration.Configuration
            .SetDataCompatibilityLevel(CompatibilityLevel.Version_170)// Global configuration compatible version , Backwards compatible 
            .UseColouredConsoleLogProvider()// Output log 
            .UseSimpleAssemblyNameTypeSerializer()// Serializer with simple assembly name type 
            .UseRecommendedSerializerSettings()// Use the recommended serialization configuration 
            .UseStorage(new MySqlStorage(
             "server= The server IP Address ;Database=hangfiredb;user id=root;password=123456;SslMode=none",
             new MySqlStorageOptions
             {
                 TransactionIsolationLevel = IsolationLevel.ReadCommitted,
                 QueuePollInterval = TimeSpan.FromSeconds(15),
                 JobExpirationCheckInterval = TimeSpan.FromHours(1),
                 CountersAggregateInterval = TimeSpan.FromMinutes(5),
                 PrepareSchemaIfNecessary = true,
                 DashboardJobListLimit = 50000,
                 TransactionTimeout = TimeSpan.FromMinutes(1),
                 TablesPrefix = "Hangfire"
             }));

        // Client create task 
        BackgroundJob.Enqueue(() => Console.WriteLine("Hello, world!"));

        // The server runs the task 
        using (var server = new BackgroundJobServer())
        {
            Console.ReadLine();
        }
    }
}

Optional parameter description ：

• TransactionIsolationLevel- Transaction isolation level . The default is read committed .
• QueuePollInterval- Job queue polling interval . The default value is 15 second .
• JobExpirationCheckInterval- Job expiration check interval （ Manage expired records ）. The default value is 1 Hours .
• CountersAggregateInterval- The interval of the aggregate counter . The default is 5 minute .
• PrepareSchemaIfNecessary- If set to true, It creates database tables . The default is true.
• DashboardJobListLimit- Dashboard job list restrictions . The default value is 50000.
• TransactionTimeout- Transaction timeout . The default value is 1 minute .
• TablesPrefix- Prefix of the table in the database . Default to none

4、 Running results

（1） The first time you run a database table, it is automatically created

（2） The task was executed successfully

3、 ... and 、 Supports multiple task types

1、 Instant tasks

Immediate task jobs only execute once , Almost after creation Execute now .

var jobId = BackgroundJob .Enqueue(() => Console .WriteLine( " Instant tasks ！" ));

2、 Delayed tasks

Delayed jobs are also Only once , But not necessarily The time interval Immediately after .

var jobId2 = BackgroundJob.Schedule(() => Console.WriteLine(" Delayed tasks ！"), TimeSpan.FromMilliseconds(10));

3、 Repeat task

Repeat the job at the specified CRON On the plan **** many times Trigger .

RecurringJob.AddOrUpdate("myrecurringjob", () => Console.WriteLine(" Repeat task ！"), Cron.Minutely);

4、 Go ahead with the task

Be his father complete Continue with .

BackgroundJob.ContinueJobWith(jobId2,() => Console.WriteLine("jobId2 After execution, continue to execute ！"));

5、 Batch tasks - charge

A batch process is a set of processes that Atomic creation And is treated as a background job of a single entity .

var batchId = BatchJob.StartNew(x =>
{
    x.Enqueue(() => Console.WriteLine("Job 1"));
    x.Enqueue(() => Console.WriteLine("Job 2"));
});

6、 Batch continue task – charge

When... In the parent batch All background jobs **** complete when , Batch processing will be triggered to continue .

BatchJob.ContinueBatchWith(batchId, x =>
{
    x.Enqueue(() => Console.WriteLine("Last Job"));
});

7、 Encapsulation tasks

When the business logic is complex, it can be encapsulated into methods

// The way of encapsulation 
public class SyncUserDataSchedule
{
    public void SyncUserData()
    {
        Console.WriteLine($" Synchronize user data --{DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss")}");
    }
}

RecurringJob.AddOrUpdate<SyncUserDataSchedule>(c => c.SyncUserData(), Cron.Minutely);

Four 、 Integrated into the Asp.NetCore5 frame

1、 demand

The dashboard

Access control

http Ask for a task

Request parameters

Custom tasks

corn To configure

2、nuget Import assembly

Microsoft.AspNetCore.App
Hangfire.Core
Hangfire.MySqlStorage                   --mysql Database storage 
Hangfire.AspNetCore                     --AspNetCore Support 
Hangfire.Dashboard.BasicAuthorization   -- visualization + Access control 
Hangfire.HttpJob                        --httpJob

3、 Create database

Ditto quick start , establish hangfiredb

4、 Configuration file configuration

Add connection string and print log level

Allow User Variables=true; This parameter is important , Otherwise, the page will not display normally .

{
    
  "ConnectionStrings": {
    
    "HangfireConnection":"server= The server IP Address ;Database=hangfiredb;userid=root;password=123456;SslMode=none;Allow User Variables=true;"
  },
  "Logging": {
    
    "LogLevel": {
    
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Hangfire": "Information"
    }
  },
  "AllowedHosts": "*"
}

5、Startup Support hangfire

Account verification can also be configured to the database and configuration file

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Config = configuration;
    }

    public IConfiguration Config { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        // Add Hangfire services.
        services.AddHangfire(configuration => configuration
            .SetDataCompatibilityLevel(CompatibilityLevel.Version_170)
            .UseSimpleAssemblyNameTypeSerializer()
            .UseRecommendedSerializerSettings()                
            .UseStorage(new MySqlStorage(
             Config["ConnectionStrings:HangfireConnection"],
             new MySqlStorageOptions
             {
                 TransactionIsolationLevel = IsolationLevel.ReadCommitted,
                 QueuePollInterval = TimeSpan.FromSeconds(15),
                 JobExpirationCheckInterval = TimeSpan.FromHours(1),
                 CountersAggregateInterval = TimeSpan.FromMinutes(5),
                 PrepareSchemaIfNecessary = true,
                 DashboardJobListLimit = 50000,
                 TransactionTimeout = TimeSpan.FromMinutes(1),
                 TablesPrefix = "Hangfire"
             })).UseHangfireHttpJob());
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHangfireServer();
        app.UseHangfireDashboard("/hangfire", new DashboardOptions
        {
            Authorization = new[] { new BasicAuthAuthorizationFilter(new BasicAuthAuthorizationFilterOptions
            {
                RequireSsl = false,
                SslRedirect = false,
                LoginCaseSensitive = true,
                Users = new []
                {
                    new BasicAuthAuthorizationUser
                    {
                        Login = "admin",
                        PasswordClear =  "test"
                    }
                }
            })}
        });

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapGet("/", async context =>
            {
                await context.Response.WriteAsync("Hello World!");
            });
        });
    }
}

6、 Operation results

Access page http://localhost:8848/hangfire, The account number needs to be verified for the first time

After logging in, you can see the entire dashboard and configuration interface

Job management ： Dashboard home page

Homework ： Some execution of the job

retry ： Some failed retrying job information

Job periodicity ： Some periodic jobs can be configured

The server ： Display the server information of the currently running task

5、 ... and 、 Integrated into the Asp.NetCore6 frame

Other parts are the same as Asp.NetCore5,Program as follows

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // Add Hangfire services.
        builder.Services.AddHangfire(configuration => configuration
            .SetDataCompatibilityLevel(CompatibilityLevel.Version_170)
            .UseSimpleAssemblyNameTypeSerializer()
            .UseRecommendedSerializerSettings()
            .UseStorage(new MySqlStorage(
             builder.Configuration["ConnectionStrings:HangfireConnection"],
             new MySqlStorageOptions
             {
                 TransactionIsolationLevel = IsolationLevel.ReadCommitted,
                 QueuePollInterval = TimeSpan.FromSeconds(15),
                 JobExpirationCheckInterval = TimeSpan.FromHours(1),
                 CountersAggregateInterval = TimeSpan.FromMinutes(5),
                 PrepareSchemaIfNecessary = true,
                 DashboardJobListLimit = 50000,
                 TransactionTimeout = TimeSpan.FromMinutes(1),
                 TablesPrefix = "Hangfire"
             })).UseHangfireHttpJob());


        var app = builder.Build();

        app.UseHangfireServer();
        app.UseHangfireDashboard("/hangfire", new DashboardOptions
        {
            Authorization = new[] { new BasicAuthAuthorizationFilter(new BasicAuthAuthorizationFilterOptions
            {
                RequireSsl = false,
                SslRedirect = false,
                LoginCaseSensitive = true,
                Users = new []
                {
                    new BasicAuthAuthorizationUser
                    {
                        Login = "admin",
                        PasswordClear =  "test"
                    }
                }
            })}
        });

        app.MapGet("/", () => "Hello World!");

        app.Run();
    }
}

6、 ... and 、 Best practice advice

1、 Business and scheduled tasks are decoupled

The scheduled task only configures the request service api, Encapsulate the business into api External exposure api, Realize the decoupling of business and scheduled tasks .