Class ProgressStatus

Describes an execution status, e.g. of a callback function of a worker.

Note: If a DbException is passed to the static factory methods, database specific exception details will be automatically added to the Message property.

Inheritance

Object

ProgressStatus

Implements

IOutcomeStatus

Namespace: actionETL

Assembly: actionETL.dll

Syntax

public sealed class ProgressStatus : IOutcomeStatus

Properties

Category

Gets the category, if any, which describes what generated the status. Guaranteed to not be null.

Declaration

public string Category { get; }

Property Value

Type	Description
String

Exception

Gets the exception that caused the failure, or null if either no exception was thrown, or it was thrown but was caught and not rethrown.

Declaration

public Exception Exception { get; }

Property Value

Type	Description
Exception	The exception.

Remarks

Exception can be null even if the worker or worker system fails - this happens when an error condition is noticed without an exception having been thrown, e.g. when testing for and finding a null argument, logging the error, and returning an Error or Fatal status.

InnerStatuses

Gets the inner statuses, which only consists of failure statuses, or an empty list.

Declaration

public IImmutableList<IOutcomeStatus> InnerStatuses { get; }

Property Value

Type	Description
IImmutableList<IOutcomeStatus>

IsCanceled

Gets a value indicating whether the status is canceled.

Declaration

public bool IsCanceled { get; }

Property Value

Type	Description
Boolean	true if the status is Canceled; otherwise, false.

IsCompleted

Gets a value indicating whether this instance is completed, i.e. is in a final state.

Declaration

public bool IsCompleted { get; }

Property Value

Type	Description
Boolean	true if the status is Succeeded, Canceled, Error, or Fatal; otherwise, false.

IsError

Gets a value indicating whether the status is an error.

Declaration

public bool IsError { get; }

Property Value

Type	Description
Boolean	true if the status is Error; otherwise, false.

IsFailed

Gets a value indicating whether the status is in a failed completed state, i.e. Canceled, Error, or Fatal.

Declaration

public bool IsFailed { get; }

Property Value

Type	Description
Boolean	true if the status is Canceled, Error, or Fatal; otherwise, false.

IsFatal

Gets a value indicating whether the status has fatally faulted.

Declaration

public bool IsFatal { get; }

Property Value

Type	Description
Boolean	true if the status is Fatal; otherwise, false.

IsSucceeded

Gets a value indicating whether the status is succeeded.

Declaration

public bool IsSucceeded { get; }

Property Value

Type	Description
Boolean	true if the status is Succeeded; otherwise, false.

Message

Gets the message, if any, which provides supplementary information. Guaranteed to not be null.

Declaration

public string Message { get; }

Property Value

Type	Description
String

Name

Gets the ProgressStatus name, which is the same as the ProgressState name.

Declaration

public string Name { get; }

Property Value

Type	Description
String

NotCompleted

Gets an immutable ProgressStatus instance with the NotCompleted status. This can e.g. be used when returning this status from a (potentially asynchronous) method.

Note: Always use the Is* properties (IsSucceeded, IsCompleted etc.), or use the State property to check the status. I.e. do not compare with this immutable instance (since there can be other instances, with e.g. InnerStatuses populated).

Declaration

public static ProgressStatus NotCompleted { get; }

Property Value

Type	Description
ProgressStatus

NotCompletedTask

Gets a completed Task with an immutable ProgressStatus instance with the NotCompleted status. This is typically used when returning this status from a non-async method that has a Task<ProgressStatus> return type.

Note: Always use the Is* properties (IsSucceeded, IsCompleted etc.), or use the State property to check the status. I.e. do not compare with this immutable instance (since there can be other instances, with e.g. InnerStatuses populated).

Declaration

public static Task<ProgressStatus> NotCompletedTask { get; }

Property Value

Type	Description
Task<ProgressStatus>

Ordinal

Gets the (0-based) OutcomeState ordinal.

Declaration

public int Ordinal { get; }

Property Value

Type	Description
Int32

State

Gets the state.

Declaration

public ProgressState State { get; }

Property Value

Type	Description
ProgressState

Succeeded

Gets an immutable ProgressStatus instance with the Succeeded status. This can e.g. be used when returning this status from a (potentially asynchronous) method.

Note: Always use the Is* properties (IsSucceeded, IsCompleted etc.), or use the State property to check the status. I.e. do not compare with this immutable instance (since there can be other instances, with e.g. InnerStatuses populated).

