Class SystemOutcomeStatus

Describes a success or failure outcome of a completed worker system.

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

SystemOutcomeStatus

Implements

IOutcomeStatus

Namespace: actionETL

Assembly: actionETL.dll

Syntax

public sealed class SystemOutcomeStatus : 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 SystemOutcomeStatus 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 SystemOutcomeStatus 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 SystemOutcomeStatus Succeeded { get; }

Property Value

Type	Description
SystemOutcomeStatus

SucceededTask

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

Property Value

Type	Description
Task<SystemOutcomeStatus>

Methods

Canceled()

Creates a Canceled status instance.

Declaration

public static SystemOutcomeStatus Canceled()

Returns

Type	Description
SystemOutcomeStatus	The Canceled status instance.

Canceled(String)

Creates a Canceled status instance.

Declaration

public static SystemOutcomeStatus Canceled(string category)

Parameters

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

Returns

Type	Description
SystemOutcomeStatus	The Canceled status instance.

Canceled(String, Exception)

Creates a Canceled status instance.

Declaration

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

Canceled(String, Exception, String)

Creates a Canceled status instance.

Declaration

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

Canceled(String, String)

Creates a Canceled status instance.

Declaration

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

Combine(SystemOutcomeStatus)

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

Declaration

public SystemOutcomeStatus Combine(SystemOutcomeStatus secondStatus)

Parameters

Type	Name	Description
SystemOutcomeStatus	secondStatus	The second status.

Returns

Type	Description
SystemOutcomeStatus	The combined SystemOutcomeStatus.

Remarks

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

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

Combine(Boolean, SystemOutcomeStatus)

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

Declaration

public SystemOutcomeStatus Combine(bool forceFirstStatus, SystemOutcomeStatus secondStatus)

Parameters

Type	Name	Description
Boolean	forceFirstStatus	If set to false, the SystemOutcomeStatus 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.
SystemOutcomeStatus	secondStatus	The second status.

Returns

Type	Description
SystemOutcomeStatus	The combined SystemOutcomeStatus.

Remarks

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

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

Error(String)

Creates an Error status instance.

Declaration

public static SystemOutcomeStatus Error(string category)

Parameters

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

Returns

Type	Description
SystemOutcomeStatus	The Error status instance.

Error(String, Exception)

Creates an Error status instance.

Declaration

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

Error(String, Exception, String)

Creates an Error status instance.

Declaration

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

Error(String, String)

Creates an Error status instance.

Declaration

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

Exit()

Exits the program (by calling Exit(Int32)), returning the Ordinal as the exit code, i.e. zero on success, and non-zero on failure. OutcomeState lists the specific codes.

Declaration

public void Exit()

Failure(OutcomeState, String)

Creates a failure status instance.

Declaration

public static SystemOutcomeStatus 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
SystemOutcomeStatus	The failure status instance.

Failure(OutcomeState, String, Exception)

Creates a failure status instance.

Declaration

public static SystemOutcomeStatus 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
SystemOutcomeStatus	The failure status instance.

Failure(OutcomeState, String, Exception, String)

Creates a failure status instance.

Declaration

public static SystemOutcomeStatus 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
SystemOutcomeStatus	The failure status instance.

Failure(OutcomeState, String, String)

Creates a failure status instance.

Declaration

public static SystemOutcomeStatus 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
SystemOutcomeStatus	The failure status instance.

Fatal(String)

Creates a Fatal status instance.

Declaration

public static SystemOutcomeStatus Fatal(string category)

Parameters

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

Returns

Type	Description
SystemOutcomeStatus	The Fatal status instance.

Fatal(String, Exception)

Creates a Fatal status instance.

Declaration

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

Fatal(String, Exception, String)

Creates a Fatal status instance.

Declaration

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

Fatal(String, String)

Creates a Fatal status instance.

Declaration

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

FromOutcomeStatus(IOutcomeStatus)

Gets a SystemOutcomeStatus from an IOutcomeStatus.

Declaration

public static SystemOutcomeStatus FromOutcomeStatus(IOutcomeStatus outcomeStatus)

Parameters

Type	Name	Description
IOutcomeStatus	outcomeStatus

Returns

Type	Description
SystemOutcomeStatus

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

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<SystemOutcomeStatus> ToTask()

Returns

Type	Description
Task<SystemOutcomeStatus>

Implements

IOutcomeStatus