Class WorkerSystemBase<TDerived>

An abstract class that creates and runs a system of workers. Commonly used members include SetValue(String, Int64) configuration overloads and methods for adding worker system callbacks.

To create a custom reusable worker system type, inherit from this class and also override RunAsync() to provide your user logic, i.e. what you would otherwise use a Root(Action<WorkerSystem>) overload to provide.

To retain the Root(Action<WorkerSystem>) overloads, instead inherit from WorkerSystem.

Inheritance
Object
WorkerParent
WorkerSystemBase
WorkerSystemBase<TDerived>
WorkerSystem
Implements
Inherited Members
Namespace: actionETL
Assembly: actionETL.dll
Syntax
public abstract class WorkerSystemBase<TDerived> : WorkerSystemBase, IDisposeOnFinished where TDerived : WorkerSystemBase<TDerived>
Type Parameters
Name Description
TDerived

Constructors

WorkerSystemBase(String, IConfigurationService, IALogFactory)

Initializes a new instance of WorkerSystemBase<TDerived>, which is used to create and run a system of workers.

Declaration
protected WorkerSystemBase(string workerSystemName, IConfigurationService configurationService, IALogFactory logFactory)
Parameters
Type Name Description
String workerSystemName

Name of the worker system, which will be the first level of the Locator string.

Defaults to "Root" if set to null or whitespace.

Cannot contain "/", or start with double underscore "__".

IConfigurationService configurationService

The configuration service. If null, will look for the configuration file in the default locations.
IALogFactory logFactory

The log factory. If null, will look for the logging configuration file in the default locations.
Exceptions
Type Condition
Exception

(Various Newtonsoft.Json.JsonException license and configuration reading and parsing exceptions).
FormatException

File parse error.
IOException

An I/O error occurred.
InvalidOperationException
  • actionETL requires '.NET framework version 4.6.2' or later (available from Microsoft), please install this or a later version.
  • No license text found in file.
  • No valid license found.

Methods

AddCompletedCallback(Func<TDerived, OutcomeStatus, Task<OutcomeStatus>>)

Adds a callback which will be called as the last step of the worker system Running phase, which is after any children have completed. Multiple callbacks can be added.

These callbacks are useful for performing cleanup tasks. Also see DisposeOnFinished<TDisposable>(TDisposable) and UsingActionWorker<TDisposable> which are specifically for disposing resources.

If the worker system is started, these callbacks will run, even if earlier callbacks, or any children have failures. If multiple callbacks have been added, they will all be called (even if one fails) in the reverse order from they were added, e.g. callbacks from derived classes will be called before callbacks from base classes.

Each callback takes the worker system itself and the OutcomeStatus from previous steps (including any children) as parameters.

Note: Adding the callback is thread-safe.

Declaration
public TDerived AddCompletedCallback(Func<TDerived, OutcomeStatus, Task<OutcomeStatus>> completedFuncAsync)
Parameters
Type Name Description
Func<TDerived, OutcomeStatus, Task<OutcomeStatus>> completedFuncAsync

The asynchronous callback that will be called when the worker system has completed. See "Remarks" below for details.
Returns
Type Description
TDerived

The instance itself, so you can chain multiple calls.
Remarks

The callback takes two parameters:

TDerivedThe worker system itself
OutcomeStatusFrom previous execution steps (including any children)

The callback implementation is either synchronous and returns a Task<OutcomeStatus> explicitly, or is async and returns an OutcomeStatus.

  • To leave the OutcomeStatus unchanged, return the OutcomeStatus that was passed in as a parameter (and use ToTask() in synchronous callbacks).
  • To change the OutcomeStatus (e.g. changing Error to Succeeded), return a new OutcomeStatus instance. If appropriate, use Combine(Boolean, OutcomeStatus) to also retain the previous information, both of which the system will log.

If you only have access to the WorkerSystemBase type, use AddCompletedCallback(Func<WorkerSystemBase, OutcomeStatus, Task<OutcomeStatus>>) instead.

Examples

In this example we roll back a transaction on failure:

