Class OutcomeStatus

Describes a success or failure outcome, e.g. of a completed worker or port.

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

OutcomeStatus

Implements

IOutcomeStatus

Namespace: actionETL

Assembly: actionETL.dll

Syntax

public sealed class OutcomeStatus : 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 OutcomeStatus name, which is the same as the OutcomeState name.

Declaration

public string Name { get; }

Property Value

Type	Description
String

Ordinal

Gets the (0-based) OutcomeState ordinal.

Declaration

public int Ordinal { get; }

Property Value

Type	Description
Int32

State

Gets the state.

Declaration

public OutcomeState State { get; }

Property Value

Type	Description
OutcomeState

Succeeded

Gets an immutable OutcomeStatus 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 OutcomeStatus Succeeded { get; }

Property Value

Type	Description
OutcomeStatus

SucceededTask

Gets a completed Task with an immutable OutcomeStatus instance with the Succeeded status. This is typically used when returning this status from a non-async method that has a Task<OutcomeStatus> 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<OutcomeStatus> SucceededTask { get; }

Property Value

Type	Description
Task<OutcomeStatus>

Methods

Canceled()

Creates a Canceled status instance.

Declaration

public static OutcomeStatus Canceled()

Returns

Type	Description
OutcomeStatus	The Canceled status instance.

Canceled(String)

Creates a Canceled status instance.

Declaration

public static OutcomeStatus Canceled(string category)

Parameters

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

Returns

Type	Description
OutcomeStatus	The Canceled status instance.

Canceled(String, Exception)

Creates a Canceled status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Canceled status instance.

Canceled(String, Exception, String)

Creates a Canceled status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Canceled status instance.

Canceled(String, String)

Creates a Canceled status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Canceled status instance.

Combine(OutcomeStatus)

Combines the current instance with a second OutcomeStatus 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 OutcomeStatus.Status is OutcomeStatus.Succeeded.

Declaration

public OutcomeStatus Combine(OutcomeStatus secondStatus)

Parameters

Type	Name	Description
OutcomeStatus	secondStatus	The second status.

Returns

Type	Description
OutcomeStatus	The combined OutcomeStatus.

Remarks

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

The OutcomeStatus 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 OutcomeStatus instance that have been returned from this Combine method.

Combine(Boolean, OutcomeStatus)

Combines the current instance with a second OutcomeStatus 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 OutcomeStatus.Status is OutcomeStatus.Succeeded.

Declaration

public OutcomeStatus Combine(bool forceFirstStatus, OutcomeStatus secondStatus)

Parameters

Type	Name	Description
Boolean	forceFirstStatus	If set to false, the OutcomeStatus with the most severe OutcomeState (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.
OutcomeStatus	secondStatus	The second status.

Returns

Type	Description
OutcomeStatus	The combined OutcomeStatus.

Remarks

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

The OutcomeStatus 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 OutcomeStatus instance that have been returned from this Combine method.

Error(String)

Creates an Error status instance.

Declaration

public static OutcomeStatus Error(string category)

Parameters

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

Returns

Type	Description
OutcomeStatus	The Error status instance.

Error(String, Exception)

Creates an Error status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Error status instance.

Error(String, Exception, String)

Creates an Error status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Error status instance.

Error(String, String)

Creates an Error status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Error status instance.

Failure(OutcomeState, String)

Creates a failure status instance.

Declaration

public static OutcomeStatus Failure(OutcomeState state, string category)

Parameters

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

Returns

Type	Description
OutcomeStatus	The failure status instance.

Failure(OutcomeState, String, Exception)

Creates a failure status instance.

Declaration

public static OutcomeStatus Failure(OutcomeState state, string category, Exception exception)

Parameters

Type	Name	Description
OutcomeState	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
OutcomeStatus	The failure status instance.

Failure(OutcomeState, String, Exception, String)

Creates a failure status instance.

Declaration

public static OutcomeStatus Failure(OutcomeState state, string category, Exception exception, string message)

Parameters

Type	Name	Description
OutcomeState	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
OutcomeStatus	The failure status instance.

Failure(OutcomeState, String, String)

Creates a failure status instance.

Declaration

public static OutcomeStatus Failure(OutcomeState state, string category, string message)

Parameters

Type	Name	Description
OutcomeState	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
OutcomeStatus	The failure status instance.

Fatal(String)

Creates a Fatal status instance.

Declaration

public static OutcomeStatus Fatal(string category)

Parameters

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

Returns

Type	Description
OutcomeStatus	The Fatal status instance.

Fatal(String, Exception)

Creates a Fatal status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Fatal status instance.

Fatal(String, Exception, String)

Creates a Fatal status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	The Fatal status instance.

Fatal(String, String)

Creates a Fatal status instance.

Declaration

public static OutcomeStatus 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
OutcomeStatus	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

ToProgressStatus()

Creates a ProgressStatus instance from this OutcomeStatus instance.

Declaration

public ProgressStatus ToProgressStatus()

Returns

Type	Description
ProgressStatus	The ProgressStatus instance.

ToProgressStatusTask()

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

Declaration

public Task<ProgressStatus> ToProgressStatusTask()

Returns

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

ToString()

Returns a String that represents this instance.

Declaration

public override sealed 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<OutcomeStatus> ToTask()

Returns

Type	Description
Task<OutcomeStatus>

Implements

IOutcomeStatus