Class ErrorOutputPort<TError>

Generic class for dataflow error output ports. Create these ports with Create<TError>(String), or use a dataflow worker that already has the appropriate error output port(s) added.

Note that error output ports will always have Full buffering, since this simplifies outputting error rows. To avoid running out of memory where a very large number of error rows might be produced, limit the number of allowed error rows (which is also the default) using MaxRowsSent and/or MaxRowsBeforeError.

Always use SendErrorRow(...) overloads instead of LogRowError(...) overloads where possible (since the port can be left unlinked anyway), except when there is no meaningful error row available.

Note: As per normal, unless otherwise noted, the instance members are not thread-safe, and should only be used from the worker that the port belongs to.

See Dataflow Row Errors for further details.

Note that each logged column is truncated to 256 characters if needed. Rows sent to a downstream worker will however retain their original format and length.

Inheritance

Object

OutputPortBase

OutputPortBase<TError>

ErrorOutputPort<TError>

Inherited Members

OutputPortBase<TError>.ClearRowErrors

OutputPortBase<TError>.Link

OutputPortBase<TError>.LinkedTo

OutputPortBase<TError>.LinkTo(InputPort<TError>)

OutputPortBase<TError>.SetDebugCommands(DebugPortCommands, Int64)

OutputPortBase<TError>.SetDebugCommands(DebugPortCommands)

OutputPortBase.BufferCapacity

OutputPortBase.IsErrorOutput

OutputPortBase.IsLinked

OutputPortBase.Locator

OutputPortBase.Logger

OutputPortBase.Name

OutputPortBase.RowsSent

OutputPortBase.SendError(String, Exception, String, String[])

OutputPortBase.SendError(String, String, String[])

OutputPortBase.SendError(String, Exception)

OutputPortBase.SendError(String)

OutputPortBase.SendSucceeded()

OutputPortBase.State

OutputPortBase.ToLongString()

OutputPortBase.ToString()

OutputPortBase.Worker

OutputPortBase.DebugCommands

OutputPortBase.DebugBreakAfterRows

OutputPortBase.ActiveDuration

OutputPortBase.InstantActive

OutputPortBase.InstantCompleted

Namespace: actionETL

Assembly: actionETL.dll

Syntax

public sealed class ErrorOutputPort<TError> : OutputPortBase<TError> where TError : class

Type Parameters

Name	Description
TError	The type of the error output rows. If a public CaptureRowErrors CaptureRowErrors; field is present in the row type, the system automatically adds the row error to the RowErrors list (unless configured to be ignored). Also see CaptureRowErrors and RowError.

Properties

IsLoggingRows

Returns true if this port is logging rows to the AConfig logging system; otherwise, false. MaxRowsLogged controls how many rows to log.

Declaration

public bool IsLoggingRows { get; }

Property Value

Type	Description
Boolean

MaxRowsBeforeError

Gets or sets the maximum number of rows before an error is raised. It can also be accessed using ErrorPortMaxRowsBeforeError.

The property initially defaults to 0. If the port is then linked, it will be automatically changed to long.MaxValue, allowing an infinite number of rows. Also check the individual worker using the ErrorOutputPort since they can modify the default behavior.

Note: When adding an error output port to a custom Adb worker that modifies database data, see AdbInsertTarget<TInputError> for how to configure MaxRowsBeforeError and handle transactions.

Note: This property is thread-safe.

Declaration

public long MaxRowsBeforeError { get; set; }

Property Value

Type	Description
Int64

MaxRowsBeforeWarning

Gets or sets the maximum number of rows before logging will be at the warning (instead of the informational) level. Defaults to 0, i.e. all logged messages will be at the warning level.

It can also be accessed using ErrorPortMaxRowsBeforeWarning.

Note: This property is thread-safe.

Declaration

public long MaxRowsBeforeWarning { get; set; }

Property Value

Type	Description
Int64

MaxRowsLogged

Gets or sets the maximum number of rows logged to the AConfig logging system. Any additional rows will not be logged (although if multi-row buffers are logged to the error port, the whole buffer is logged even if it partially exceeds MaxRowsLogged).

It can also be accessed using the ErrorPortMaxRowsLogged configuration.

