Plinth.Hangfire 1.7.1

Prefix Reserved

dotnet add package Plinth.Hangfire --version 1.7.1

NuGet\Install-Package Plinth.Hangfire -Version 1.7.1

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Plinth.Hangfire" Version="1.7.1" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add Plinth.Hangfire --version 1.7.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Plinth.Hangfire, 1.7.1"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

// Install Plinth.Hangfire as a Cake Addin
#addin nuget:?package=Plinth.Hangfire&version=1.7.1

// Install Plinth.Hangfire as a Cake Tool
#tool nuget:?package=Plinth.Hangfire&version=1.7.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

README

Plinth.Hangfire

Utility framework for using Hangfire as a scheduled jobs engine

Simplifies usage of Hangfire for operating a persistent scheduled jobs engine which can run predefined tasks on a configurable schedule regardless of number of machines or when they reboot.

1. Project setup

Option 1: Windows Service
- See Plinth.WindowsService to set up an ASP.Net Core project as a Windows Service
Option 2: ASP.NET Core project (IIS or kestrel)

2. Startup.cs

👉 NOTE: by default, it will use the default ISqlTransactionProvider to retrieve the job list from the database. 👉 The Hangfire schema/tables will be created using the db connection string passed in AddPlinthHangfire

Startup.cs

	public void ConfigureServices(IServiceCollection services)
	{
		// hangfire
		services.AddPlinthHangfire(
			Configuration.GetConnectionString("HangfireDB"),
			reg =>
			{
				// register jobs
				reg.RegisterAsyncHandler<BasicJob>(BasicJob.JobCode);
			});
		// hangfire

		// be sure to register job execution class with services
		services.AddTransient<BasicJob>();
	}

	public void Configure(IApplicationBuilder app, IHostingEnvironment env)
	{
	    // hangfire
	    app.UsePlinthHangfire<BasicJobExec>("/dashboard");  // "" to host dashboard at root
	    // hangfire
	}

BasicJob.cs

public class BasicJob : IAsyncJob
{
	public const string JobCode = "BasicJob";
	
	public async Task ExecuteAsync(PlinthJob job)
	{
		await DoJobStuff(job.Code, job.JobData);
	}
}

3. Database setup

👉 You must install either Plinth.Hangfire.MSSql or Plinth.Hangfire.PgSql

👉 In each package, find the Hangfire_Procedures.sql and Hangfire_Tables.sql files. Include those in your database scripts. It is required by the framework that the procedures and tables be available to the main Plinth database connection.

The connection string that is passed to AddPlinthHangfire must have rights to create schemas and tables. This can be a separate database from the main Plinth database. See here for more details: https://docs.hangfire.io/en/latest/configuration/using-sql-server.html

4. Registering Jobs

To register jobs, you must supply the types and the job code that will invoke that job.

		reg =>
		{
			// register Job Code "BasicJob" which will invoke IAsyncJob BasicJob
			reg.RegisterAsyncHandler<BasicJob>("BasicJob");

			// register a handler for all Job Codes not registered with RegisterAsyncHandler
			reg.RegisterAsyncGlobalHandler<GlobalJob>();
		}

Registering a Job by Code will attach that particular code to that particular class and invoke it according to the schedule.
Registering a global Job Handler will invoke that handler if the Job Code is not otherwise registered.

👉 In all cases, the Job Handler will be instantiated via DI, so it is important to register your Job Handlers with the DI container.

5. Configuring Jobs

Hangfire_Procedures.sql ships with a stored procedure called usp_SubmitJob. You can use this to seed the job into the Job table.

Example for MS SQL Server.

EXECUTE usp_SubmitJob
	@Code = "BasicJob",
	@Description = "A basic job",
	@JobData = '{ "Meta1": 55 }',
	@CronExpression = '*/15 * * * 1-5',
	@TimeZone = NULL,
	@IsActive = 1,
	@CallingUser = 'System';

Example for PostgreSQL

SELECT * FROM public.fn_submit_job(
	i_code := 'BasicJob',
	i_description := 'A basic Job',
	i_job_data = '{ "Meta1": 55 }',
	i_cron_expression := '*/15 * * * 1-5',
	i_time_zone := NULL,
	i_is_active := 1,
	i_calling_user := 'System');

@Code: A unique identifier for the job. Will appear in the Hangfire dashboard so something human readable is recommended.
@Description: More descriptive text for the job. Will also appear in the Hangfire dashboard.
@JobData: Option metadata which is provided to the Job Handler. Typically JSON but can be any NVARCHAR data
@CronExpression: A cron expression which indicates when the job will run.
- This site is a handy way to craft cron expressions: https://crontab.guru
- Note that Hangfire supports second level precision for jobs. To use, place an extra value before the expression.
- Examples:
  - * * * * * ⇒ Start of every minute
  - */30 * * * * * ⇒ Every 30 seconds at the start of the minute and halfway through the minute
  - 30 22 * * * ⇒ Every night at 11:30 PM
  - */30 * */4 * 2,3,4 2-5 ⇒ Every 30 seconds at every minute past every 4th hour on every day-of-week from Tuesday through Friday in February, March, and April
@TimeZone: Time zone identifier, see next section
@IsActive: Flag indicating the job should run
@CallingUser: Audit data for who last modified the job record

👉 Only the Job Code parameter is required. This same procedure can be used to update subsets of Job configuration

