Table of Contents

Class DataConnection

Namespace
LinqToDB.Data
Assembly
linq2db.dll

Implements persistent database connection abstraction over different database engines. Could be initialized using connection string name or connection string, or attached to existing connection or transaction.

public class DataConnection : IDataContext, IConfigurationID, IDisposable, IAsyncDisposable, IInfrastructure<IServiceProvider>
Inheritance
DataConnection
Implements
Inherited Members
Extension Methods

Constructors

DataConnection()

Creates database connection object that uses default connection configuration from DefaultConfiguration property.

public DataConnection()

DataConnection(DataOptions)

Creates database connection object that uses a DataOptions to configure the connection.

public DataConnection(DataOptions options)

Parameters

options DataOptions

Options, setup ahead of time.

DataConnection(string?)

Creates database connection object that uses provided connection configuration.

public DataConnection(string? configurationString)

Parameters

configurationString string

Name of database connection configuration to use with this connection. In case of null, configuration from DefaultConfiguration property will be used.

Fields

WriteTraceLine

Trace function. By Default use Debug class for logging, but could be replaced to log e.g. to your log file. will be ignored if UseTraceWith(DataOptions, Action<string, string, TraceLevel>) is called on builder

First parameter contains trace message.

Second parameter contains trace message category (DisplayName).

Third parameter contains trace level for message (TraceLevel).

TraceSwitch Should only not use to write trace lines, only use WriteTraceLineConnection. 
public static Action<string, string, TraceLevel> WriteTraceLine

Field Value

Action<string, string, TraceLevel>

Properties

CommandTimeout

Gets or sets command execution timeout in seconds. Supported values:

public int CommandTimeout { get; set; }

Property Value

int

ConfigurationString

Database configuration name (connection string name).

public string? ConfigurationString { get; }

Property Value

string

ConnectionString

Database connection string.

public string? ConnectionString { get; }

Property Value

string

DataProvider

Database provider implementation for specific database engine.

public IDataProvider DataProvider { get; }

Property Value

IDataProvider

DefaultConfiguration

Gets or sets default connection configuration name. Used by DataConnection by default and could be set automatically from:

- DefaultConfiguration;

- first non-global connection string name from ConnectionStrings;

- first non-global connection string name passed to SetConnectionStrings(IEnumerable<IConnectionStringSettings>) method.

public static string? DefaultConfiguration { get; set; }

Property Value

string
See Also

DefaultDataProvider

Gets or sets name of default data provider, used by new connection if user didn't specified provider explicitly in constructor or in connection options. Initialized with value from DefaultSettings.DefaultDataProvider.

public static string? DefaultDataProvider { get; set; }

Property Value

string
See Also

DefaultOnTraceConnection

Gets or sets default trace handler.

public static Action<TraceInfo> DefaultOnTraceConnection { get; set; }

Property Value

Action<TraceInfo>

DefaultSettings

Gets or sets default connection settings. By default, contains settings from linq2db configuration section from configuration file (not supported by .Net Core). ILinqToDBSettings

public static ILinqToDBSettings? DefaultSettings { get; set; }

Property Value

ILinqToDBSettings

Disposed 

protected bool Disposed { get; }

Property Value

bool

InlineParameters

Gets or sets option to force inline parameter values as literals into command text. If parameter inlining not supported for specific value type, it will be used as parameter.

public bool InlineParameters { get; set; }

Property Value

bool

LastQuery

Contains text of last command, sent to database using current connection.

public string? LastQuery { get; }

Property Value

string

MappingSchema

Gets mapping schema, used for current connection.

public MappingSchema MappingSchema { get; }

Property Value

MappingSchema

NextQueryHints

Gets list of query hints (writable collection), that will be used only for next query, executed through current connection.

public List<string> NextQueryHints { get; }

Property Value

List<string>

OnRemoveInterceptor 

public Action<IInterceptor>? OnRemoveInterceptor { get; set; }

Property Value

Action<IInterceptor>

OnTraceConnection

Gets or sets trace handler, used for current connection instance. Configured on the connection builder using UseTracing(DataOptions, Action<TraceInfo>). defaults to WriteTraceLineConnection calls.

public Action<TraceInfo> OnTraceConnection { get; set; }

Property Value

Action<TraceInfo>

Options

Current DataContext options

public DataOptions Options { get; }

Property Value

DataOptions

QueryHints

Gets list of query hints (writable collection), that will be used for all queries, executed through current connection.

public List<string> QueryHints { get; }

Property Value

List<string>

RetryPolicy

Retry policy for current connection.

public IRetryPolicy? RetryPolicy { get; set; }

Property Value

IRetryPolicy

