Skip to content

Commit

Permalink
more docs
Browse files Browse the repository at this point in the history
  • Loading branch information
mythz committed Sep 13, 2024
1 parent c7d2bb4 commit 09787bb
Showing 1 changed file with 73 additions and 9 deletions.
82 changes: 73 additions & 9 deletions MyApp/_pages/releases/v8_04.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ the following options:
- `ReplyTo` - Optional field for capturing where to send notification for completion of a Job
- `Args` - Optional String Dictionary of Arguments that can be attached to a Job

### Schedule Recurring Tasks
## Schedule Recurring Tasks

In addition to queueing jobs to run in the background, it also supports scheduling recurring tasks
to execute APIs or Commands at fixed intervals.
Expand All @@ -208,15 +208,73 @@ Schedule your Reoccurring Tasks with Background Jobs!
APIs and Commands can be scheduled to run at either a `TimeSpan` or
[CRON Expression](https://github.com/HangfireIO/Cronos?tab=readme-ov-file#cron-format) interval, e.g:


### CRON Expression Examples

```csharp
// Every Minute Expression
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.Cron("* * * * *"));
jobs.RecurringCommand<CheckUrlsCommand>(
Schedule.Interval(TimeSpan.FromMinutes(1)));

// Every Minute Constant
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.EveryMinute, new CheckUrls {
Urls = urls
});
```

### CRON Format

You can use any **unix-cron format** expression supported by the [HangfireIO/Cronos](https://github.com/HangfireIO/Cronos) library:

```txt
|------------------------------- Minute (0-59)
| |------------------------- Hour (0-23)
| | |------------------- Day of the month (1-31)
| | | |------------- Month (1-12; or JAN to DEC)
| | | | |------- Day of the week (0-6; or SUN to SAT; or 7 for Sunday)
| | | | |
| | | | |
* * * * *
```

The allowed formats for each field include:

| Field | Format of valid values |
|------------------|--------------------------------------------|
| Minute | 0-59 |
| Hour | 0-23 |
| Day of the month | 1-31 |
| Month | 1-12 (or JAN to DEC) |
| Day of the week | 0-6 (or SUN to SAT; or 7 for Sunday) |

#### Matching all values

To match all values for a field, use the asterisk: `*`, e.g here are two examples in which the minute field is left unrestricted:

- `* 0 1 1 1` - the job runs every minute of the midnight hour on January 1st and Mondays.
- `* * * * *` - the job runs every minute (of every hour, of every day of the month, of every month, every day of the week, because each of these fields is unrestricted too).

#### Matching a range

To match a range of values, specify your start and stop values, separated by a hyphen (-). Do not include spaces in the range. Ranges are inclusive. The first value must be less than the second.

The following equivalent examples run at midnight on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays (for all months):

- `0 0 * * 1-5`
- `0 0 * * MON-FRI`

#### Matching a list

Lists can contain any valid value for the field, including ranges. Specify your values, separated by a comma (,). Do not include spaces in the list, e.g:

- `0 0,12 * * *` - the job runs at midnight and noon.
- `0-5,30-35 * * * *` - the job runs in each of the first five minutes of every half hour (at the top of the hour and at half past the hour).

### TimeSpan Interval Examples

```csharp
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.Interval(TimeSpan.FromMinutes(1)));

// With Example
jobs.RecurringApi(Schedule.Interval(TimeSpan.FromMinutes(1)), new CheckUrls {
Urls = urls
});
Expand All @@ -235,13 +293,12 @@ jobs.RecurringCommand<CheckUrlsCommand>("Check URLs", Schedule.EveryMinute,
If no name is provided, the Command's Name or APIs Request DTO will be used
:::

### Idempotent Registration

Scheduled Tasks are idempotent where the same registration with the same name will
either create or update the scheduled task registration without losing track of the
last time the Recurring Task was run which is also viewable in the Jobs Admin UI:

![](/img/pages/jobs/jobs-scheduled-tasks-last-job.webp)

As such it's recommended to always define your App's Scheduled Tasks on Startup:
last time the Recurring Task, as such it's recommended to always define your App's
Scheduled Tasks on Startup:

```csharp
public class ConfigureBackgroundJobs : IHostingStartup
Expand All @@ -255,12 +312,19 @@ public class ConfigureBackgroundJobs : IHostingStartup
var services = appHost.GetApplicationServices();

var jobs = services.GetRequiredService<IBackgroundJobs>();
// Register Scheduled Tasks

// App's Scheduled Tasks Registrations:
jobs.RecurringCommand<MyCommand>(Schedule.Hourly);
});
}
```

### Background Jobs Admin UI

The last job the Recurring Task ran is also viewable in the Jobs Admin UI:

![](/img/pages/jobs/jobs-scheduled-tasks-last-job.webp)

### Executing non-durable jobs

`IBackgroundJobs` also supports `RunCommand` methods to be able to execute jobs transiently
Expand Down

0 comments on commit 09787bb

Please sign in to comment.