Class AdbInsertTargetFactory

Factory methods that create an AdbInsertTarget<TInputError> dataflow worker with one Input port, that inserts all incoming rows into a SQL table or view. It also has an ErrorOutput port that receives any row batches that throw an exception when creating and executing their queries.

Note that this worker requires an AdbProvider that supports both IAdbTableInformationService and IAdbInsertStatementService, see Database Support for details. You can also use IsSupported(AdbProvider) at runtime to determine whether a given provider is supported with this worker.

Rows will be inserted in batches and transactions according to how the provider IAdbInsertStatementService has been configured. The out-of-box providers typically use multi-row batches and also wrap the batches into periodic transactions. To change the defaults, either use SetRowLimits(Int32, Int64) on this worker, or use AConfig configurations with the InsertStatementValuesPerBatch and InsertStatementValuesPerTransaction string keys, or create a new provider instance with e.g. With(String, IAdbInsertStatementService).

Using any transactions will automatically set ErrorOutput.MaxRowsBeforeError to 0 (i.e. fail on the first batch error).

Note however that creating transactions is automatically disabled when the ErrorOutput port has been linked to a downstream worker, since otherwise rows could end up processed several different ways (rows successfully inserted, incorrect and correct rows sent to downstream worker, and rows rolled back) which would be difficult to program against.

This worker does participate in any pre-existing transaction currently active on the connection. Using both a transaction and linking the ErrorOutput port to a downstream worker is however incompatible, and would fail the worker.

Note that with multiple rows per batch or transaction, any insert error will reject all the rows in the batch or transaction. Only the failed batch insert will be sent to ErrorOutput, even if transactions are used and some or all previous batches are rolled back.

The Input port is linked to (if available) the upstream output or error output port specified by the factory.

Get the factory from Link when the upstream port is known ahead of time (which is usually the case). Otherwise get it from GetDownstreamFactory<TInput>(), and link the transform or target explicitly using LinkTo(InputPort<TOutput>) or LinkFrom(OutputPortBase<TInput>).

The following exceptions can occur when the worker runs:

ArgumentNullException	ConnectionBuilder
ArgumentException	CompositeTableName
InvalidOperationException	- No column name matches found. - Cannot both use transactions and link the ErrorOutput port.

Inheritance

Object

AdbInsertTargetFactory

Namespace: actionETL.Adb

Assembly: actionETL.dll

Syntax

public static class AdbInsertTargetFactory

Methods

AdbInsertTarget<TInputError>(in DownstreamFactory<TInputError>, String, IAdbConnectionBuilder, String)

Initializes a new instance of the AdbInsertTarget<TInputError> dataflow worker, which inserts all incoming rows into a SQL table or view. It also has an ErrorOutput port that receives any rows that throw an exception when creating and executing their queries.

The Input port is linked to (if available) the upstream output or error output port specified by the factory.

Only columns where the incoming column name and the external database name match will be mapped (see AutoName() overloads for details).

Column name matching is ordinal case insensitive, but a case sensitive match takes precedence over a case insensitive match.

Declaration

public static AdbInsertTarget<TInputError> AdbInsertTarget<TInputError>(this in DownstreamFactory<TInputError> downstreamFactory, string workerName, IAdbConnectionBuilder connectionBuilder, string compositeTableName)
    where TInputError : class

Parameters

Type	Name	Description
DownstreamFactory<TInputError>	downstreamFactory	The downstream factory, which specifies the parent worker and (optionally) the upstream port to link the "first" input port of this dataflow worker to. Get it from Link when the upstream port is known ahead of time (which is usually the case). Otherwise get it from GetDownstreamFactory<TInput>(), and link the transform or target explicitly using LinkTo(InputPort<TOutput>) or LinkFrom(OutputPortBase<TInput>).
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 "__".
IAdbConnectionBuilder	connectionBuilder	The connection builder. Can be null, in which case the ConnectionBuilder property must be set before the worker runs.
String	compositeTableName	Name of the table to insert into. The string must have a format appropriate for the data source. E.g. for the SqlClient provider: Product, dbo.Product, [Sales].[dbo].[Internet Sales], or "Sales"."dbo"."Internet Sales".

Returns

Type	Description
AdbInsertTarget<TInputError>	The newly created and (optionally) linked worker.

Type Parameters

Name	Description
TInputError	The type of each Input and ErrorOutput row.

Exceptions

Type	Condition
ArgumentException	connectionBuilder - The provider does not support either the IAdbInsertStatementService or the IAdbTableInformationService.
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?

AdbInsertTarget<TInputError>(in DownstreamFactory<TInputError>, String, Action<IColumnMapperCommand>, IAdbConnectionBuilder, String)

Initializes a new instance of the AdbInsertTarget<TInputError> dataflow worker, which inserts all incoming rows into a SQL table or view. It also has an ErrorOutput port that receives any rows that throw an exception when creating and executing their queries.

The Input port is linked to (if available) the upstream output or error output port specified by the factory.

Declaration

public static AdbInsertTarget<TInputError> AdbInsertTarget<TInputError>(this in DownstreamFactory<TInputError> downstreamFactory, string workerName, Action<IColumnMapperCommand> columnMapperCommandAction, IAdbConnectionBuilder connectionBuilder, string compositeTableName)
    where TInputError : class

Parameters

Type	Name	Description
DownstreamFactory<TInputError>	downstreamFactory	The downstream factory, which specifies the parent worker and (optionally) the upstream port to link the "first" input port of this dataflow worker to. Get it from Link when the upstream port is known ahead of time (which is usually the case). Otherwise get it from GetDownstreamFactory<TInput>(), and link the transform or target explicitly using LinkTo(InputPort<TOutput>) or LinkFrom(OutputPortBase<TInput>).
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 "__".
Action<IColumnMapperCommand>	columnMapperCommandAction	Defines mappings between input columns and external database columns. Can be null, in which case only columns where the incoming column name and the external database name match will be mapped (see AutoName() overloads for details). Column name matching is ordinal case insensitive, but a case sensitive match takes precedence over a case insensitive match. Also see Dataflow Column Mapping.
IAdbConnectionBuilder	connectionBuilder	The connection builder. Can be null, in which case the ConnectionBuilder property must be set before the worker runs.
String	compositeTableName	Name of the table to insert into. The string must have a format appropriate for the data source. E.g. for the SqlClient provider: Product, dbo.Product, [Sales].[dbo].[Internet Sales], or "Sales"."dbo"."Internet Sales".

Returns

Type	Description
AdbInsertTarget<TInputError>	The newly created and (optionally) linked worker.

Type Parameters

Name	Description
TInputError	The type of each Input and ErrorOutput row.

Exceptions

Type	Condition
ArgumentException	connectionBuilder - The provider does not support either the IAdbInsertStatementService or the IAdbTableInformationService.
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?

IsSupported(AdbProvider)

Returns true if the AdbInsertTarget<TInputError> worker is supported with the specified Adb provider; otherwise, false.

Both IAdbTableInformationService and IAdbInsertStatementService are required for the worker to be supported.

Declaration

public static bool IsSupported(AdbProvider adbProvider)

Parameters

Type	Name	Description
AdbProvider	adbProvider	The Adb provider.

Returns

Type	Description
Boolean

Exceptions

Type	Condition
ArgumentNullException	adbProvider

See Also

AdbInsertTarget<TInputError>

AdbCommandBuilder