Declaration

public static ProgressStatus Succeeded { get; }

Property Value

Type	Description
ProgressStatus

SucceededTask

Gets a completed Task with an immutable ProgressStatus instance with the Succeeded status. This is typically used when returning this status from a non-async method that has a Task<ProgressStatus> return type.

Note: Always use the Is* properties (IsSucceeded, IsCompleted etc.), or use the State property to check the status. I.e. do not compare with this immutable instance (since there can be other instances, with e.g. InnerStatuses populated).

Declaration

public static Task<ProgressStatus> SucceededTask { get; }

Property Value

Type	Description
Task<ProgressStatus>

Methods

Canceled()

Creates a Canceled status instance.

Declaration

public static ProgressStatus Canceled()

Returns

Type	Description
ProgressStatus	The Canceled status instance.

Canceled(String)

Creates a Canceled status instance.

Declaration

public static ProgressStatus Canceled(string category)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.

Returns

Type	Description
ProgressStatus	The Canceled status instance.

Canceled(String, Exception)

Creates a Canceled status instance.

Declaration

public static ProgressStatus Canceled(string category, Exception exception)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.

Returns

Type	Description
ProgressStatus	The Canceled status instance.

Canceled(String, Exception, String)

Creates a Canceled status instance.

Declaration

public static ProgressStatus Canceled(string category, Exception exception, string message)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The Canceled status instance.

Canceled(String, String)

Creates a Canceled status instance.

Declaration

public static ProgressStatus Canceled(string category, string message)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The Canceled status instance.

Combine(ProgressStatus)

Combines the current instance with a second ProgressStatus instance by using the most severe as the primary one presented directly in properties, and retaining secondary statuses (if they are failure statuses) in InnerStatuses.

Note that InnerStatuses can have (failure) statuses even if the main ProgressStatus.Status is ProgressStatus.Succeeded.

Declaration

public ProgressStatus Combine(ProgressStatus secondStatus)

Parameters

Type	Name	Description
ProgressStatus	secondStatus	The second status.

Returns

Type	Description
ProgressStatus	The combined ProgressStatus.

Remarks

Supplementary properties Category, Exception, and Message are only allowed for states Canceled, Error, and Fatal.

The ProgressStatus properties are immutable, i.e. they can't themselves be modified after construction. Note however that any Exception object in the Exception property is a mutable reference type, and its properties can be modified. To avoid any issues with this, never modify the Exception object in an ProgressStatus instance that have been returned from this Combine method.

Combine(Boolean, ProgressStatus)

Combines the current instance with a second ProgressStatus instance by using one status as the primary one (usually the most severe one) presented directly in properties, and retaining secondary statuses (if they are failure statuses) in InnerStatuses.

Note that InnerStatuses can have (failure) statuses even if the main ProgressStatus.Status is ProgressStatus.Succeeded.

Declaration

public ProgressStatus Combine(bool forceFirstStatus, ProgressStatus secondStatus)

Parameters

Type	Name	Description
Boolean	forceFirstStatus	If set to false, the ProgressStatus with the most severe ProgressState (i.e. highest Ordinal) will be the main status returned. If set to true, the current instance will be the main status returned. In both cases, InnerStatuses is possibly extended with additional entries.
ProgressStatus	secondStatus	The second status.

Returns

Type	Description
ProgressStatus	The combined ProgressStatus.

Remarks

Supplementary properties Category, Exception, and Message are only allowed for states Canceled, Error, and Fatal.

The ProgressStatus properties are immutable, i.e. they can't themselves be modified after construction. Note however that any Exception object in the Exception property is a mutable reference type, and its properties can be modified. To avoid any issues with this, never modify the Exception object in an ProgressStatus instance that have been returned from this Combine method.

Error(String)

Creates an Error status instance.

Declaration

public static ProgressStatus Error(string category)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.

Returns

Type	Description
ProgressStatus	The Error status instance.

Error(String, Exception)

Creates an Error status instance.

Declaration

public static ProgressStatus Error(string category, Exception exception)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.

Returns

Type	Description
ProgressStatus	The Error status instance.

Error(String, Exception, String)

Creates an Error status instance.

Declaration

public static ProgressStatus Error(string category, Exception exception, string message)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The Error status instance.

Error(String, String)

