Class AdbCommandBuilder

An Adb command builder for an SQL statement or stored procedure and parameters to execute against a data source, similar to a DbCommand, with extra information and functionality. It creates one AdbCommand instance, as well as AdbParameter instances via the Parameters property.

Command builder instances can be created by AdbProvider factory methods, which will automatically generate an associated AdbConnectionBuilder instance. Use this approach when you don't need a direct reference to the associated AdbConnectionBuilder.

Alternatively, create an AdbConnectionBuilder (or AdbKeepOpenConnectionBuilder) instance first, and use that to in turn create AdbCommandBuilder instances.

Each AdbCommandBuilder instance has a database provider and connection string that cannot be changed after the instance is created. It can in turn create a single AdbCommand database command. Note that the AdbCommandBuilder instance cannot be used after having created the AdbCommand.

The command builder instance members are used for configuring the command, and for finally creating an AdbCommand instance.

Inheritance
Object
AdbCommandBuilder
Namespace: actionETL.Adb
Assembly: actionETL.dll
Syntax
public sealed class AdbCommandBuilder
Remarks

Do design database workers to take AdbConnectionString, IAdbConnectionBuilder, and AdbCommandBuilder instances as parameters, which allows them to support connections with different AdbConnectionMode. Conversely, avoid passing AdbConnection, AdbKeepOpenConnection, AdbCommand, or connection (text) strings to workers.

Examples

Stored Procedure Example demonstrates how to use this class.

Properties

CommandText

Gets or sets the command text to execute.

Declaration
public string CommandText { get; set; }
Property Value
Type Description
String

CommandTimeout

Gets or sets the command timeout, in seconds.

Declaration
public int CommandTimeout { get; set; }
Property Value
Type Description
Int32

CommandType

Gets or sets the command type.

Declaration
public CommandType CommandType { get; set; }
Property Value
Type Description
CommandType

Parameters

Gets the Adb parameter collection, for creating, adding and inspecting command database parameters.

Add parameters to match any parameter placeholders in the query. Named parameters in the query match to ParameterName. For providers using positional ? placeholders, add the same number of parameters as there are placeholders.

For dataflow Adb workers, by default any named parameters match to the dataflow column names; set SourceColumn to map to a different column name than the parameter name. For providers using positional ? placeholders, add the same number of parameters to the AdbCommand as there are placeholders, with parameter names matching the column names.

Declaration
public AdbParameterCollection Parameters { get; }
Property Value
Type Description
AdbParameterCollection
Exceptions
Type Condition
InvalidOperationException

The AdbCommandBuilder instance cannot be used again after calling Create().

Provider

Gets the Adb provider.

Declaration
public AdbProvider Provider { get; }
Property Value
Type Description
AdbProvider

Transaction

Gets or sets an AdbTransaction within which this command will execute. Setting the transaction is only needed if Create() is called before the transaction is created with an BeginTransaction() overload; the Create() call will automatically pick up any active transaction.

This property will throw an exception if it is accessed after the Create() method has been called.

Declaration
public AdbTransaction Transaction { get; set; }
Property Value
Type Description
AdbTransaction

The transaction, or null if there is no transaction present.
Exceptions
Type Condition
InvalidOperationException

The AdbCommandBuilder instance cannot be used again after calling Create()

Methods

Create()

Creates an AdbCommand database command instance, using the connection and command settings from the AdbCommandBuilder instance, as well as the transaction from the connection if it is currently active. The AdbCommand instance can then be used to send commands to the database.

The AdbCommand instance must be disposed after use. If the command was responsible for creating the connection, disposing the command will automatically dispose the connection. See Disposing Disposables for details.

This method can only be called once. After that, calling it again, or accessing Parameters or Transaction will throw an exception.

Declaration
public AdbCommand Create()
Returns
Type Description
AdbCommand

The database command instance.
Exceptions
Type Condition
ArgumentException

Bad ConnectionString format.
InvalidOperationException

AdbConnectionBuilder: Each instance can only create a single AdbConnection instance.
Exception

See the provider documentation for which specific exceptions Open() can throw, it typically includes DbException and InvalidOperationException.
InvalidOperationException

The AdbCommandBuilder instance cannot be used again after calling Create().
ObjectDisposedException

AdbKeepOpenConnection: Cannot call Create() after disposing the object.

StoredProcedure()

Sets the CommandType to StoredProcedure.

Declaration
public AdbCommandBuilder StoredProcedure()
Returns
Type Description
AdbCommandBuilder

The AdbCommandBuilder instance itself, allowing chaining further method calls.

StoredProcedure(String)

Sets the CommandType to StoredProcedure, and the CommandText property.

Declaration
public AdbCommandBuilder StoredProcedure(string commandText)
Parameters
Type Name Description
String commandText

The command text.
Returns
Type Description
AdbCommandBuilder

The AdbCommandBuilder instance itself, allowing chaining further method calls.

See Also