Class UsingActionWorker<TDisposable>

A worker which mimics the using statement in C#/VB, i.e. it allows creating an arbitrary disposable object, running a callback with access to the disposable object, and then automatically disposing the object (via an AddCompletedCallback(Func<WorkerBase, OutcomeStatus, Task<OutcomeStatus>>) callback).

This construct is very useful for guaranteeing a disposable object always gets correctly disposed, even if exceptions occur.

An alternative is to use DisposeOnFinished<TDisposable>(TDisposable). Also see Disposing Disposables.

Inheritance

Object

WorkerParent

WorkerBase

WorkerBase<UsingActionWorker<TDisposable>>

UsingActionWorker<TDisposable>

Implements

IDisposeOnFinished

Inherited Members

WorkerBase<UsingActionWorker<TDisposable>>.AddCompletedCallback(Func<UsingActionWorker<TDisposable>, OutcomeStatus, Task<OutcomeStatus>>)

WorkerBase<UsingActionWorker<TDisposable>>.AddRanCallback(Func<UsingActionWorker<TDisposable>, OutcomeStatus, WorkerParentChildrenState, Task<OutcomeStatus>>)

WorkerBase<UsingActionWorker<TDisposable>>.AddStartingCallback(Func<UsingActionWorker<TDisposable>, Task<ProgressStatus>>)

WorkerBase.AddCompletedCallback(Func<WorkerBase, OutcomeStatus, Task<OutcomeStatus>>)

WorkerBase.AddRanCallback(Func<WorkerBase, OutcomeStatus, WorkerParentChildrenState, Task<OutcomeStatus>>)

WorkerBase.AddStartingCallback(Func<WorkerBase, Task<ProgressStatus>>)

WorkerBase.DefaultIsStartable()

WorkerBase.ErroredPortErrorsWorkerProtected

WorkerBase.ErrorOutputs

WorkerBase.EscalateError

WorkerBase.Inputs

WorkerBase.IsStartable

WorkerBase.Outputs

WorkerBase.Parent

WorkerBase.SucceededSequence<TLastWorker>(WorkerBase, WorkerBase, WorkerBase, WorkerBase, WorkerBase, TLastWorker)

WorkerBase.SucceededSequence<TLastWorker>(WorkerBase, WorkerBase, WorkerBase, WorkerBase, TLastWorker)

WorkerBase.SucceededSequence<TLastWorker>(WorkerBase, WorkerBase, WorkerBase, TLastWorker)

WorkerBase.SucceededSequence<TLastWorker>(WorkerBase, WorkerBase, TLastWorker)

WorkerBase.SucceededSequence<TLastWorker>(WorkerBase, TLastWorker)

WorkerBase.SucceededSequence<TLastWorker>(TLastWorker)

WorkerParent.AddChildCompletedCallback(Action<WorkerBase>)

WorkerParent.AddStartingChildrenCallback(Func<WorkerParent, Task<ProgressStatus>>)

WorkerParent.BytesPerRowBuffer

WorkerParent.Children

WorkerParent.DisposeOnFinished<TDisposable>(TDisposable)

WorkerParent.GetDownstreamFactory<TInput>()

WorkerParent.HasChildren

WorkerParent.IsCanceled

WorkerParent.IsCompleted

WorkerParent.IsCreated

WorkerParent.IsError

WorkerParent.IsFailed

WorkerParent.IsFatal

WorkerParent.IsRunning

WorkerParent.IsSucceeded

WorkerParent.KeepChildrenLevels

WorkerParent.Locator

WorkerParent.LogFactory

WorkerParent.Logger

WorkerParent.MaxRunningChildren

WorkerParent.Name

WorkerParent.RemoveChildren()

WorkerParent.RescheduleChildren()

WorkerParent.RunChildrenAsync(Boolean)

WorkerParent.RunChildrenAsync()

WorkerParent.Status

WorkerParent.Item[String]

WorkerParent.ToString()

WorkerParent.WorkerSystem

WorkerParent.DebugCommands

WorkerParent.AggregateErrorOutputRows

WorkerParent.AggregateOutputRows

WorkerParent.AggregateWorkersCompleted

WorkerParent.InstantCompleted

WorkerParent.InstantCreated

WorkerParent.InstantStarted

WorkerParent.RunningDuration

Namespace: actionETL

Assembly: actionETL.dll

Syntax

public class UsingActionWorker<TDisposable> : WorkerBase<UsingActionWorker<TDisposable>>, IDisposeOnFinished where TDisposable : class, IDisposable

Type Parameters

Name	Description
TDisposable	The type of the disposable object.

Examples

The below example uses a UsingActionWorker worker to guarantee that the disposable FileStream instance returned by File.OpenWrite() will get disposed after the follow-on action executes, even if the action throws an exception.

using actionETL;
using System.IO;

new WorkerSystem()
    .Root(ws =>
    {
        _ = new UsingActionWorker<FileStream>(ws, "Write file"
            , () => File.OpenWrite(@"MyFile.txt")
            , (uaw, file) =>
            {
                file.WriteByte(0x01);
                // File operations, other processing ...
            });
    })
    .Start()
    .ThrowOnFailure();

Constructors

UsingActionWorker(WorkerParent, String, Func<TDisposable>, Action<UsingActionWorker<TDisposable>, TDisposable>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run a synchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<TDisposable> usingFunc, Action<UsingActionWorker<TDisposable>, TDisposable> action)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Action<UsingActionWorker<TDisposable>, TDisposable>	action	The synchronous action to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

UsingActionWorker(WorkerParent, String, Func<TDisposable>, Func<UsingActionWorker<TDisposable>, TDisposable, OutcomeStatus>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run a synchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<TDisposable> usingFunc, Func<UsingActionWorker<TDisposable>, TDisposable, OutcomeStatus> func)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Func<UsingActionWorker<TDisposable>, TDisposable, OutcomeStatus>	func	The synchronous function to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters. It returns OutcomeStatus success or failure.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

