Skip to main content

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​

  1. ContinueJobWith creates the child job in the Awaiting state (AwaitingState). The state records the parent ID, the state to move to when the condition is met (NextState, Enqueued by default) and the JobContinuationOptions.
  2. The ContinuationsSupportAttribute filter, registered globally by default, adds the child's ID to the parent's Continuations job parameter. It takes a distributed lock on the parent while it does so. If the parent does not exist, creation fails with an exception.
  3. If the parent has already finished, the child is decided right away. Otherwise it waits.
  4. When the parent moves to Succeeded or Deleted, the filter looks at every waiting child. A child whose options accept that outcome moves to its next state; the others move to Deleted with the reason "Continuation condition was not met".
  5. 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:

OverloadLambda typesDefaults
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 fourNext state Enqueued when null; queue is stored with the child

Static methods on BackgroundJob:

OverloadLambda 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.

ValueNumberThe child starts when the parent is
OnlyOnSucceededState1Succeeded (the default)
OnlyOnDeletedState2Deleted
OnAnyFinishedState0Succeeded or Deleted
OnlyOnFailedState4Failed for good, with no retry left
OnlyOnProcessingState8Processing: 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​

MemberTypeMeaning
AwaitingState(string parentId)constructorNext state Enqueued, OnAnyFinishedState
AwaitingState(string parentId, IState nextState)constructorOnAnyFinishedState
AwaitingState(string parentId, IState nextState, JobContinuationOptions options)constructor
ParentIdstringThe parent job
NextStateIStateThe state the child moves to when the condition is met
OptionsJobContinuationOptionsWhich outcomes count
StateNamestring"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:

AttributeFills the parameter withParameter type
[FromResult] (FromResultAttribute)The parent's return value (job parameter AntecedentResult), when the parent succeededThe 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 OperationCanceledExceptionExceptionInfo (has Type, Message, InnerException)
[FromParameter("name")] (FromParameterAttribute)The value of the child's own job parameter name, read with your serializer settingsAny 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. Enqueue and friends return string?, and ContinueJobWith needs a real ID. Check first, as in the examples. (Fan-in methods skip null parent IDs instead, see Fan-in and batches.)
  • The parent must still exist. A continuation for an expired or unknown parent fails with BackgroundJobClientException; its inner InvalidOperationException says "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 with OnlyOnFailedState. 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 longer Awaiting. 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.
  • NextState is 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​