Tag

Gets or sets a value to specify additional connection info to be used in tracing.

public string? Tag { get; set; }

Property Value

string

TraceSwitch

Gets or sets global data connection trace options. Used for all new connections unless UseTraceLevel(DataOptions, TraceLevel) is called on builder. defaults to off unless library was built in debug mode. Should only be used when TraceSwitchConnection can not be used!

public static TraceSwitch TraceSwitch { get; set; }

Property Value

TraceSwitch

TraceSwitchConnection

gets or sets the trace switch, this is used by some methods to determine if OnTraceConnection should be called. defaults to TraceSwitch used for current connection instance.

public TraceSwitch TraceSwitchConnection { get; set; }

Property Value

TraceSwitch

Transaction

Gets current transaction, associated with connection.

public DbTransaction? Transaction { get; }

Property Value

DbTransaction

WriteTraceLineConnection

Gets the delegate to write logging messages for this connection. Defaults to WriteTraceLine. Used for the current instance.

public Action<string, string, TraceLevel> WriteTraceLineConnection { get; protected set; }

Property Value

Action<string, string, TraceLevel>

Methods

AddConfiguration(string, string, IDataProvider?)

Register connection configuration with specified connection string and database provider implementation.

public static void AddConfiguration(string configuration, string connectionString, IDataProvider? dataProvider = null)

Parameters

configuration string

Connection configuration name.

connectionString string

Connection string.

dataProvider IDataProvider

Database provider. If not specified, will use provider, registered using configuration value.

AddDataProvider(IDataProvider)

Registers database provider implementation using Name name.

public static void AddDataProvider(IDataProvider dataProvider)

Parameters

dataProvider IDataProvider

Database provider implementation.

AddDataProvider(string, IDataProvider)

Registers database provider implementation by provided unique name.

public static void AddDataProvider(string providerName, IDataProvider dataProvider)

Parameters

providerName string

Provider name, to which provider implementation will be mapped.

dataProvider IDataProvider

Database provider implementation.

AddInterceptor(IInterceptor)

Adds interceptor instance to context.

public void AddInterceptor(IInterceptor interceptor)

Parameters

interceptor IInterceptor

Interceptor.

AddMappingSchema(MappingSchema)

Adds additional mapping schema to current connection.

public void AddMappingSchema(MappingSchema mappingSchema)

Parameters

mappingSchema MappingSchema

Mapping schema.

Remarks

DataConnection will share MappingSchema instances that were created by combining same mapping schemas.

AddOrSetConfiguration(string, string, string) 

public static void AddOrSetConfiguration(string configuration, string connectionString, string dataProvider)

Parameters

configuration string
connectionString string
dataProvider string

AddProviderDetector(Func<ConnectionOptions, IDataProvider?>)

Registers database provider factory method. Factory accepts connection string settings and connection string. Could return null, if cannot create provider instance using provided options.

public static void AddProviderDetector(Func<ConnectionOptions, IDataProvider?> providerDetector)

Parameters

providerDetector Func<ConnectionOptions, IDataProvider>

Factory method delegate.

BeginTransaction()

Starts new transaction for current connection with default isolation level. If connection already has transaction, it will throw InvalidOperationException.

public virtual DataConnectionTransaction BeginTransaction()

Returns

DataConnectionTransaction

Database transaction object.

Exceptions

InvalidOperationException

Thrown when connection already has a transaction.

BeginTransaction(IsolationLevel)

Starts new transaction for current connection with specified isolation level. If connection already has transaction, it will throw InvalidOperationException.

public virtual DataConnectionTransaction BeginTransaction(IsolationLevel isolationLevel)

Parameters

isolationLevel IsolationLevel

Transaction isolation level.

Returns

DataConnectionTransaction

Database transaction object.

Exceptions

InvalidOperationException

Thrown when connection already has a transaction.

BeginTransactionAsync(IsolationLevel, CancellationToken)

Starts new transaction asynchronously for current connection with specified isolation level. If connection already has transaction, it will throw InvalidOperationException.

public virtual Task<DataConnectionTransaction> BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken = default)

Parameters

isolationLevel IsolationLevel

Transaction isolation level.

cancellationToken CancellationToken

Asynchronous operation cancellation token.

Returns

Task<DataConnectionTransaction>

Database transaction object.

Exceptions

InvalidOperationException

Thrown when connection already has a transaction.

BeginTransactionAsync(CancellationToken)

Starts new transaction asynchronously for current connection with default isolation level. If connection already has transaction, it will throw InvalidOperationException.

public virtual Task<DataConnectionTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Asynchronous operation cancellation token.

Returns

Task<DataConnectionTransaction>