6. Time Zones

When submitting a job, a NULL Time Zone will indicate that the Cron expression should be evaluated in UTC.

To use a different Time Zone, supply a zone name in the @TimeZone parameter. This will allow scheduling jobs to execute at a specific time in a specific time zone. For example, 11:30 PM in America/Los_Angeles

👉 Either Windows "Pacific Standard Time" or Olson "America/Los_Angeles" will work on either OS, but it is strongly recommended to use Olson timezone names. https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Product	Compatible and additional computed target framework versions.
.NET	net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net6.0
- CronExpressionDescriptor (>= 2.36.0)
- Hangfire (>= 1.8.15)
- Hangfire.AspNetCore (>= 1.8.15)
- Microsoft.SourceLink.Bitbucket.Git (>= 1.1.1)
- Plinth.AspNetCore (>= 1.7.1)
- Plinth.Common (>= 1.7.1)
- Plinth.Serialization (>= 1.7.1)
- System.Text.Json (>= 9.0.0)
net8.0
- CronExpressionDescriptor (>= 2.36.0)
- Hangfire (>= 1.8.15)
- Hangfire.AspNetCore (>= 1.8.15)
- Microsoft.SourceLink.Bitbucket.Git (>= 1.1.1)
- Plinth.AspNetCore (>= 1.7.1)
- Plinth.Common (>= 1.7.1)
- Plinth.Serialization (>= 1.7.1)
- System.Text.Json (>= 9.0.0)
net9.0
- CronExpressionDescriptor (>= 2.36.0)
- Hangfire (>= 1.8.15)
- Hangfire.AspNetCore (>= 1.8.15)
- Microsoft.SourceLink.Bitbucket.Git (>= 1.1.1)
- Plinth.AspNetCore (>= 1.7.1)
- Plinth.Common (>= 1.7.1)
- Plinth.Serialization (>= 1.7.1)
- System.Text.Json (>= 9.0.0)

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Plinth.Hangfire:

Package	Downloads
Plinth.Hangfire.MSSql Plinth Hangfire Utilities for SQL Server	33.5K
Plinth.Hangfire.PgSql Plinth Hangfire Utilities	23.0K

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last updated
1.7.1	130	12/12/2024
1.7.0	118	11/12/2024
1.6.6	116	11/8/2024
1.6.5	146	8/31/2024
1.6.4	124	8/2/2024
1.6.3	182	5/15/2024
1.6.2	176	2/16/2024
1.6.1	1,489	1/5/2024
1.6.0	234	11/30/2023
1.5.10-b186.aca976b4	80	11/30/2023
1.5.9	171	11/29/2023
1.5.9-b174.64153841	80	11/23/2023
1.5.9-b172.dfc6e7bd	71	11/17/2023
1.5.9-b171.4e2b92e2	91	11/4/2023
1.5.8	200	10/23/2023
1.5.7	747	7/31/2023
1.5.6	3,212	7/13/2023
1.5.5	260	6/29/2023
1.5.4	672	3/7/2023
1.5.3	395	3/3/2023
1.5.2	467	1/11/2023
1.5.2-b92.7c961f5f	124	1/11/2023
1.5.0	536	11/9/2022
1.5.0-b88.7a7c20cd	108	11/9/2022
1.4.7	1,486	10/20/2022
1.4.6	1,006	10/17/2022
1.4.5	865	10/1/2022
1.4.4	881	8/16/2022
1.4.3	884	8/2/2022
1.4.2	914	7/19/2022
1.4.2-b80.7fdbfd04	140	7/19/2022
1.4.2-b74.acaf86f5	127	6/15/2022
1.4.1	943	6/13/2022
1.4.0	910	6/6/2022
1.3.8	1,309	4/12/2022
1.3.7	916	3/21/2022
1.3.6	937	3/17/2022
1.3.6-b67.ca5053f3	145	3/16/2022
1.3.6-b66.4a9683e6	145	3/16/2022
1.3.5	943	2/23/2022
1.3.4	959	1/20/2022
1.3.3	709	12/29/2021
1.3.2	673	12/11/2021
1.3.1	584	11/12/2021
1.3.0	581	11/8/2021
1.2.3	1,774	9/22/2021
1.2.2	615	8/20/2021
1.2.1	666	8/5/2021
1.2.0	706	8/1/2021
1.2.0-b37.a54030b9	172	6/24/2021
1.1.6	1,989	3/22/2021
1.1.5	726	3/9/2021
1.1.4	702	2/27/2021
1.1.3	679	2/17/2021
1.1.2	688	2/12/2021
1.1.1	1,015	2/1/2021
1.1.0	806	12/16/2020
1.1.0-b27.b66c309b	286	11/15/2020
1.0.12	886	10/18/2020
1.0.11	811	10/6/2020
1.0.10	764	9/30/2020
1.0.9	741	9/29/2020
1.0.8	952	9/26/2020
1.0.7	910	9/19/2020
1.0.6	873	9/3/2020
1.0.5	793	9/2/2020
1.0.4	1,203	9/1/2020
1.0.3	816	9/1/2020
1.0.2	862	8/29/2020
1.0.1	873	8/29/2020
1.0.0	774	8/29/2020
1.0.0-b1.c22f563d	245	8/28/2020

net9.0 support

Total 48.3K

Current version 130

Per day average 30

Plinth Hangfire Job Scheduler