Creates an Error status instance.

Declaration

public static ProgressStatus Error(string category, string message)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The Error status instance.

Failure(ProgressState, String)

Creates a failure status instance.

Declaration

public static ProgressStatus Failure(ProgressState state, string category)

Parameters

Type	Name	Description
ProgressState	state	The failure state, i.e. Canceled, Error, or Fatal.
String	category	The category. Defaults to "Unset" if null.

Returns

Type	Description
ProgressStatus	The failure status instance.

Failure(ProgressState, String, Exception)

Creates a failure status instance.

Declaration

public static ProgressStatus Failure(ProgressState state, string category, Exception exception)

Parameters

Type	Name	Description
ProgressState	state	The failure state, i.e. Canceled, Error, or Fatal.
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.

Returns

Type	Description
ProgressStatus	The failure status instance.

Failure(ProgressState, String, Exception, String)

Creates a failure status instance.

Declaration

public static ProgressStatus Failure(ProgressState state, string category, Exception exception, string message)

Parameters

Type	Name	Description
ProgressState	state	The failure state, i.e. Canceled, Error, or Fatal.
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The failure status instance.

Failure(ProgressState, String, String)

Creates a failure status instance.

Declaration

public static ProgressStatus Failure(ProgressState state, string category, string message)

Parameters

Type	Name	Description
ProgressState	state	The failure state, i.e. Canceled, Error, or Fatal.
String	category	The category. Defaults to "Unset" if null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The failure status instance.

Fatal(String)

Creates a Fatal status instance.

Declaration

public static ProgressStatus Fatal(string category)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.

Returns

Type	Description
ProgressStatus	The Fatal status instance.

Fatal(String, Exception)

Creates a Fatal status instance.

Declaration

public static ProgressStatus Fatal(string category, Exception exception)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.

Returns

Type	Description
ProgressStatus	The Fatal status instance.

Fatal(String, Exception, String)

Creates a Fatal status instance.

Declaration

public static ProgressStatus Fatal(string category, Exception exception, string message)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
Exception	exception	The exception. Can be null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The Fatal status instance.

Fatal(String, String)

Creates a Fatal status instance.

Declaration

public static ProgressStatus Fatal(string category, string message)

Parameters

Type	Name	Description
String	category	The category. Defaults to "Unset" if null.
String	message	The message. Defaults to an empty string if null.

Returns

Type	Description
ProgressStatus	The Fatal status instance.

ThrowOnFailure()

Throws an InvalidOperationException if the State is a failure state.

Declaration

public void ThrowOnFailure()

Exceptions

Type	Condition
InvalidOperationException	State

ToLongString()

Returns a String that describes this instance in detail.

Declaration

public string ToLongString()

Returns

Type	Description
String

ToOutcomeStatus(Boolean)

Creates an OutcomeStatus instance from this ProgressStatus instance.

Declaration

public OutcomeStatus ToOutcomeStatus(bool notCompletedIsSucceeded)

Parameters

Type	Name	Description
Boolean	notCompletedIsSucceeded	If set to true, will silently convert not completed states to the Succeeded state. If set to false, will throw an exception on any not completed states.

Returns

Type	Description
OutcomeStatus	The OutcomeStatus instance.

Exceptions

Type	Condition
InvalidCastException	Cannot convert an uncompleted state to OutcomeStatus.

ToOutcomeStatusTask(Boolean)

Creates an OutcomeStatus instance wrapped in a Task from this ProgressStatus instance.

Declaration

public Task<OutcomeStatus> ToOutcomeStatusTask(bool notCompletedIsSucceeded)

Parameters

Type	Name	Description
Boolean	notCompletedIsSucceeded	If set to true, will silently convert not completed states to the Succeeded state. If set to false, will throw an exception on any not completed states.

Returns

Type	Description
Task<OutcomeStatus>	The Task{OutcomeStatus} instance.

Exceptions

Type	Condition
InvalidCastException	Cannot convert an uncompleted state to OutcomeStatus.

ToString()

Returns a String that represents this instance.

Declaration

public sealed override string ToString()

Returns

Type	Description
String

Overrides

Object.ToString()

ToTask()

Returns a task with the status instance in the Task.Result property.

Declaration

public Task<ProgressStatus> ToTask()

Returns

Type	Description
Task<ProgressStatus>

Implements

IOutcomeStatus