Plinth.Hangfire 1.5.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
.NET 6.0
dotnet add package Plinth.Hangfire --version 1.5.0
NuGet\Install-Package Plinth.Hangfire -Version 1.5.0
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.5.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Plinth.Hangfire --version 1.5.0
#r "nuget: Plinth.Hangfire, 1.5.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. 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.5.0

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

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 Versions
.NET net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
Compatible target framework(s)
Additional computed target framework(s)
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 The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Plinth Hangfire Utilities for SQL Server

Plinth.Hangfire.PgSql The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Plinth Hangfire Utilities

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.5.0 91 11/9/2022
1.5.0-b88.7a7c20cd 32 11/9/2022
1.4.7 244 10/20/2022
1.4.6 334 10/17/2022
1.4.5 277 10/1/2022
1.4.4 272 8/16/2022
1.4.3 277 8/2/2022
1.4.2 323 7/19/2022
1.4.2-b80.7fdbfd04 75 7/19/2022
1.4.2-b74.acaf86f5 61 6/15/2022
1.4.1 336 6/13/2022
1.4.0 334 6/6/2022
1.3.8 719 4/12/2022
1.3.7 325 3/21/2022
1.3.6 339 3/17/2022
1.3.6-b67.ca5053f3 68 3/16/2022
1.3.6-b66.4a9683e6 61 3/16/2022
1.3.5 333 2/23/2022
1.3.4 353 1/20/2022
1.3.3 333 12/29/2021
1.3.2 397 12/11/2021
1.3.1 304 11/12/2021
1.3.0 303 11/8/2021
1.2.3 1,498 9/22/2021
1.2.2 349 8/20/2021
1.2.1 370 8/5/2021
1.2.0 406 8/1/2021
1.2.0-b37.a54030b9 105 6/24/2021
1.1.6 1,580 3/22/2021
1.1.5 455 3/9/2021
1.1.4 427 2/27/2021
1.1.3 397 2/17/2021
1.1.2 417 2/12/2021
1.1.1 749 2/1/2021
1.1.0 521 12/16/2020
1.1.0-b27.b66c309b 227 11/15/2020
1.0.12 608 10/18/2020
1.0.11 511 10/6/2020
1.0.10 490 9/30/2020
1.0.9 479 9/29/2020
1.0.8 684 9/26/2020
1.0.7 621 9/19/2020
1.0.6 559 9/3/2020
1.0.5 559 9/2/2020
1.0.4 920 9/1/2020
1.0.3 566 9/1/2020
1.0.2 582 8/29/2020
1.0.1 571 8/29/2020
1.0.0 476 8/29/2020
1.0.0-b1.c22f563d 195 8/28/2020

net7.0 support and removed netcoreapp3.1