Database transaction object.

Exceptions

InvalidOperationException

Thrown when connection already has a transaction.

CheckAndThrowOnDisposed() 

protected void CheckAndThrowOnDisposed()

Close()

Closes and dispose associated underlying database transaction/connection.

public virtual void Close()

CloseAsync()

Closes and dispose associated underlying database transaction/connection asynchronously.

public virtual Task CloseAsync()

Returns

Task

Asynchronous operation completion task.

CommitTransaction()

Commits transaction (if any), associated with connection.

public virtual void CommitTransaction()

CommitTransactionAsync(CancellationToken)

Commits started (if any) transaction, associated with connection. If underlying provider doesn't support asynchronous commit, it will be performed synchronously.

public virtual Task CommitTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Asynchronous operation cancellation token.

Returns

Task

Asynchronous operation completion task.

Dispose()

Disposes connection.

public void Dispose()

DisposeAsync()

Disposes connection asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

Asynchronous operation completion task.

DisposeTransaction()

Disposes transaction (if any), associated with connection.

public virtual void DisposeTransaction()

DisposeTransactionAsync()

Dispose started (if any) transaction, associated with connection. If underlying provider doesn't support asynchonous disposal, it will be performed synchonously.

public virtual Task DisposeTransactionAsync()

Returns

Task

Asynchronous operation completion task.

ExecuteNonQuery(DbCommand) 

protected virtual int ExecuteNonQuery(DbCommand command)

Parameters

command DbCommand

Returns

int

ExecuteNonQueryAsync(CancellationToken) 

protected virtual Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Returns

Task<int>

ExecuteReader(CommandBehavior) 

protected virtual DataReaderWrapper ExecuteReader(CommandBehavior commandBehavior)

Parameters

commandBehavior CommandBehavior

Returns

DataReaderWrapper

ExecuteReaderAsync(CommandBehavior, CancellationToken) 

protected virtual Task<DataReaderWrapper> ExecuteReaderAsync(CommandBehavior commandBehavior, CancellationToken cancellationToken)

Parameters

commandBehavior CommandBehavior
cancellationToken CancellationToken

Returns

Task<DataReaderWrapper>

ExecuteScalar(DbCommand) 

protected virtual object? ExecuteScalar(DbCommand command)

Parameters

command DbCommand

Returns

object

ExecuteScalarAsync(CancellationToken) 

protected virtual Task<object?> ExecuteScalarAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Returns

Task<object>

GetConnectionString(string)

Returns connection string for specified connection name.

public static string GetConnectionString(string configurationString)

Parameters

configurationString string

Connection name.

Returns

string

Connection string.

GetDataProvider(string)

Returns database provider implementation, associated with provided connection configuration name.

public static IDataProvider GetDataProvider(string configurationString)

Parameters

configurationString string

Connection configuration name.

Returns

IDataProvider

Database provider.

GetDataProvider(string, string)

Returns database provider associated with provider name and connection string.

public static IDataProvider? GetDataProvider(string providerName, string connectionString)

Parameters

providerName string

Provider name.

connectionString string

Connection string.

Returns

IDataProvider

Database provider.

GetDataProvider(string, string, string)

Returns database provider associated with provider name, configuration and connection string.

public static IDataProvider? GetDataProvider(string providerName, string configurationString, string connectionString)

Parameters

providerName string

Provider name.

configurationString string

Connection configuration name.

connectionString string

Connection string.

Returns

IDataProvider

Database provider.

GetRegisteredProviders()

Returns registered database providers.

public static IReadOnlyDictionary<string, IDataProvider> GetRegisteredProviders()

Returns

IReadOnlyDictionary<string, IDataProvider>

Returns registered providers collection.

InsertProviderDetector(Func<ConnectionOptions, IDataProvider?>)

Registers database provider factory method. Factory accepts connection string settings and connection string. Could return null, if cannot create provider instance using provided options.

public static void InsertProviderDetector(Func<ConnectionOptions, IDataProvider?> providerDetector)

Parameters

providerDetector Func<ConnectionOptions, IDataProvider>

Factory method delegate.

OpenDbConnection()

Returns underlying DbConnection instance. If connection is not open yet - it will be opened.

public DbConnection OpenDbConnection()

Returns

DbConnection

OpenDbConnectionAsync(CancellationToken)

Returns underlying DbConnection instance. If connection is not open yet - it will be opened.

public Task<DbConnection> OpenDbConnectionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Returns

Task<DbConnection>

ProcessQuery(SqlStatement, EvaluationContext) 

protected virtual SqlStatement ProcessQuery(SqlStatement statement, EvaluationContext context)

Parameters