UsingActionWorker(WorkerParent, String, Func<TDisposable>, Func<UsingActionWorker<TDisposable>, TDisposable, Task<OutcomeStatus>>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run an asynchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<TDisposable> usingFunc, Func<UsingActionWorker<TDisposable>, TDisposable, Task<OutcomeStatus>> funcAsync)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Func<UsingActionWorker<TDisposable>, TDisposable, Task<OutcomeStatus>>	funcAsync	The asynchronous function to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters. It returns OutcomeStatus success or failure.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

UsingActionWorker(WorkerParent, String, Func<TDisposable>, Func<UsingActionWorker<TDisposable>, TDisposable, Task>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run an asynchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<TDisposable> usingFunc, Func<UsingActionWorker<TDisposable>, TDisposable, Task> actionAsync)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Func<UsingActionWorker<TDisposable>, TDisposable, Task>	actionAsync	The asynchronous action to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

UsingActionWorker(WorkerParent, String, Func<Boolean>, Func<TDisposable>, Action<UsingActionWorker<TDisposable>, TDisposable>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run a synchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, Func<TDisposable> usingFunc, Action<UsingActionWorker<TDisposable>, TDisposable> action)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<Boolean>	isStartableFunc	Function to calculate the worker start constraint; it should return true for startable and false for not startable. Defaults to startable if null.
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Action<UsingActionWorker<TDisposable>, TDisposable>	action	The synchronous action to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

UsingActionWorker(WorkerParent, String, Func<Boolean>, Func<TDisposable>, Func<UsingActionWorker<TDisposable>, TDisposable, OutcomeStatus>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run a synchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, Func<TDisposable> usingFunc, Func<UsingActionWorker<TDisposable>, TDisposable, OutcomeStatus> func)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<Boolean>	isStartableFunc	Function to calculate the worker start constraint; it should return true for startable and false for not startable. Defaults to startable if null.
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Func<UsingActionWorker<TDisposable>, TDisposable, OutcomeStatus>	func	The synchronous function to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters. It returns OutcomeStatus success or failure.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

UsingActionWorker(WorkerParent, String, Func<Boolean>, Func<TDisposable>, Func<UsingActionWorker<TDisposable>, TDisposable, Task<OutcomeStatus>>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run an asynchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, Func<TDisposable> usingFunc, Func<UsingActionWorker<TDisposable>, TDisposable, Task<OutcomeStatus>> funcAsync)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<Boolean>	isStartableFunc	Function to calculate worker start constraints. Defaults to true if not supplied or null.
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Func<UsingActionWorker<TDisposable>, TDisposable, Task<OutcomeStatus>>	funcAsync	The asynchronous function to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters. It returns OutcomeStatus success or failure.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

UsingActionWorker(WorkerParent, String, Func<Boolean>, Func<TDisposable>, Func<UsingActionWorker<TDisposable>, TDisposable, Task>)

Initializes a new instance of the UsingActionWorker<TDisposable> worker that will create a disposable object, run an asynchronous callback with access to the disposable object, and then automatically dispose the object when the worker has completed.

Declaration

public UsingActionWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, Func<TDisposable> usingFunc, Func<UsingActionWorker<TDisposable>, TDisposable, Task> actionAsync)

Parameters

Type	Name	Description
WorkerParent	workerParent	The parent worker or worker system that the new child worker will be added to. Cannot be null.
String	workerName	Name of the worker. Set to a prefix plus a trailing "/" (e.g. "MyPrefix-/") to generate a unique name from the prefix plus an increasing number starting at 1. While less useful, set to null, whitespace or "/" to generate a unique name from the worker type plus an increasing number starting at 1. The name cannot otherwise contain "/", and cannot start with double underscore "__".
Func<Boolean>	isStartableFunc	Function to calculate the worker start constraint; it should return true for startable and false for not startable. Defaults to startable if null.
Func<TDisposable>	usingFunc	The using function. It takes no parameters, and returns a disposable object.
Func<UsingActionWorker<TDisposable>, TDisposable, Task>	actionAsync	The asynchronous action to execute, optionally creating child workers. It receives the worker itself and the disposable object created by usingFunc as parameters.

Exceptions

Type	Condition
ArgumentException	workerName: Workers with the same parent must have unique names. Worker and worker system names cannot contain '/' or start with double underscore '__'.
ArgumentNullException	workerParent - All workers must have a parent. The top level workers have the worker system as parent.
InvalidOperationException	Cannot add child worker to parent which has completed. Are you adding it to the correct parent? Cannot add worker to parent, since its children have been started. Are you adding it to the correct parent?

Methods

RunAsync()

This method can be overridden to add custom functionality to the derived worker that runs before and after the row processing. In this case, the base class base.RunAsync() must be called for the worker to function correctly.

Note however that the worker uses an AddCompletedCallback(Func<WorkerBase, OutcomeStatus, Task<OutcomeStatus>>) callback to dispose the disposable, which runs after RunAsync() and any AddRanCallback(Func<WorkerBase, OutcomeStatus, WorkerParentChildrenState, Task<OutcomeStatus>>) callbacks.

Typically, this worker is used without overriding this method.

Declaration

protected override Task<OutcomeStatus> RunAsync()

Returns

Type	Description
Task<OutcomeStatus>	A Task describing the success or failure of the worker. An asynchronous async implementation would e.g. return OutcomeStatus.Succeeded on success, while a synchronous implementation would return OutcomeStatus.SucceededTask.

Overrides

WorkerParent.RunAsync()

Implements

IDisposeOnFinished