ASP.NET Core Applications
Before we start with our tutorial, we need to have a working ASP.NET Core application. This documentation is devoted to Hangfire, please, read the official ASP.NET Core Documentation to learn the details on how to create and initialize a new web application: Getting Started and Tutorials.
Hangfire is available as a set of NuGet packages, so you need to add them to the
*.csproj file by adding new
PackageReference tags as below. 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.
Creating a database
As you can see from the snippet above, we'll be using SQL Server as a job storage in this article. Before configuring Hangfire, you'll need to create a database for it or use an existing one. Configuration strings below point to the
HangfireTest database living in the
SQLEXPRESS instance on a local machine.
You can use SQL Server Management Studio or any other way to execute the following SQL command. If you are using other database name or instance, ensure you've changed connection strings when configuring Hangfire during the next steps.
CREATE DATABASE [HangfireTest] GO
We'll start our configuration process with defining configuration string for
Hangfire.SqlServer package. Consider you have an
sqlexpress named instance running on localhost, and just created the "HangfireTest" database. Current user *hould be able to create tables, to allow automatic migrations to do their job.
Hangfire.AspNetCore package has a logging integration with ASP.NET Core applications. Hangfire's log messages sometimes very important and help to diagnose different issues.
Information level allows to see how Hangfire is working, and
Warning and upper log level help to investigate problems.
appsettings.json file, and add the highlighted lines from the following snippet.
After updating the application settings, open the
Startup.cs file. Startup class is the heart of ASP.NET Core application's configuration. First we need to import the
Dependency Injection is one of the primary techniques introduced in ASP.NET Core.
Hangfire.AspNetCore integration package adds an extension method to register all the services, their implementation, as well as logging and job activator. As a parameter, it takes an action that allows to configure Hangfire itself.
Configuration settings below for new installations only
Some of those settings can be incompatible with existing installations, please see the :doc:`Upgrade Guides <../upgrade-guides/index>` instead when upgrading to a newer version.
Adding Dashboard UI
After registering Hangfire types, you can now choose features you need to add to your application. The following snippet shows you how to add the Dashboard UI to use all the Hangfire features immediately. The following lines are fully optional, and you can remove them completely, if your application will only create background jobs, while separate application will process them.
Authorization configuration required for non-local requests
By default only local access is permitted to the Hangfire Dashboard. Dashboard authorization must be configured in order to allow remote access.
Run the following command in to to start an application, or click the F5 button in Visual Studio.
After application is started, the following messages should appear, if background processing was started successfully. These lines contain messages regarding SQL Server Job Storage that is used to persist background jobs, and Background Job Server, that's processing all the background jobs.
info: Hangfire.SqlServer.SqlServerStorage Start installing Hangfire SQL objects... Hangfire SQL objects installed. Using job storage: 'SQL Server: .\@AspNetCoreTest' Using the following options for SQL Server job storage: Queue poll interval: 00:00:15. info: Hangfire.BackgroundJobServer Starting Hangfire Server... Using the following options for Hangfire Server: Worker count: 20 Listening queues: 'default' Shutdown timeout: 00:00:15 Schedule polling interval: 00:00:15
The following message should also appear, since we created background job, whose only behavior is to write a message to the console.
Hello world from Hangfire!
When application is started, open the following URL (assuming your app is running on the 5000 port) to access to the Hangfire Dashboard interface. As we can see, our background job was completed successfully.
When you finished working with the application, press the Ctrl+C in your console window to stop the application. The following message should appear telling you that background processing server was stopped gracefully.
info: Hangfire.BackgroundJobServer Hangfire Server stopped.
You can also kill your process, but in this case some background jobs may be delayed in invocation.