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                
#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                

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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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

Plinth.Hangfire.PgSql

Plinth Hangfire Utilities

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.7.1 129 12/12/2024
1.7.0 117 11/12/2024
1.6.6 115 11/8/2024
1.6.5 145 8/31/2024
1.6.4 122 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,204 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 882 8/2/2022
1.4.2 912 7/19/2022
1.4.2-b80.7fdbfd04 140 7/19/2022
1.4.2-b74.acaf86f5 127 6/15/2022
1.4.1 941 6/13/2022
1.4.0 908 6/6/2022
1.3.8 1,307 4/12/2022
1.3.7 914 3/21/2022
1.3.6 935 3/17/2022
1.3.6-b67.ca5053f3 145 3/16/2022
1.3.6-b66.4a9683e6 145 3/16/2022
1.3.5 941 2/23/2022
1.3.4 957 1/20/2022
1.3.3 707 12/29/2021
1.3.2 671 12/11/2021
1.3.1 582 11/12/2021
1.3.0 579 11/8/2021
1.2.3 1,772 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