Class ExecuteProcessWorker

A worker that launches an external process, e.g. an executable, a batch script, or a document.

On successful completion, the exit code from the process is stored in ExitCode. By default, a zero exit code will give the worker a Succeeded status, any other exit code will give it an Error status.

See the Process and ProcessStartInfo classes for background information.

Inheritance

Object

WorkerParent

WorkerBase

WorkerBase<ExecuteProcessWorker>

ExecuteProcessWorker

Implements

IDisposeOnFinished

Inherited Members

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

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

WorkerBase<ExecuteProcessWorker>.AddStartingCallback(Func<ExecuteProcessWorker, 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.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 ExecuteProcessWorker : WorkerBase<ExecuteProcessWorker>, IDisposeOnFinished

Constructors

ExecuteProcessWorker(WorkerParent, String, ProcessStartInfo)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, ProcessStartInfo processStartInfo)

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 "__".
ProcessStartInfo	processStartInfo	Use a ProcessStartInfo overload to customize how the process is launched.

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?

ExecuteProcessWorker(WorkerParent, String, Func<Boolean>, ProcessStartInfo)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, ProcessStartInfo processStartInfo)

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.
ProcessStartInfo	processStartInfo	Use a ProcessStartInfo overload to customize how the process is launched.

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?

ExecuteProcessWorker(WorkerParent, String, Func<Boolean>, String)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, string fileName)

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.
String	fileName	Name of the file to launch.

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?

ExecuteProcessWorker(WorkerParent, String, Func<Boolean>, String, String)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, string fileName, string arguments)

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.
String	fileName	Name of the file to launch.
String	arguments	Command line arguments.

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?

ExecuteProcessWorker(WorkerParent, String, Func<Boolean>, String, String, String, SecureString, String)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, Func<bool> isStartableFunc, string fileName, string arguments, string userName, SecureString password, string domain)

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.
String	fileName	Name of the file to launch.
String	arguments	Command line arguments.
String	userName	Name of the user.
SecureString	password	The password.
String	domain	The domain.

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?

ExecuteProcessWorker(WorkerParent, String, String)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, string fileName)

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 "__".
String	fileName	Name of the file to launch.

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?

ExecuteProcessWorker(WorkerParent, String, String, String)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, string fileName, string arguments)

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 "__".
String	fileName	Name of the file to launch.
String	arguments	Command line arguments.

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?

ExecuteProcessWorker(WorkerParent, String, String, String, String, SecureString, String)

Initializes a new instance of the ExecuteProcessWorker worker that launches an external process, e.g. an executable, a batch script, or a document.

Declaration

public ExecuteProcessWorker(WorkerParent workerParent, string workerName, string fileName, string arguments, string userName, SecureString password, string domain)

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 "__".
String	fileName	Name of the file to launch.
String	arguments	Command line arguments.
String	userName	Name of the user.
SecureString	password	The password.
String	domain	The domain.

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?

Properties

ExitCode

Gets the exit code specified by the process. Only available after the worker has completed. Each process defines the meaning of its exit codes; by default a zero exit code will give the worker a Succeeded status, any other will give it an Error status.

Also see ExitCodeOutcomeStatusFunc.

Note: This property is thread-safe.

Declaration

public int ExitCode { get; }

Property Value

Type	Description
Int32	The exit code.

Exceptions

Type	Condition
InvalidOperationException	Value only available after the worker has completed. Value not set.

ExitCodeOutcomeStatusFunc

Gets or sets the callback that takes the exit code and returns the OutcomeStatus for the worker. Can only be set before the worker is started.

Do use ExecuteProcessWorkerExitCodeFailure as the category when returning a failure status.

The default callback converts a 0 exit code into Succeeded, and any other exit code into an Error status.

Also see ExitCode.

Note: This property is thread-safe.

Declaration

public Func<int, OutcomeStatus> ExitCodeOutcomeStatusFunc { get; set; }

Property Value

Type	Description
Func<Int32, OutcomeStatus>

Exceptions

Type	Condition
ArgumentNullException	ExitCodeOutcomeStatusFunc
InvalidOperationException	Cannot set the value after the worker has started.

StandardErrorAction

Gets or sets a callback to process each text line the started process sends to StandardError. This setting is mutually exclusive with StandardErrorLines.

Defaults to null. Can only be set before the worker starts running.

For each call to the callback, the string parameter contains a single line of text. After the final line, a null or empty string might be sent, therefore always check the line with String.IsNullOrEmpty() before using it.

Note: This property is thread-safe.

Declaration

public Action<Process, string> StandardErrorAction { get; set; }

Property Value

Type	Description
Action<Process, String>

Exceptions

Type	Condition
InvalidOperationException	Cannot set the value after the worker has started running.

StandardErrorLines

Gets or sets the standard error lines collection, e.g. a List<string>, to store ErrorOutput lines in. This setting is mutually exclusive with StandardErrorAction.

Defaults to null. Can only be set before the worker has started. Note that accessing the items in the collection while the worker is running is only supported if the collection is thread-safe.

Note: This property is thread-safe.

Declaration

public ICollection<string> StandardErrorLines { get; set; }

Property Value

Type	Description
ICollection<String>

Exceptions

Type	Condition
InvalidOperationException	Cannot set the value after the worker has started running.

StandardInputAction

Gets or sets a callback that writes data to the input stream of the started process. Can only be set before the worker starts running. This setting is mutually exclusive with StandardInputString.

Call StreamWriter.Close to close the stream after all data has been written.

Note: This property is thread-safe.

Declaration

public Action<StreamWriter> StandardInputAction { get; set; }

Property Value

Type	Description
Action<StreamWriter>

Exceptions

Type	Condition
InvalidOperationException	Cannot set the value after the worker has started running.

StandardInputString

Gets or sets a string that will be sent to the standard input of the process. Can only be set before the worker starts running. This setting is mutually exclusive with StandardInputAction.

Note: This property is thread-safe.

Declaration

public string StandardInputString { get; set; }

Property Value

Type	Description
String

Exceptions

Type	Condition
InvalidOperationException	Cannot set the value after the worker has started running.

StandardOutputAction

Gets or sets a callback to process each text line the started process sends to StandardOutput. This setting is mutually exclusive with StandardOutputLines.

Defaults to null. Can only be set before the worker starts running.

For each call to the callback, the string parameter contains a single line of text. After the final line, a null or empty string might be sent, therefore always check the line with String.IsNullOrEmpty() before using it.

Note: This property is thread-safe.

Declaration

public Action<Process, string> StandardOutputAction { get; set; }

Property Value

Type	Description
Action<Process, String>

Exceptions

Type	Condition
InvalidOperationException	Cannot set the value after the worker has started running.

StandardOutputLines

Gets or sets the standard output lines collection, e.g. a List<string>, to store ErrorOutput lines in. This setting is mutually exclusive with StandardOutputAction.

Defaults to null. Can only be set before the worker has started. Note that accessing the items in the collection while the worker is running is only supported if the collection is thread-safe.

Note: This property is thread-safe.

Declaration

public ICollection<string> StandardOutputLines { get; set; }

Property Value

Type	Description
ICollection<String>

Exceptions

Type	Condition
InvalidOperationException	Cannot set the value after the worker has started running.

Methods

RunAsync()

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

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

See Also

Process

ProcessStartInfo