RabbitMQ Background Job Manager

RabbitMQ is an industry standard message broker. While it is typically used for inter-process communication (messaging / distributed events), it is pretty useful to store and execute background jobs in FIFO (First In First Out) order.

ABP Framework provides the Volo.Abp.BackgroundJobs.RabbitMQ NuGet package to use the RabbitMQ for background job execution.

See the background jobs document to learn how to use the background job system. This document only shows how to install and configure the RabbitMQ integration.

Installation

Use the ABP CLI to add Volo.Abp.BackgroundJobs.RabbitMQ NuGet package to your project:

• Install the ABP CLI if you haven't installed before.
• Open a command line (terminal) in the directory of the .csproj file you want to add the Volo.Abp.BackgroundJobs.RabbitMQ package.
• Run abp add-package Volo.Abp.BackgroundJobs.RabbitMQ command.

If you want to do it manually, install the Volo.Abp.BackgroundJobs.RabbitMQ NuGet package to your project and add [DependsOn(typeof(AbpBackgroundJobsRabbitMqModule))] to the ABP module class inside your project.

Configuration

Default Configuration

The default configuration automatically connects to the local RabbitMQ server (localhost) with the standard port. In this case, no configuration needed.

RabbitMQ Connection(s)

You can configure the RabbitMQ connections using the standard configuration system, like using the appsettings.json file, or using the options classes.

appsettings.json file configuration

This is the simplest way to configure the RabbitMQ connections. It is also very strong since you can use any other configuration source (like environment variables) that is supported by the AspNet Core.

Example: Configuring the Default RabbitMQ Connection

{
  "RabbitMQ": {
    "Connections": {
      "Default": {
        "HostName": "123.123.123.123",
        "Port": "5672"
      }
    }
  }
}

You can use any of the ConnectionFactry properties as the connection properties. See the RabbitMQ document to understand these options better.

Defining multiple connections is allowed. In this case, you can use different connections for different background job types (see the AbpRabbitMqBackgroundJobOptions section below).

Example: Declare two connections

{
  "RabbitMQ": {
    "Connections": {
      "Default": {
        "HostName": "123.123.123.123"
      },
      "SecondConnection": {
        "HostName": "321.321.321.321"
      }
    }
  }
}

If you need to connect to the RabbitMQ cluster, you can use the ; character to separate the host names.

Example: Connect to the RabbitMQ cluster

{
  "RabbitMQ": {
    "Connections": {
      "Default": {
        "HostName": "123.123.123.123;234.234.234.234"
      }
    },
    "EventBus": {
      "ClientName": "MyClientName",
      "ExchangeName": "MyExchangeName"
    }
  }
}

AbpRabbitMqOptions

AbpRabbitMqOptions class can be used to configure the connection strings for the RabbitMQ. You can configure this options inside the ConfigureServices of your module.

Example: Configure the connection

Configure<AbpRabbitMqOptions>(options =>
{
    options.Connections.Default.UserName = "user";
    options.Connections.Default.Password = "pass";
    options.Connections.Default.HostName = "123.123.123.123";
    options.Connections.Default.Port = 5672;
});

Using these options classes can be combined with the appsettings.json way. Configuring an option property in the code overrides the value in the configuration file.

AbpRabbitMqBackgroundJobOptions

Job Queue Names

By default, each job type uses a separate queue. Queue names are calculated by combining a standard prefix and the job name. Default prefix is AbpBackgroundJobs. So, if the job name is EmailSending then the queue name in the RabbitMQ becomes AbpBackgroundJobs.EmailSending

Use BackgroundJobName attribute on the background job argument class to specify the job name. Otherwise, the job name will be the full name (with namespace) of the job class.

Job Connections

By default, all the job types use the Default RabbitMQ connection.

Customization

AbpRabbitMqBackgroundJobOptions can be used to customize the queue names and the connections used by the jobs.

Example:

Configure<AbpRabbitMqBackgroundJobOptions>(options =>
{
    options.DefaultQueueNamePrefix = "my_app_jobs.";
    options.DefaultDelayedQueueNamePrefix = "my_app_jobs.delayed"
    options.PrefetchCount = 1;
    options.JobQueues[typeof(EmailSendingArgs)] =
        new JobQueueConfiguration(
            typeof(EmailSendingArgs),
            queueName: "my_app_jobs.emails",
            connectionName: "SecondConnection",
            delayedQueueName:"my_app_jobs.emails.delayed"
        );
});

• This example sets the default queue name prefix to my_app_jobs. and default delayed queue name prefix to my_app_jobs.delayed. If different applications use the same RabbitMQ server, it would be important to use different prefixes for each application to not consume jobs of each other.
• Sets PrefetchCount for all queues.
• Also specifies a different connection string for the EmailSendingArgs.

JobQueueConfiguration class has some additional options in its constructor;

• queueName: The queue name that is used for this job. The prefix is not added, so you need to specify the full name of the queue.
• DelayedQueueName: The delayed queue name that is used for delayed execution of job. The prefix is not added, so you need to specify the full name of the queue.
• connectionName: The RabbitMQ connection name (see the connection configuration above). This is optional and the default value is Default.
• durable (optional, default: true).
• exclusive (optional, default: false).
• autoDelete (optional, default: false).
• PrefetchCount (optional, default: null)

See the RabbitMQ documentation if you want to understand the durable, exclusive and autoDelete options better, while most of the times the default configuration is what you want.

See Also

• Background Jobs