Search Results for

    Show / Hide Table of Contents

    Class AdbConnection

    An Adb database connection, similar to a DbConnection, including creating database commands, with extra information and functionality. It is created by an AdbConnectionBuilder instance.

    This class opens and closes connections in the same way as the underlying .NET DbConnection, and is the normal type of connection to use for database access. AdbKeepOpenConnection is available for the (rare) cases when a connection should stay open across multiple workers.

    Note: The AdbConnection instance is not thread-safe, and must only be used in a single place (in a single worker) at any one time.

    Note: Database specific drivers, e.g. SqlClient and MySqlClient, sets properties like DatabaseName from the ConnectionString, before the connection is open, and sets them again with values from the database server after the connection is open. Universal drivers like ODBC do not set these properties from the connection string, and only sets them after the connection is open.

    The connection can be opened and closed multiple times as needed, and it must be disposed after use. Disposal should almost always be done by whoever created the connection, typically via DisposeOnFinished<TDisposable>(TDisposable) or UsingActionWorker<TDisposable> if used across multiple method calls, or by a using statement if created and disposed in a single method and thread, without being passed to any other workers. See Disposing Disposables for details.

    Inheritance
    Object
    AdbConnection
    AdbKeepOpenConnection
    Implements
    IAdbConnection
    IDisposable
    Namespace: actionETL.Adb
    Assembly: actionETL.dll
    Syntax
    public class AdbConnection : IAdbConnection, IDisposable
    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.

    Properties

    ConnectionString

    Gets the string used to open the connection.

    Note that setting the connection string is done via IAdbConnectionBuilder or AdbConnectionString.

    Note: Database specific drivers, e.g. SqlClient and MySqlClient, sets properties like DatabaseName from the ConnectionString, before the connection is open, and sets them again with values from the database server after the connection is open. Universal drivers like ODBC do not set these properties from the connection string, and only sets them after the connection is open.

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

    ConnectionTimeout

    Gets the time (in seconds) to wait while trying to establish a connection before terminating the attempt and generating an error.

    The default value is data source dependent; a common value is 15 seconds.

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

    DatabaseName

    Gets the unquoted name of the current database after a connection is opened.

    Before the connection is open, depending on the driver, either gets the database name specified in the connection string (with whatever quoting it had there), or an empty string.

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

    DataSourceName

    Gets the name of the database server to which to connect.

    Before the connection is open, depending on the driver, either gets the database server name specified in the connection string (with whatever quoting it had there), or an empty string.

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

    Information

    Provides and helps process the information about a data source behind a connection, such as what character to use for quoting, how to specify parameter markers etc. This is used to write provider-independent database code.

    Note that when accessing this property the first time, the connection will if needed be opened before information is retrieved, and closed again if it was not open before the property was accessed, leaving it in the original state on return. After the first time, a cached instance will be returned.

    Also see the TableInformation property.

    Declaration
    public AdbDataSourceInformation Information { get; }
    Property Value
    Type Description
    AdbDataSourceInformation

    The data source information.

    Exceptions
    Type Condition
    Exception

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

    InvalidOperationException

    May throw if the connection is associated with a transaction.

    NotImplementedException

    Not implemented for provider.

    NumberOfColumnIdentifierParts

    Gets the number of column identifier parts. E.g., if column name, table name, schema name, and catalog name are all available, this property would return 4.

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

    NumberOfColumnRestrictions

    Gets the number of column restrictions available when using GetSchema(String, String[]), see https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/retrieving-database-schema-information for details.

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

    Provider

    Gets the Adb provider that created this connection.

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

    SchemaInformationCollection

    Gets the database provider meta-data schema collections, which can be used to retrieve a schema collection with GetSchema(String) or its overloads.

    Note that when accessing this property the first time, the connection will if needed be opened before information is retrieved, and closed again if it was closed before the property was accessed. After the first time, a cached instance will be returned.

    Declaration
    public IReadOnlyList<AdbSchemaInformation> SchemaInformationCollection { get; }
    Property Value
    Type Description
    IReadOnlyList<AdbSchemaInformation>
    Exceptions
    Type Condition
    Exception

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

    InvalidOperationException

    May throw if the connection is associated with a transaction (this is provider-specific).

    ServerVersion

    On an open connection, gets a string that represents the version of the server to which the connection is connected to.

    Declaration
    public string ServerVersion { get; }
    Property Value
    Type Description
    String
    Exceptions
    Type Condition
    InvalidOperationException

    Connection was closed.

    State

    Gets an enum that describes the state of the connection.

    Declaration
    public ConnectionState State { get; }
    Property Value
    Type Description
    ConnectionState

    TableCommand

    An optional service that executes predefined database table commands (truncate, drop, delete all rows). Will be null for providers that don't support it; always check that the property is not null before using it (if you have a connection) or that HasTableCommandService is true (if checking before you have a connection).

    Also see the TableInformation and Information properties.

    Declaration
    public AdbTableCommand TableCommand { get; }
    Property Value
    Type Description
    AdbTableCommand

    TableInformation

    An optional service that manipulates table identifiers and provides information about tables, such as what tables and columns are present. Will be null for providers that don't support it; always check that the property is not null before using it (if you have a connection) or that HasTableInformationService is true (if checking before you have a connection).

    Also see the TableCommand and Information properties.

    Declaration
    public AdbTableInformation TableInformation { get; }
    Property Value
    Type Description
    AdbTableInformation

    Transaction

    The currently active AdbTransaction returned from the last BeginTransaction() call, or null if no transaction is currently active.

    Any active transaction is removed when either of its Commit(), Rollback(), or Dispose() methods are called.

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

    UnderlyingConnection

    Gets the underlying .NET DbConnection.

    Note: Always use the members on AdbConnection instead of this UnderlyingConnection wherever possible. In rare cases however, the underlying .NET DbConnection is needed, e.g. when accessing provider-specific functionality not covered by AdbConnection.

    Declaration
    public DbConnection UnderlyingConnection { get; }
    Property Value
    Type Description
    DbConnection

    Methods

    BeginTransaction()

    Starts a database transaction, using the default isolation level for the specific type of connection used. As long as it is active, any commands created from this connection will automatically use this transaction, which (when the command is created after the transaction is created) removes the need to explicitly set the AdbCommand.Transaction property.

    You must ensure that the transaction is later either committed or rolled back by using the transaction Commit() or Rollback() methods, or by closing or disposing the connection, which will roll back the transaction.

    Do consider if the default isolation level is appropriate, in terms of performance and correctness.

    Declaration
    public virtual AdbTransaction BeginTransaction()
    Returns
    Type Description
    AdbTransaction

    An object representing the new transaction.

    Exceptions
    Type Condition
    Exception

    (See the provider documentation for specific exceptions.)

    BeginTransaction(IsolationLevel)

    Starts a database transaction. As long as it is active, any commands created from this connection will automatically use this transaction, which (when the command is created after the transaction is created) removes the need to explicitly set the AdbCommand.Transaction property.

    You must ensure that the transaction is later either committed or rolled back by using the transaction Commit() or Rollback() methods, or by closing or disposing the connection, which will roll back the transaction.

    Declaration
    public virtual AdbTransaction BeginTransaction(IsolationLevel isolationLevel)
    Parameters
    Type Name Description
    IsolationLevel isolationLevel

    Specifies the isolation level for the transaction. Do consider what to set it to, since this can affect both performance and correctness.

    Returns
    Type Description
    AdbTransaction

    An object representing the new transaction.

    Exceptions
    Type Condition
    Exception

    (See the provider documentation for specific exceptions.)

    Close()

    Closes the connection to the database, which will also roll back any active transaction. This is the preferred method of closing any open connection.

    An application can call this method multiple times, without generating any exception.

    Declaration
    public virtual void Close()
    Exceptions
    Type Condition
    DbException

    The connection-level error that occurred while opening the connection.

    CreateCommand()

    Creates an Adb database command with CommandType set to Text, initialized with the connection.

    Note that the command query must be set separately.

    Declaration
    public virtual AdbCommand CreateCommand()
    Returns
    Type Description
    AdbCommand

    A database command, initialized with the connection. The command must be disposed after its use; the associated connection will not be automatically disposed at the same time.

    CreateCommand(String)

    Creates an Adb database command with CommandType set to Text, initialized with the connection.

    Declaration
    public virtual AdbCommand CreateCommand(string queryText)
    Parameters
    Type Name Description
    String queryText

    The query text.

    Returns
    Type Description
    AdbCommand

    A database command, initialized with the connection. The command must be disposed after its use; the associated connection will not be automatically disposed at the same time.

    CreateCommand(String, CommandType)

    Creates an Adb database command, initialized with the connection.

    Declaration
    public virtual AdbCommand CreateCommand(string queryText, CommandType commandType)
    Parameters
    Type Name Description
    String queryText

    The query text.

    CommandType commandType

    Type of the command.

    Returns
    Type Description
    AdbCommand

    A database command, initialized with the connection. The command must be disposed after its use; the associated connection will not be automatically disposed at the same time.

    Dispose()

    Disposes the connection, which also closes it, and rolls back any active transaction.

    Declaration
    public void Dispose()

    Dispose(Boolean)

    Releases any unmanaged resources, and optionally releases managed resources.

    Declaration
    protected virtual void Dispose(bool disposing)
    Parameters
    Type Name Description
    Boolean disposing

    true to release both managed and unmanaged resources, which includes closing the underlying .NET connection; false to release only unmanaged resources.

    GetSchema()

    Returns metadata schema information for the data source of this connection. Also see NumberOfColumnRestrictions and Retrieving Database Schema Information.

    Note that some of these schemas are already available in an easily digestible format in this class (e.g. the meta-data schema collection SchemaInformationCollection, and columns in table-like objects via one of the GetTableColumnsAsync(IAdbTableIdentifier) overloads), and in Information.

    Some providers (such as Microsoft.Data.SqlClient) may throw an exception if the connection is associated with a transaction. Therefore avoid calling this method on a connection that has an associated transaction.

    Declaration
    public DataTable GetSchema()
    Returns
    Type Description
    DataTable

    A DataTable that contains schema information.

    Exceptions
    Type Condition
    InvalidOperationException

    May throw if the connection is associated with a transaction (this is provider-specific).

    GetSchema(String)

    Returns metadata schema information for the data source of this connection using the specified string for the schema name. Also see NumberOfColumnRestrictions and Retrieving Database Schema Information.

    Note that some of these schemas are already available in an easily digestible format in this class (e.g. the meta-data schema collection SchemaInformationCollection, and columns in table-like objects via one of the GetTableColumnsAsync(IAdbTableIdentifier) overloads), and in Information.

    Note that this method does not log errors. Instead the caller should normally log any returned failure status.

    Some providers (such as Microsoft.Data.SqlClient) may throw an exception if the connection is associated with a transaction. Therefore avoid calling this method on a connection that has an associated transaction.

    Declaration
    public DataTable GetSchema(string collectionName)
    Parameters
    Type Name Description
    String collectionName

    Specifies the name of the schema to return. Must not be null.

    Returns
    Type Description
    DataTable

    A DataTable that contains schema information.

    Exceptions
    Type Condition
    ArgumentException

    collectionName is specified as null.

    InvalidOperationException

    May throw if the connection is associated with a transaction (this is provider-specific).

    GetSchema(String, String[])

    Returns metadata schema information for the data source of this connection using the specified string for the schema name and the specified string array for the restriction values. Also see NumberOfColumnRestrictions and Retrieving Database Schema Information.

    Note that some of these schemas are already available in an easily digestible format in this class (e.g. the meta-data schema collection SchemaInformationCollection, and columns in table-like objects via one of the GetTableColumnsAsync(IAdbTableIdentifier) overloads), and in Information.

    Some providers (such as Microsoft.Data.SqlClient) may throw an exception if the connection is associated with a transaction. Therefore avoid calling this method on a connection that has an associated transaction.

    Declaration
    public DataTable GetSchema(string collectionName, string[] restrictionValues)
    Parameters
    Type Name Description
    String collectionName

    Specifies the name of the schema to return. Must not be null.

    String[] restrictionValues

    Specifies a set of restriction values for the requested schema.

    Returns
    Type Description
    DataTable

    A DataTable that contains schema information.

    Exceptions
    Type Condition
    ArgumentException

    collectionName is specified as null.

    InvalidOperationException

    May throw if the connection is associated with a transaction (this is provider-specific).

    Open()

    Opens a database connection with the settings specified by the connection string.

    Declaration
    public virtual void Open()
    Exceptions
    Type Condition
    Exception

    (See the provider documentation for specific exceptions.)

    OpenAsync()

    Opens the connection asynchronously if the provider supports it, otherwise it calls Open() and returns a completed task. Any exceptions thrown by OpenAsync() will be communicated via the returned task Exception property. Do not invoke other methods and properties of the connection object until the returned task is complete.

    Declaration
    public virtual Task OpenAsync()
    Returns
    Type Description
    Task

    A task representing the asynchronous operation. The task will contain any exceptions raised (see the provider documentation for specific exceptions).

    OpenAsync(CancellationToken)

    Opens the connection asynchronously if the provider supports it, otherwise it calls Open() and returns a completed task (or a canceled task if cancellationToken is canceled). Any exceptions thrown by Open() will be communicated via the returned task Exception property. Do not invoke other methods and properties of the connection object until the returned task is complete.

    Declaration
    public virtual Task OpenAsync(CancellationToken cancellationToken)
    Parameters
    Type Name Description
    CancellationToken cancellationToken

    The cancellation token.

    Returns
    Type Description
    Task

    A task representing the asynchronous operation. The task will contain any exceptions raised (see the provider documentation for specific exceptions).

    OpenCloseIfRequired(Action<IAdbConnection>)

    Synchronously opens the connection only if it's closed, then runs a synchronous action that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The action itself should not open or close the connection.

    This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

    Declaration
    public void OpenCloseIfRequired(Action<IAdbConnection> action)
    Parameters
    Type Name Description
    Action<IAdbConnection> action

    The synchronous action that uses the open connection.

    Exceptions
    Type Condition
    ArgumentNullException

    action

    Exception

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

    OpenCloseIfRequired<TResult>(Func<IAdbConnection, TResult>)

    Synchronously opens the connection only if it's closed, then runs a synchronous function that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The function itself should not open or close the connection.

    This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

    Declaration
    public TResult OpenCloseIfRequired<TResult>(Func<IAdbConnection, TResult> func)
    Parameters
    Type Name Description
    Func<IAdbConnection, TResult> func

    The synchronous action that uses the open connection.

    Returns
    Type Description
    TResult
    Type Parameters
    Name Description
    TResult

    The type of the function result.

    Exceptions
    Type Condition
    ArgumentNullException

    func

    Exception

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

    OpenCloseIfRequiredAsync(Func<IAdbConnection, Task>)

    Asynchronously opens the connection only if it's closed, then runs an asynchronous action that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The action itself should not open or close the connection.

    This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

    Declaration
    public Task OpenCloseIfRequiredAsync(Func<IAdbConnection, Task> actionAsync)
    Parameters
    Type Name Description
    Func<IAdbConnection, Task> actionAsync

    The asynchronous action that uses the open connection.

    Returns
    Type Description
    Task
    Exceptions
    Type Condition
    ArgumentNullException

    actionAsync

    Exception

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

    OpenCloseIfRequiredAsync<TResult>(Func<IAdbConnection, Task<TResult>>)

    Asynchronously opens the connection only if it's closed, then runs an asynchronous function that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The function itself should not open or close the connection.

    This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

    Declaration
    public Task<TResult> OpenCloseIfRequiredAsync<TResult>(Func<IAdbConnection, Task<TResult>> funcAsync)
    Parameters
    Type Name Description
    Func<IAdbConnection, Task<TResult>> funcAsync

    The asynchronous action that uses the open connection.

    Returns
    Type Description
    Task<TResult>
    Type Parameters
    Name Description
    TResult

    The type of the function result.

    Exceptions
    Type Condition
    ArgumentNullException

    funcAsync

    Exception

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

    ToString()

    Returns a string that describes this instance.

    Declaration
    public override string ToString()
    Returns
    Type Description
    String
    Overrides
    Object.ToString()

    Events

    StateChange

    Occurs when the state of the connection changes.

    Declaration
    public event StateChangeEventHandler StateChange
    Event Type
    Type Description
    StateChangeEventHandler

    Implements

    IAdbConnection
    System.IDisposable

    See Also

    IAdbConnectionBuilder
    IAdbConnection
    AdbConnectionBuilder
    AdbKeepOpenConnection
    AdbCommand
    DbConnection
    In This Article
    Back to top Copyright © 2020 Envobi Ltd