Defaults to 10. Also see IsLoggingRows.

Note: This property is thread-safe.

Declaration

public long MaxRowsLogged { get; set; }

Property Value

Type	Description
Int64

MaxRowsSent

Gets or sets the maximum number of rows sent to the linked downstream worker. Any additional rows will not be sent (although if multi-row buffers are sent to the error port, the whole buffer is logged even if it partially exceeds MaxRowsSent).

It can also be accessed using the ErrorPortMaxRowsSent configuration.

Defaults to long.MaxValue, allowing an infinite number of rows to be sent to the downstream worker.

If this port is not linked, this property is ignored.

Note: This property is thread-safe.

Declaration

public long MaxRowsSent { get; set; }

Property Value

Type	Description
Int64

RowsReceived

Gets the number of rows received.

Note that this shows all rows that were received by the error output port, even if they were not necessarily sent to the downstream worker. Also see TotalRowsSent.

Note: this property is only thread-safe for other workers etc. to read after the port has completed.

Declaration

public long RowsReceived { get; }

Property Value

Type	Description
Int64

Methods

LogRowError(Exception)

Logs a row error, without logging row contents, and without sending any row to any linked downstream worker.

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus LogRowError(Exception exception)

Parameters

Type	Name	Description
Exception	exception	The exception that caused the error. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

LogRowError(Nullable<Int64>, Exception)

Logs a row error, without logging row contents, and without sending any row to any linked downstream worker.

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus LogRowError(long? rowNumber, Exception exception)

Parameters

Type	Name	Description
Nullable<Int64>	rowNumber	The nullable row number. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
Exception	exception	The exception that caused the error. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

LogRowError(String)

Logs a row error, without logging row contents, and without sending any row to any linked downstream worker.

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus LogRowError(string message)

Parameters

Type	Name	Description
String	message	The error message. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

LogRowError(String, Exception)

Logs a row error, without logging row contents, and without sending any row to any linked downstream worker.

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus LogRowError(string message, Exception exception)

Parameters

Type	Name	Description
String	message	The error message. Can be null.
Exception	exception	The exception that caused the error. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

LogRowError(String, Nullable<Int64>, Exception)

Logs a row error, without logging row contents, and without sending any row to any linked downstream worker.

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus LogRowError(string message, long? rowNumber, Exception exception)

Parameters

Type	Name	Description
String	message	The error message. Can be null.
Nullable<Int64>	rowNumber	The nullable row number. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
Exception	exception	The exception that caused the error. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

LogRowError(String, Nullable<Int64>, String)

Logs a row error, without logging row contents, and without sending any row to any linked downstream worker.

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus LogRowError(string message, long? rowNumber, string columnName)

Parameters

Type	Name	Description
String	message	The error message. Can be null.
Nullable<Int64>	rowNumber	The nullable row number. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
String	columnName	Name of the column that caused the error. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

LogRowError(String, Nullable<Int64>, String, Exception)

Logs a row error, without logging row contents, and without sending any row to any linked downstream worker.

Note: The caller of this method must fail its worker if this method returns a failure status.

Declaration

public ProgressStatus LogRowError(string message, long? rowNumber, string columnName, Exception exception)

Parameters

Type	Name	Description
String	message	The error message. Can be null.
Nullable<Int64>	rowNumber	The nullable row number. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
String	columnName	Name of the column that caused the error. Can be null.
Exception	exception	The exception that caused the error. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

SendErrorBuffer(TError[], Int32, Int32, String, Nullable<Int64>, String, Exception)

Logs an error for a batch of rows, and sends the error rows to the linked downstream worker (if any).

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Note: All rows in the batch will be sent to any linked downstream worker, even if that will exceed MaxRowsSent. This is to ensure the specific row that caused the error is included in the rows sent.

Declaration

public ProgressStatus SendErrorBuffer(TError[] rows, int start, int count, string message, long? rowNumber, string columnName, Exception exception)

Parameters

Type	Name	Description
TError[]	rows	The rows. Can be null to not log row contents nor send the rows to any downstream worker.
Int32	start	The start index in the rows array. Ignored if rows is null.
Int32	count	The number of rows to send from the rows array, at most BufferCapacity. If 0 or negative, no rows will be sent. Ignored if rows is null.
String	message	The error message. Can be null.
Nullable<Int64>	rowNumber	The nullable row number for the first row in the batch. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
String	columnName	Name of the column that caused the error. Can be null.
Exception	exception	The exception that caused the error. Can be null.

