Upgrading to Hangfire 1.7¶

Backward Compatibility¶

Hangfire.Core, Hangfire.SqlServer:

New version can successfully process background jobs created with both Version_110 and Version_170 data compatibility levels. However if you change the UseSerializerSettings with incompatible options, the resulting behavior is undefined.

Hangfire.SqlServer:

All queries are backward compatible even with Schema 5 from versions 1.6.X, so you can run the schema migration manually after some time, for example during off-hours.

Forward Compatibility¶

Hangfire.Core, Hangfire.SqlServer:

Forward compatibility is supported on the CompatibilityLevel.Version_110 (default value) data compatibility level. In this case no data in the new format will be created in the storage, and servers of previous versions will be possible to handle the new data.

Hangfire.SqlServer:

Hangfire.SqlServer 1.6.23 is forward compatible with Schema 6 and Schema 7 schemas. Previous versions don’t support the new schemas and may lead to exceptions. Anyway it’s better to upgrade all your servers first, and only then apply the migration.

Breaking Changes in API¶

Unfortunately there’s need to update your code if you are using one of the following features during upgrade to the newest version. I understand such changes are not welcome when migrating between minor versions, but all of them are required to fix problems. These changes cover only the low level API surface and don’t relate to background jobs.

Hangfire.Core:

• Added IBackgroundJobFactory.StateMachine property to enable transactional behavior of RecurringJobScheduler.
• Changed the way of creating recurring job. CreatingContext.InitialState and CreatedContext.InitialState properties for IClientFilter implementations will return null now, instead of an actual value. Use IApplyStateFilter or IElectStateFilter to access that value.

Hangfire.AspNetCore:

• Removed registrations for IBackgroundJobFactory, IBackgroundJobPerformer and IBackgroundJobStateChanger interfaces. Custom implementations of these interfaces now applied only if all of them are registered. Previously it was unclear what JobActivator is used – from registered service or from options, and lead to errors.

Hangfire.SqlServer:

• IPersistentJobQueueMonitoringApi.Get**JobIds methods now return IEnumerable<long>. If you are using non-default persistent queue implementations, upgrade those packages as well. This change is required to handle bigger identifier format.

Breaking Changes in Code¶

There are no breaking changes for your background jobs in this release, unless you explicitly changed the following configuration options.

• IGlobalConfiguration.UseRecommendedSerializerSettings (disabled by default) may affect argument serialization and may be incompatible with your current JSON settings if you’ve changed them using the JobHelper.SetSerializerSettings method or DefaultValueAttribute on your argument classes or different date/time formats.
• Setting BackgroundJobServerOptions.TaskScheduler to null (TaskScheduler.Default is used by default) will force async continuations to be processed by the worker thread itself, reducing the number of required threads (that’s good). But if you are using non-recommended and dangerous Task.Result or Task.GetAwaiter().GetResult() methods, your async background jobs can be deadlocked.

1. Upgrading Packages¶

First upgrade all the packages without touching any new configuration and/or new features. Then deploy your application with the new version until all your servers are successfully migrated to the newer version. 1.6.X and 1.7.0 servers can co-exist in the same environment just fine, thanks to forward compatibility.

1. Upgrade your NuGet package references using your own preferred way. If you’ve referenced Hangfire using a single meta-package, just upgrade it:

   

   <PackageReference Include="Hangfire" Version="1.7.0" />
   

   If you reference individual packages upgrade them all, here is the full list of packages that come with this release. Please note that versions in the code snippet below may be outdated, so use versions from the following badges, they are updated in real-time.

   

   <PackageReference Include="Hangfire.Core" Version="1.7.0" />
   <PackageReference Include="Hangfire.AspNetCore" Version="1.7.0" />
   <PackageReference Include="Hangfire.SqlServer" Version="1.7.0" />
   <PackageReference Include="Hangfire.SqlServer.Msmq" Version="1.7.0" />
   

2. Fix breaking changes mentioned in the previous section if they apply to your use case.

3. (Optional) If your background processing sits mostly idle and you are already using Hangfire 1.6.23, you can run the schema migration for SQL Server during this step. Otherwise I’d highly encourage you to perform the migration manually as written in the following section, because it may take too long if there are outstanding queries.

   GlobalConfiguration.Configuration.UseSqlServerStorage("connection_string", new SqlServerStorageOptions
   {
       CommandBatchMaxTimeout = TimeSpan.FromMinutes(5),
       QueuePollInterval = TimeSpan.Zero,
       SlidingInvisibilityTimeout = TimeSpan.FromMinutes(5),
       UseRecommendedIsolationLevel = true,
       PrepareSchemaIfNecessary = true, // Default value: true
       EnableHeavyMigrations = true     // Default value: false
   });
   

4. Set the StopTimeout for your background processing servers to give your background jobs some time to be processed during the shutdown event, instead of instantly aborting them.

   new BackgroundJobServerOptions
   {
       StopTimeout = TimeSpan.FromSeconds(10)
   }
   

2. Migrating the Schema¶

Schema 6 and Schema 7 migrations that come with the new Hangfire.SqlServer package version will not be applied automatically, unless you set the EnableHeavyMigrations options as written above. This option was added to prevent uncontrolled upgrades that may lead to long downtime or deadlocks when applied in processing-heavy environments or during the peak load.

To perform the manual upgrade, obtain the DefaultInstall.sql migration script from the repository and wrap it with the lines below to reduce the migration downtime. Please note this will abort all the current transactions and prevent new ones from starting until the upgrade is complete, so it’s better to do it during off-hours.

ALTER DATABASE [HangfireDB] SET SINGLE_USER WITH ROLLBACK IMMEDIATE;

-- DefaultInstall.sql / Install.sql contents

ALTER DATABASE [HangfireDB] SET MULTI_USER;

If you are using non-default schema, please get the Install.sql file instead and replace all the occurrences of the $(HangFireSchema) token with your schema name without brackets.

3. Updating Configuration¶

When all your servers can understand the new features, you can safely enable them. The new version understands all the existing jobs even in previous data format, thanks to backward compatibility. All these settings are recommended, but optional – you can use whatever you have currently.

1. Set the new data compatibility level and type serializer to have more compact payloads for background jobs.

   GlobalConfiguration.Configuration
       // ...
       .SetDataCompatibilityLevel(CompatibilityLevel.Version_170)
       .UseSimpleAssemblyNameTypeSerializer();
   

2. If you don’t use custom JSON settings before by calling JobHelper.SetSerializerSettings or by using JsonConvert.DefaultOption or by using attributes on your job argument classes, you can set the recommended JSON options that lead to more compact payloads. Otherwise you can get breaking changes.

   GlobalConfiguration.Configuration
       // ...
       .UseRecommendedSerializerSettings();
   

   If you do use custom settings, you can call the UseSerializerSettings method instead:

   GlobalConfiguration.Configuration
       // ...
       .UseSerializerSettings(new JsonSerializerSettings { /* ... */ });
   

3. Update SQL Server options to have better locking scheme, more efficient dequeue when using Sliding Invisibility Timeout technique and disable heavy migrations in future to prevent accidental deadlocks.

   GlobalConfiguration.Configuration
       // ...
       .UseSqlServerStorage("connection_string", new SqlServerStorageOptions
       {
           // ...
           UsePageLocksOnDequeue = true,
           DisableGlobalLocks = true,
           EnableHeavyMigrations = false    // Default value: false
       });
   

After setting new configuration options, deploy the changes to your servers when needed.