statement SqlStatement
context EvaluationContext

Returns

SqlStatement

RemoveInterceptor(IInterceptor)

Removes interceptor instance from context.

public void RemoveInterceptor(IInterceptor interceptor)

Parameters

interceptor IInterceptor

Interceptor.

ResetCommandTimeout()

Resets command timeout to provider or connection defaults. Note that default provider/connection timeout is not the same value as timeout value you can specify upon context configuration.

public void ResetCommandTimeout()

ResetCommandTimeoutAsync()

Sets command timeout to default connection value. Note that default provider/connection timeout is not the same value as timeout value you can specify upon context configuration.

public ValueTask ResetCommandTimeoutAsync()

Returns

ValueTask

RollbackTransaction()

Rollbacks transaction (if any), associated with connection.

public virtual void RollbackTransaction()

RollbackTransactionAsync(CancellationToken)

Rollbacks started (if any) transaction, associated with connection. If underlying provider doesn't support asynchronous commit, it will be performed synchronously.

public virtual Task RollbackTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Asynchronous operation cancellation token.

Returns

Task

Asynchronous operation completion task.

SetConnectionString(string, string)

Sets connection string for specified connection name.

public static void SetConnectionString(string configuration, string connectionString)

Parameters

configuration string

Connection name.

connectionString string

Connection string.

SetConnectionStrings(IEnumerable<IConnectionStringSettings>)

Register connection strings for use by data connection class.

public static void SetConnectionStrings(IEnumerable<IConnectionStringSettings> connectionStrings)

Parameters

connectionStrings IEnumerable<IConnectionStringSettings>

Collection of connection string configurations.

TraceActionAsync<TContext, TResult>(DataConnection, TraceOperation, Func<TContext, string?>?, TContext, Func<DataConnection, TContext, CancellationToken, Task<TResult>>, CancellationToken) 

protected static Task<TResult> TraceActionAsync<TContext, TResult>(DataConnection dataConnection, TraceOperation traceOperation, Func<TContext, string?>? commandText, TContext context, Func<DataConnection, TContext, CancellationToken, Task<TResult>> action, CancellationToken cancellationToken)

Parameters

dataConnection DataConnection
traceOperation TraceOperation
commandText Func<TContext, string>
context TContext
action Func<DataConnection, TContext, CancellationToken, Task<TResult>>
cancellationToken CancellationToken

Returns

Task<TResult>

Type Parameters

TContext
TResult

TraceAction<TContext, TResult>(DataConnection, TraceOperation, Func<TContext, string?>?, TContext, Func<DataConnection, TContext, TResult>) 

protected static TResult TraceAction<TContext, TResult>(DataConnection dataConnection, TraceOperation traceOperation, Func<TContext, string?>? commandText, TContext context, Func<DataConnection, TContext, TResult> action)

Parameters

dataConnection DataConnection
traceOperation TraceOperation
commandText Func<TContext, string>
context TContext
action Func<DataConnection, TContext, TResult>

Returns

TResult

Type Parameters

TContext
TResult

TryGetConnectionString(string?)

Returns connection string for specified configuration name or NULL.

public static string? TryGetConnectionString(string? configurationString)

Parameters

configurationString string

Configuration.

Returns

string

Connection string or NULL.

TryGetDbConnection()

Returns underlying DbConnection instance or null if connection is not open.

public DbConnection? TryGetDbConnection()

Returns

DbConnection

TurnTraceSwitchOn(TraceLevel)

Sets tracing level for data connections.

public static void TurnTraceSwitchOn(TraceLevel traceLevel = TraceLevel.Info)

Parameters

traceLevel TraceLevel

Connection tracing level.

Remarks

Use TraceSwitchConnection when possible, configured via UseTraceLevel(DataOptions, TraceLevel).

UseMappingSchema(MappingSchema)

Sets new mapping schema for current data context.

Implements the Disposable pattern, which must be used to properly restore previous settings. 

public IDisposable? UseMappingSchema(MappingSchema mappingSchema)

Parameters

mappingSchema MappingSchema

Mapping schema to set.

Returns

IDisposable

UseOptions(Func<DataOptions, DataOptions>)

Sets new options for current data context.

Implements the Disposable pattern, which must be used to properly restore previous options. 

public IDisposable? UseOptions(Func<DataOptions, DataOptions> optionsSetter)

Parameters

optionsSetter Func<DataOptions, DataOptions>

Options setter function.

Returns

IDisposable

Returns disposable object, which could be used to restore previous options.

Remarks

For ConnectionOptions we update only mapping schema and connection interceptor. Connection string, configuration, data provider, etc. are not updatable.

Exceptions

ArgumentNullException