Returns

Type

Description

ProgressStatus

Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Exceptions

Type	Condition
ArgumentException	start and count must be within the bounds of the row array, or 0.
ArgumentOutOfRangeException	Row count larger than BufferCapacity
InvalidOperationException	Row was null Port canceled

SendErrorRow(TError, Exception)

Logs a row error, and sends the error row to the linked downstream worker (if any).

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus SendErrorRow(TError row, Exception exception)

Parameters

Type	Name	Description
TError	row	The row. Can be null to not log row contents nor send the row to any downstream worker.
Exception	exception	The exception that caused the error. Can be null.

Returns

Type

Description

ProgressStatus

Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

SendErrorRow(TError, Nullable<Int64>, Exception)

Logs a row error, and sends the error row to the linked downstream worker (if any).

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus SendErrorRow(TError row, long? rowNumber, Exception exception)

Parameters

Type	Name	Description
TError	row	The row. Can be null to not log row contents nor send the row to any downstream worker.
Nullable<Int64>	rowNumber	The nullable row number. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
Exception	exception	The exception that caused the error. Can be null.

Returns

Type

Description

ProgressStatus

Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

SendErrorRow(TError, String)

Logs a row error, and sends the error row to the linked downstream worker (if any).

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus SendErrorRow(TError row, string message)

Parameters

Type	Name	Description
TError	row	The row. Can be null to not log row contents nor send the row to any downstream worker.
String	message	The error message. Can be null.

Returns

Type

Description

ProgressStatus

Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

SendErrorRow(TError, String, Exception)

Logs a row error, and sends the error row to the linked downstream worker (if any).

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus SendErrorRow(TError row, string message, Exception exception)

Parameters

Type	Name	Description
TError	row	The row. Can be null to not log row contents nor send the row to any downstream worker.
String	message	The error message. Can be null.
Exception	exception	The exception that caused the error. Can be null.

Returns

Type	Description
ProgressStatus	Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status.

SendErrorRow(TError, String, Nullable<Int64>, String)

Logs a row error, and sends the error row to the linked downstream worker (if any).

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus SendErrorRow(TError row, string message, long? rowNumber, string columnName)

Parameters

Type	Name	Description
TError	row	The row. Can be null to not log row contents nor send the row to any downstream worker.
String	message	The error message. Can be null.
Nullable<Int64>	rowNumber	The nullable row number. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
String	columnName	Name of the column that caused the error. Can be null.

Returns

Type

Description

ProgressStatus

Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

SendErrorRow(TError, String, Nullable<Int64>, String, Exception)

Logs a row error, and sends the error row to the linked downstream worker (if any).

Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

Declaration

public ProgressStatus SendErrorRow(TError row, string message, long? rowNumber, string columnName, Exception exception)

Parameters

Type	Name	Description
TError	row	The row. Can be null to not log row contents nor send the row to any downstream worker.
String	message	The error message. Can be null.
Nullable<Int64>	rowNumber	The nullable row number. Can be null. The meaning of the row number depends on where the row is coming from, e.g.: A source worker reading a CSV file would use the line number of the offending line in the source file as the row number. The first data line would have row number 1. A transform or target worker that sends the incoming rows to its output without aggregation would use the RowsTaken property
String	columnName	Name of the column that caused the error. Can be null.
Exception	exception	The exception that caused the error. Can be null.

Returns

Type

Description

ProgressStatus

Returns a status on whether the row error limit has been reached or not: NotCompleted If MaxRowsBeforeError has not been reached Succeeded If MaxRowsBeforeError has been reached but not exceeded Error If MaxRowsBeforeError has been exceeded Note: The caller of this method must fail its worker if this method returns a failure status, and should then use the returned ProgressStatus as the error status and message (calling a ToOutcomeStatus(Boolean) overload if needed).

See Also

OutputPortBase<TOutput>

OutputPortBaseState

ErrorOutputPortCollection

CaptureRowErrors

RowErrorCollection

RowError