Plinth.Hangfire 1.4.5

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Plinth.Hangfire --version 1.4.5
NuGet\Install-Package Plinth.Hangfire -Version 1.4.5
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.4.5" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Plinth.Hangfire --version 1.4.5
#r "nuget: Plinth.Hangfire, 1.4.5"
#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.4.5

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

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

👉 If using .NET Core 3.1, you must use Windows timezone names on Windows, and Olson timezone names on Linux.
👉 For .NET 6, either 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 net5.0 was computed.  net5.0-windows was computed.  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 was computed.  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. 
.NET Core netcoreapp3.1 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 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.6.2 113 2/16/2024
1.6.1 234 1/5/2024
1.6.0 181 11/30/2023
1.5.10-b186.aca976b4 56 11/30/2023
1.5.9 127 11/29/2023
1.5.9-b174.64153841 66 11/23/2023
1.5.9-b172.dfc6e7bd 56 11/17/2023
1.5.9-b171.4e2b92e2 74 11/4/2023
1.5.8 139 10/23/2023
1.5.7 373 7/31/2023
1.5.6 1,979 7/13/2023
1.5.5 213 6/29/2023
1.5.4 629 3/7/2023
1.5.3 336 3/3/2023
1.5.2 421 1/11/2023
1.5.2-b92.7c961f5f 110 1/11/2023
1.5.0 492 11/9/2022
1.5.0-b88.7a7c20cd 94 11/9/2022
1.4.7 1,438 10/20/2022
1.4.6 959 10/17/2022
1.4.5 807 10/1/2022
1.4.4 830 8/16/2022
1.4.3 835 8/2/2022
1.4.2 859 7/19/2022
1.4.2-b80.7fdbfd04 126 7/19/2022
1.4.2-b74.acaf86f5 113 6/15/2022
1.4.1 867 6/13/2022
1.4.0 864 6/6/2022
1.3.8 1,243 4/12/2022
1.3.7 869 3/21/2022
1.3.6 889 3/17/2022
1.3.6-b67.ca5053f3 123 3/16/2022
1.3.6-b66.4a9683e6 131 3/16/2022
1.3.5 892 2/23/2022
1.3.4 900 1/20/2022
1.3.3 621 12/29/2021
1.3.2 622 12/11/2021
1.3.1 534 11/12/2021
1.3.0 524 11/8/2021
1.2.3 1,719 9/22/2021
1.2.2 564 8/20/2021
1.2.1 610 8/5/2021
1.2.0 647 8/1/2021
1.2.0-b37.a54030b9 157 6/24/2021
1.1.6 1,922 3/22/2021
1.1.5 673 3/9/2021
1.1.4 649 2/27/2021
1.1.3 628 2/17/2021
1.1.2 645 2/12/2021
1.1.1 961 2/1/2021
1.1.0 755 12/16/2020
1.1.0-b27.b66c309b 273 11/15/2020
1.0.12 842 10/18/2020
1.0.11 758 10/6/2020
1.0.10 715 9/30/2020
1.0.9 696 9/29/2020
1.0.8 904 9/26/2020
1.0.7 860 9/19/2020
1.0.6 796 9/3/2020
1.0.5 753 9/2/2020
1.0.4 1,145 9/1/2020
1.0.3 774 9/1/2020
1.0.2 811 8/29/2020
1.0.1 814 8/29/2020
1.0.0 733 8/29/2020
1.0.0-b1.c22f563d 232 8/28/2020

added detailed readme