workerSystem.AddCompletedCallback((ws, outcomeStatus) =>
{
    if (!outcomeStatus.IsSucceeded)
        transaction?.Rollback();
    return outcomeStatus.ToTask();
});
Exceptions
Type Condition
ArgumentNullException

completedFuncAsync
InvalidOperationException

Cannot add 'Starting' callback after the worker system has completed.

AddStartingCallback(Func<TDerived, Task<ProgressStatus>>)

Adds a callback which will be called as the first step of the worker system Running phase, which is before Root(Action<WorkerSystem>) overloads and RunAsync() are called or worker children are started. Multiple callbacks can be added.

These callbacks are often used for initialization, or for adding child workers, e.g. from outside the worker system.

If the worker system is started, these callbacks will all run, even if some fail, in the order they were added, e.g. callbacks added in base classes will be called before callbacks added in derived classes.

The callback takes the worker system itself as a parameter.

Note: Adding the callback is thread-safe.

Declaration
public TDerived AddStartingCallback(Func<TDerived, Task<ProgressStatus>> startingFuncAsync)
Parameters
Type Name Description
Func<TDerived, Task<ProgressStatus>> startingFuncAsync

The asynchronous callback that will be called when the worker system has started. See "Remarks" below for details.
Returns
Type Description
TDerived

The instance itself, so you can chain multiple calls.
Remarks

The callback takes the worker system itself as a parameter.

The callback implementation is either synchronous and returns a Task<ProgressStatus> explicitly, or is async and returns a ProgressStatus.

The callback should return:

If you only have access to the WorkerSystemBase type, use AddStartingCallback(Func<WorkerSystemBase, Task<ProgressStatus>>) instead.

Examples

In this example we allocate a buffer:

workerSystem.AddStartingCallback(ws =>
{
    _buffer = new int[BufferSize];
    return ProgressStatus.NotCompletedTask;
});
Exceptions
Type Condition
ArgumentNullException

startingFuncAsync
InvalidOperationException

Cannot add 'Starting' callback after the worker system has started running.

SetValue(String, Int64)

Creates or updates a global configuration value.

This method is thread-safe.

Declaration
public TDerived SetValue(string configurationName, long valueInt64)
Parameters
Type Name Description
String configurationName

Name of the configuration.
Int64 valueInt64

The value as a long.
Returns
Type Description
TDerived

The worker system, which e.g. can be used to chain multiple calls to SetValue.
Exceptions
Type Condition
ArgumentException

IsNullOrWhiteSpace - configurationName

SetValue(String, String)

Creates or updates a global configuration value.

This method is thread-safe.

Declaration
public TDerived SetValue(string configurationName, string valueString)
Parameters
Type Name Description
String configurationName

Name of the configuration.
String valueString

The value as a string.
Returns
Type Description
TDerived

The worker system, which e.g. can be used to chain multiple calls to SetValue.
Exceptions
Type Condition
ArgumentException

IsNullOrWhiteSpace - configurationName

SetValue(String, String, Int64)

Creates or updates a configuration value.

This method is thread-safe.

Declaration
public TDerived SetValue(string configurationName, string applyTo, long valueInt64)
Parameters
Type Name Description
String configurationName

Name of the configuration.
String applyTo

What part of the worker hierarchy this configuration applies to. Use null or an empty string to set a value that applies globally.
Int64 valueInt64

The value as a long.
Returns
Type Description
TDerived

The worker system, which e.g. can be used to chain multiple calls to SetValue.
Exceptions
Type Condition
ArgumentException

IsNullOrWhiteSpace - configurationName

SetValue(String, String, String)

Creates or updates a configuration value.

This method is thread-safe.

Declaration
public TDerived SetValue(string configurationName, string applyTo, string valueString)
Parameters
Type Name Description
String configurationName

Name of the configuration.
String applyTo

What part of the worker hierarchy this configuration applies to. Use null or an empty string to set a value that applies globally.
String valueString

The value as a string.
Returns
Type Description
TDerived

The worker system, which e.g. can be used to chain multiple calls to SetValue.
Exceptions
Type Condition
ArgumentException

IsNullOrWhiteSpace - configurationName

Implements