BackgroundTasks: Creating your own task

Samples

Simple background task

Types

Metadata

Metadata is used as a request for running background tasks. Create type, implementing IBackgroundTaskMetadata

ExecutionMetadata

Execution metadata used for restoring task's execution progress from the point it was suspended.

Suspension can occur when task execution is cancelled due to application shutdown (when OperationCancelledException or TaskCancelledException is thrown).

In this case, execution metadata is persisted and would be loaded when task execution proceeds (when application is restarted).

You can use mutable model as execution metadata, modifying it as the execution process goes.

To avoid repeating operation execution (ensuring idempotency) modify execution metadata only when changes are persisted, ex: transaction is committed and you update page token of some long running operation.

If your background task has no specific execution metadata, you should use EmptyExecutionMetadata type.

Results

If your task yields some result at the end of its execution, you can create type, implementing IBackgroundTaskResult, otherwise, if task yields no result, you should use EmptyExecutionResult type

Errors

If you want to emit custom errors during task execution, you can create type, implementing IBackgroundTaskError, otherwise, if your business logic does not account for custom errors, you should use EmptyError type

Task handler implementation

Create type, implementing IBackgroundTask<,,,> and specify metadata, execution metadata, result and error as generic arguments

public class ExampleBackgroundTask : IBackgroundTask<
    EmptyMetadata,
    EmptyExecutionMetadata,
    EmptyExecutionResult,
    EmptyError>
{
    ...
}

Add background task name

public static string Name => nameof(ExampleBackgroundTask);

And implement ExecuteAsync method

public Task<BackgroundTaskExecutionResult<EmptyExecutionResult, EmptyError>> ExecuteAsync(
        BackgroundTaskExecutionContext<EmptyMetadata, EmptyExecutionMetadata> executionContext,
        CancellationToken cancellationToken)

BackgroundTaskExecutionResult helpers

Task execution has to finish with one of the certain results (success, suspended, failure, cancellation)

To return there values, use special static helper class - BackgroundTaskExecutionResult

It provides builders for the results. These builders has two kinds of methods With* and For*.

The difference between them, is that With* methods used for parameters, that expect values, and For* methods, used to specify type arguments (for type inference).

These method's semantics are explained for each result builder in the following section.

Success

BackgroundTaskExecutionResult.Success.WithResult(EmptyExecutionResult.Value).ForError<EmptyError>();

As success result expects a result object, method WithResult is used to specify result part of task execution result.
As success result does not expect error, method ForError is used to specify error type, without returning any error.

Alternatively, if you have empty result, or empty error, you can use methods WithEmptyResult and ForEmptyError respectively.

Suspended

BackgroundTaskExecutionResult.Suspended.ForResult<EmptyExecutionResult>().ForError<EmptyError>();

As suspended result does not expect a result object, method ForResult is used to specify result type, without returning any value.
As suspended result does not expect error, method ForError is used to specify error type, without returning any error.

Alternatively, if you have empty result, or empty error, you can use methods ForEmptyResult and ForEmptyError respectively.

Failure

BackgroundTaskExecutionResult.Failure.ForResult<EmptyExecutionResult>().WithError(EmptyError.Value);

As failure result does not expect a result object, method ForResult is used to specify result type, without returning any value. As failure result expects a possible error, method WithError is used to specify error part of task execution result.

Alternatively, if you have empty result, or empty error, you can use methods ForEmptyResult and WithEmptyError respectively.

Cancellation

BackgroundTaskExecutionResult.Cancellation.ForResult<EmptyExecutionResult>().WithError(EmptyError.Value);

As cancellation result does not expect a result object, method ForResult is used to specify result type, without returning any value. As cancellation result expects a possible error, method WithError is used to specify error part of task execution result.