Scheduled Jobs

Scheduled jobs can execute code at regular intervals or at specific times on designated days.

Create a Scheduled Job

To create a scheduled job, define a new class that is tagged with the ServiceJob attribute and implements the IServiceJob interface.

Project.Services / Jobs / MyJob.cs

[ServiceJob("MyJobName", "Primary-Queue", "00:05:00")]
public class MyJob : IServiceJob
{
    public async Task<Response<object?>> Execute(JobServiceContext context)
    {
        var db = context.GetDbContext<DataContext>();
        // Do something
        return ServiceResult.Success();
    }
}

The ServiceJob attribute takes the following parameters.

Job Name: The name of the job as it will appear in the Admin Dashboard.
Queue: A queue executes one job at a time. Multiple jobs can run in parallel if they are assigned to different queues.
TimeSpan: When the JobSchedule is set to interval, this defines the time between executions. For example, a TimeSpan of "00:05:00" will trigger the job every 5 minutes. When JobSchedule is set to TimeOfDay, this represents the specific execution time in UTC. For instance, a TimeSpan of "05:00:00" will execute the job at 5:00 AM UTC.
Job Schedule: Defines when the job runs and can be either Interval or TimeOfDay.
Days of Week: Flags that specify which days of the week the job should execute.

Time of day example

Below is an example of a job that executes on Monday and Wednesday at 3:00 AM UTC:

Project.Services / Jobs / MyJob.cs

[ServiceJob("MyJobName", "Primary-Queue", "03:00:00", JobSchedule.TimeOfDay, DaysOfWeek.Monday | DaysOfWeek.Wednesday)]
public class MyJob : IServiceJob
{
    public async Task<Response<object?>> Execute(JobServiceContext context)
    {
        var db = context.GetDbContext<DataContext>();
        // Do something
        return ServiceResult.Success();
    }
}

Execute on one server only

In a multi-server environment, jobs execute on all servers by default. To ensure a job runs on only a single server, use the JobServer attribute with ExecuteJobOn.One.

Project.Services / Jobs / MyJob.cs

[JobServer(ExecuteJobOn.One)] // <-- add this
[ServiceJob("MyJobName", "Primary-Queue", "03:00:00", JobSchedule.TimeOfDay, DaysOfWeek.Monday | DaysOfWeek.Wednesday)]
public class MyJob : IServiceJob
{
    public async Task<Response<object?>> Execute(JobServiceContext context)
    {
        var db = context.GetDbContext<DataContext>();
        return ServiceResult.Success();
    }
}

When JobServer is set to ExecuteJobOn.One and no specific server is specified, the job will always execute on the server whose name comes first alphabetically. For example, if there are two servers named Alpha and Beta, the job will always run on Alpha because its name appears first in alphabetical order.

Execute on specific server only

In a multi-server environment, to ensure a job runs only on a specific server, provide the server name as the second parameter in the JobServer attribute.

Project.Services / Jobs / MyJob.cs

[JobServer(ExecuteJobOn.One, "Beta")] // <-- only run on server Beta
[ServiceJob("MyJobName", "Primary-Queue", "03:00:00", JobSchedule.TimeOfDay, DaysOfWeek.Monday | DaysOfWeek.Wednesday)]
public class MyJob : IServiceJob
{
    public async Task<Response<object?>> Execute(JobServiceContext context)
    {
        var db = context.GetDbContext<DataContext>();
        return ServiceResult.Success();
    }
}

To set the name of the server, use the SERVER_NAME environment variable.

Time Zone

To ensure a job executes at a consistent time within a specific time zone, regardless of daylight savings changes, use the JobTimeZone attribute.

Project.Services / Jobs / MyJob.cs

[JobTimeZone("Eastern Standard Time")] // <-- always run at 3am EST
[ServiceJob("MyJobName", "Primary-Queue", "03:00:00", JobSchedule.TimeOfDay, DaysOfWeek.Monday | DaysOfWeek.Wednesday)]
public class MyJob : IServiceJob
{
    public async Task<Response<object?>> Execute(JobServiceContext context)
    {
        var db = context.GetDbContext<DataContext>();
        return ServiceResult.Success();
    }
}