Continuations
A continuation is a job that waits for another job (its parent) to finish, then starts. Use it to build simple workflows: charge the card, then ship, then send the receipt; or run clean-up code only when a job was deleted. To wait for several parents at once, see Fan-in and batches.
Quick example
using Masterly.NightShift;
public class OrderService
{
public Task ChargeAsync(int orderId) => Task.CompletedTask;
}
public class EmailService
{
public void SendReceipt(int orderId)
{
// send the receipt
}
}
string? chargeId = jobs.Enqueue<OrderService>(x => x.ChargeAsync(orderId));
if (chargeId != null)
{
jobs.ContinueJobWith<EmailService>(chargeId, x => x.SendReceipt(orderId));
}
jobs is an IBackgroundJobClient. With the static facade, call BackgroundJob.ContinueJobWith<EmailService>(chargeId, x => x.SendReceipt(orderId)).
How it works
ContinueJobWithcreates the child job in theAwaitingstate (AwaitingState). The state records the parent ID, the state to move to when the condition is met (NextState,Enqueuedby default) and theJobContinuationOptions.- The
ContinuationsSupportAttributefilter, registered globally by default, adds the child's ID to the parent'sContinuationsjob parameter. It takes a distributed lock on the parent while it does so. If the parent does not exist, creation fails with an exception. - If the parent has already finished, the child is decided right away. Otherwise it waits.
- When the parent moves to
SucceededorDeleted, the filter looks at every waiting child. A child whose options accept that outcome moves to its next state; the others move toDeletedwith the reason "Continuation condition was not met". - When the parent fails for good (no retry left) or starts processing, only the children that ask for that (
OnlyOnFailedState,OnlyOnProcessingState) start; the others keep waiting.
Failed is not a finished state. A parent that failed and is out of retries keeps its other children waiting until someone requeues it (then it can succeed) or deletes it.
The child gets its parent's ID in the ParentId job parameter, written with the child, and reads it as PerformContext.ParentId. A fan-in continuation has its parents in ParentIds (PerformContext.ParentIds).
Continuations appear on the dashboard's Awaiting jobs page, and the job details page draws the chain of parents and children.
API
ContinueJobWith
Every overload returns string?: the child's ID, or null when a client filter canceled the creation. parentId must be the ID of an existing job.
Extension methods on IBackgroundJobClient:
| Overload | Lambda types | Defaults |
|---|---|---|
ContinueJobWith(parentId, methodCall) | Action, Action<T> | Next state Enqueued, OnlyOnSucceededState |
ContinueJobWith(parentId, methodCall, JobContinuationOptions options) | Action, Action<T> | Next state Enqueued |
ContinueJobWith(parentId, methodCall, IState nextState) | Action, Action<T> | OnlyOnSucceededState |
ContinueJobWith(parentId, methodCall, IState nextState, JobContinuationOptions options) | Action, Action<T> | None |
ContinueJobWith(parentId, methodCall, IState? nextState = null, JobContinuationOptions options = OnlyOnSucceededState) | Func<Task>, Func<T, Task> | Next state Enqueued when null |
ContinueJobWith(parentId, string queue, methodCall, IState? nextState = null, JobContinuationOptions options = OnlyOnSucceededState) | all four | Next state Enqueued when null; queue is stored with the child |
Static methods on BackgroundJob:
| Overload | Lambda types |
|---|---|
ContinueJobWith(parentId, methodCall) | Action, Action<T> |
ContinueJobWith(parentId, methodCall, JobContinuationOptions options) | Action, Action<T> |
ContinueJobWith(parentId, methodCall, JobContinuationOptions options = OnlyOnSucceededState) | Func<Task>, Func<T, Task> |
ContinueJobWith(parentId, string queue, methodCall, JobContinuationOptions options = OnlyOnSucceededState) | all four |
The static facade has no nextState overloads; use IBackgroundJobClient for those. Hangfire's older ContinueWith methods are gone: call ContinueJobWith with the same arguments.
JobContinuationOptions
A [Flags] enum that says which outcomes of the parent start the child.
| Value | Number | The child starts when the parent is |
|---|---|---|
OnlyOnSucceededState | 1 | Succeeded (the default) |
OnlyOnDeletedState | 2 | Deleted |
OnAnyFinishedState | 0 | Succeeded or Deleted |
OnlyOnFailedState | 4 | Failed for good, with no retry left |
OnlyOnProcessingState | 8 | Processing: the child runs alongside its parent |
OnlyOnSucceededState | OnlyOnDeletedState means the same as OnAnyFinishedState. The flags combine: OnlyOnSucceededState | OnlyOnFailedState starts the child when the parent succeeds or fails. When the parent finishes (Succeeded or Deleted), a child whose options don't accept that outcome is deleted; when it fails or starts processing, such a child keeps waiting, as the parent may still succeed.
A child added after its parent reached the state it asks for starts at once: OnlyOnFailedState for a failed parent, OnlyOnProcessingState for a parent that is processing, succeeded or failed. With UseResultsInContinuations(), a failed parent's exception reaches [FromException].
AwaitingState
| Member | Type | Meaning |
|---|---|---|
AwaitingState(string parentId) | constructor | Next state Enqueued, OnAnyFinishedState |
AwaitingState(string parentId, IState nextState) | constructor | OnAnyFinishedState |
AwaitingState(string parentId, IState nextState, JobContinuationOptions options) | constructor | |
ParentId | string | The parent job |
NextState | IState | The state the child moves to when the condition is met |
Options | JobContinuationOptions | Which outcomes count |
StateName | string | "Awaiting" |
The constructors without options default to OnAnyFinishedState, as they always have, unlike ContinueJobWith, which defaults to OnlyOnSucceededState. Pass the options when you create an AwaitingState yourself.
Passing the parent's result or exception
A continuation can receive what its parent returned, or the exception that deleted it. Turn the feature on once at startup:
services.AddNightShift(config => config
.UseResultsInContinuations()
.UseSqlServerStorage(connectionString));
UseResultsInContinuations() replaces the default continuation filter with one that copies the parent's outcome into the child's job parameters, and adds JobParameterInjectionFilter, which fills marked method parameters from job parameters just before the job runs.
The attributes are in the Masterly.NightShift namespace and go on parameters of the continuation's method:
| Attribute | Fills the parameter with | Parameter type |
|---|---|---|
[FromResult] (FromResultAttribute) | The parent's return value (job parameter AntecedentResult), when the parent succeeded | The parent's return type, or a type its JSON can be read as |
[FromException] (FromExceptionAttribute) | The exception that deleted the parent (job parameter AntecedentException). When the parent was deleted without an exception (by Delete, from the dashboard), an OperationCanceledException | ExceptionInfo (has Type, Message, InnerException) |
[FromParameter("name")] (FromParameterAttribute) | The value of the child's own job parameter name, read with your serializer settings | Any type the value can be read as |
FromResultAttribute and FromExceptionAttribute are FromParameterAttribute with the names AntecedentResult and AntecedentException. [FromParameter] works on any job, not only continuations, once UseResultsInContinuations() has registered the injection filter; see Job arguments.
When the job parameter is missing, the parameter keeps the value given in the lambda, so pass a placeholder such as default or null there. Without UseResultsInContinuations() nothing is filled in and the placeholder is what the method receives.
More examples
A chain of steps
string? charge = jobs.Enqueue<OrderService>(x => x.ChargeAsync(orderId));
string? ship = charge == null ? null : jobs.ContinueJobWith<OrderService>(charge, x => x.ShipAsync(orderId));
if (ship != null)
{
jobs.ContinueJobWith<EmailService>(ship, x => x.SendReceipt(orderId));
}
If the charge is deleted, the shipping job is deleted with "Continuation condition was not met", and the receipt job after it is deleted too.
Compensation when a job is deleted
jobs.ContinueJobWith<OrderService>(
chargeId,
x => x.ReleaseStock(orderId),
JobContinuationOptions.OnlyOnDeletedState);
A job is deleted when someone deletes it, or when AutomaticRetry runs out of attempts and its OnAttemptsExceeded is AttemptsExceededAction.Delete. With the default (Fail) the parent stays Failed and this continuation keeps waiting. See Retries.
Run whatever happens
jobs.ContinueJobWith<OrderService>(
chargeId,
x => x.ReleaseStock(orderId),
JobContinuationOptions.OnAnyFinishedState);
On another queue
jobs.ContinueJobWith<EmailService>(chargeId, "emails", x => x.SendReceipt(orderId));
With a custom next state
using Masterly.NightShift.States;
jobs.ContinueJobWith<OrderService>(
chargeId,
x => x.ShipAsync(orderId),
new EnqueuedState("shipping"),
JobContinuationOptions.OnlyOnSucceededState);
Using the parent's result
public class ImportService
{
public Task<int> ImportAsync(string fileName)
{
// import the rows and return how many there were
return Task.FromResult(42);
}
}
public class ImportReport
{
public void Send(string fileName, [FromResult] int rowsImported)
{
// e-mail "42 rows imported from customers.csv"
}
public void SendFailure(string fileName, [FromException] ExceptionInfo? error)
{
// e-mail error?.Message
}
}
string? importId = jobs.Enqueue<ImportService>(x => x.ImportAsync(fileName));
if (importId != null)
{
jobs.ContinueJobWith<ImportReport>(importId, x => x.Send(fileName, default));
jobs.ContinueJobWith<ImportReport>(
importId,
x => x.SendFailure(fileName, null),
JobContinuationOptions.OnlyOnDeletedState);
}
This needs UseResultsInContinuations(). For an async parent, the result is the value of its Task<T>.
Things to know
- The parent ID must not be
null.Enqueueand friends returnstring?, andContinueJobWithneeds a real ID. Check first, as in the examples. (Fan-in methods skipnullparent IDs instead, see Fan-in and batches.) - The parent must still exist. A continuation for an expired or unknown parent fails with
BackgroundJobClientException; its innerInvalidOperationExceptionsays "parent background job ... does not exist". Finished jobs expire after one day by default. - Failed parents block. Continuations wait while the parent is
Failed, except those withOnlyOnFailedState. Requeue or delete the parent to decide the others. - A processing continuation starts once, the first time the parent starts processing. A retry of the parent doesn't start it again.
- A continuation can start just before its parent's final state is stored. The children are moved to their next state while the parent's new state is chosen, before it is committed. A worker can pick a child up a moment before the parent shows
Succeeded, so don't make the child read its parent's state and expect it final; pass what it needs with[FromResult]or as arguments. If that commit then fails, the children have started anyway: the parent's state change is retried, or the parent runs again, but its continuations don't start a second time, because they are no longerAwaiting. Deciding after the commit would avoid this, but a crash between the commit and the decision would leave the children waiting forever, which is worse. Fan-in continuations decide after the commit instead. NextStateis created now. The state object you pass is stored when the child is created.new ScheduledState(TimeSpan.FromMinutes(5))computes its moment at that point, not when the parent finishes, so after a long parent the child is enqueued at once.- Results are serialized. A return value that can't be serialized is stored as the text "Can not serialize the return value", and
[FromResult]can't read it. Return small, serializable values; see Job arguments. - Each continuation is a full job. It has its own retries, filters and queue.
See also
- Fan-in and batches
- Chains
- Fire-and-forget jobs
- Managing jobs
- Retries
- Global configuration (
UseResultsInContinuations)