Class DbClient

Provides the base class for classes that are used to retrive/store data and apply changes to database schemas.

Inheritance

System.Object

DbClient

SqlDbClient

Implements

System.IDisposable

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: TimeCockpit.Data.Database

Assembly: TimeCockpit.Data.dll

Syntax

public abstract class DbClient : IDisposable

Properties

BlobEncryptionKey

Gets or sets the optional encryption key used for storing blobs. Blob encryption key must be 32 Bytes long or null to disable encryption support.

Declaration

public byte[] BlobEncryptionKey { get; set; }

Property Value

Type	Description
System.Byte[]

ConnectionName

Gets or sets the name of the connection

Declaration

public string ConnectionName { get; set; }

Property Value

Type	Description
System.String

Remarks

The connection name can be set explicitly. If you have not set the name explicitly the getter returns the Server keyword from the connection's connection string. If the Server keyword cannot be found the Data Source setting is used instead. If the Data Source setting isn't set, too, an empty string is returned by the getter.

CurrentTransaction

Gets the currently running transaction

Declaration

protected DbTransaction CurrentTransaction { get; }

Property Value

Type	Description
System.Data.Common.DbTransaction

DatabaseConnectionMode

Gets or sets the database connection mode.

Declaration

public DatabaseConnectionMode DatabaseConnectionMode { get; set; }

Property Value

Type	Description
DatabaseConnectionMode

Remarks

This property indicates if a connection should always be kept open or if a new connection should be fetched from the connection pool.

DbConnectionLockObject

Gets the lock object for member dbConnection

Declaration

protected object DbConnectionLockObject { get; }

Property Value

Type	Description
System.Object

RetryStrategy

Gets the retry strategy for database operations.

Declaration

protected RetryStrategy RetryStrategy { get; set; }

Property Value

Type	Description
TimeCockpit.Common.Database.RetryStrategy

SkipBlobGarbageCollection

Gets a value indicating whether blob garbage collection should be skipped.

Declaration

protected virtual bool SkipBlobGarbageCollection { get; }

Property Value

Type	Description
System.Boolean

SupportsNoCheckConstraint

Gets a value indicating whether this db client supports disabling constraints.

Declaration

public abstract bool SupportsNoCheckConstraint { get; }

Property Value

Type	Description
System.Boolean

SupportsTableValuedParameters

Gets a value indicating whether this db client supports TVPs.

Declaration

public abstract bool SupportsTableValuedParameters { get; }

Property Value

Type	Description
System.Boolean

TenantSchema

Gets the database schema the instance of DbClient operates on.

Declaration

public string TenantSchema { get; }

Property Value

Type	Description
System.String

TransactionCount

Gets the nesting level of the current transaction

Declaration

public int TransactionCount { get; }

Property Value

Type	Description
System.Int32

Remarks

TransactionCount is zero if no transaction is currently open.

See Also

BeginTransaction()

CommitTransaction()

RollbackTransaction()

TryCommitTransaction()

TryRollbackTransaction()

UserAccountId

Gets the id of the user this DbClient was created for.

Declaration

public Guid UserAccountId { get; }

Property Value

Type	Description
System.Guid

Methods

AddSqlParameters(IEnumerable<QueryParameter>, DbCommand)

Adds the SQL parameters to a query.

Declaration

protected void AddSqlParameters(IEnumerable<QueryParameter> queryParameters, DbCommand cmd)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<QueryParameter>	queryParameters	The query parameters to use..
System.Data.Common.DbCommand	cmd	An instance of System.Data.SqlClient.SqlCommand.

BeginTransaction()

Begins a new transaction

Declaration

public void BeginTransaction()

Remarks

This methods starts a new transaction. If you call this method multiple times without calling CommitTransaction(), RollbackTransaction(), TryCommitTransaction() or TryRollbackTransaction() in between the transaction is nested. You can query the current transaction nesting level using TransactionCount.

To call this method from IronPython or another dynamic language the DataContext is to be used. That is, to start a transaction from a dynamic language, call Context.BeginTransaction();

BeginTransactionInternal()

Begins a new transaction

Declaration

protected void BeginTransactionInternal()

Remarks

This methods starts a new transaction. If you call this method multiple times without calling CommitTransaction(), RollbackTransaction(), TryCommitTransaction() or TryRollbackTransaction() in between the transaction is nested. You can query the current transaction nesting level using TransactionCount.

CommitTransaction()

Commits the current transaction

Declaration

public void CommitTransaction()

Remarks

This methods commits the current transaction. In case of nested transactions the transaction nesting level (see TransactionCount) is decremented.

To call this method from IronPython or another dynamic language the DataContext is to be used. That is, to start a transaction from a dynamic language, call Context.CommitTransaction();

Exceptions

Type	Condition
System.InvalidOperationException	There is currently no open transaction

Create(DbClientSettings)

Creates a new instance of the DbClient class based on the specified DbClientSettings.

Declaration

public static DbClient Create(DbClientSettings settings)

Parameters

Type	Name	Description
DbClientSettings	settings	And instance DbClientSettings that defines the behavior of the created DbClient instance.

Returns

Type	Description
DbClient	New instance of the DbClient class.

Remarks

Depending on ProviderName, the new instance of DbClient can either connect to a SQL Server Compact Edition or an instance of SQL Server. Further, depending on the provider name, either a BlobStorageType of type Local or Azure is associated with the DbClient.

Exceptions

Type	Condition
System.ArgumentException	Thrown if the ProviderName is unknown, or if both AzureBlobStorageKey AND AzureSharedAccessKey are set.
System.ArgumentOutOfRangeException	Thrown if AzureBlobStorageAccountName is null and either AzureBlobStorageKey or AzureSharedAccessKey is null.
VersionCheckException	Thrown if PerformVersionCheck is true, and mandatory installation components are missing.

CreateAndOpenConnection()

Create a new, standalone, opened db connection.

Declaration

protected DbConnection CreateAndOpenConnection()

Returns

Type	Description
System.Data.Common.DbConnection	Opened db connection.

DeleteBlobGarbage(DbConnection, IEnumerable<BlobGarbageRow>)

Deletes rows from the blob garbage collection

Declaration

protected abstract void DeleteBlobGarbage(DbConnection connection, IEnumerable<BlobGarbageRow> blobGarbageCollection)

Parameters

Type	Name	Description
System.Data.Common.DbConnection	connection	Database connection used to access the database
System.Collections.Generic.IEnumerable<BlobGarbageRow>	blobGarbageCollection	Guids of the blob that should be deleted

Dispose()

Releases database connection.

Declaration

public void Dispose()

Implements

System.IDisposable.Dispose()

ExecuteDatabaseOperation(Func<DbConnection, UInt64, DbCommand>, Boolean)

Executes a database operation.

Declaration

protected abstract ulong ExecuteDatabaseOperation(Func<DbConnection, ulong, DbCommand> commandCreator, bool synContent)

Parameters

Type	Name	Description
System.Func<System.Data.Common.DbConnection, System.UInt64, System.Data.Common.DbCommand>	commandCreator	Function that is used to create the database command object.
System.Boolean	synContent	Indicates if an changes of an entity object or model entity are synced.

Returns

Type	Description
System.UInt64	Version of the database operation

ExecuteOperation(Operation, Nullable<Guid>)

Executes an operation.

Declaration

public void ExecuteOperation(Operation operation, Guid? currentSyncSource)

Parameters

Type	Name	Description
Operation	operation	Contains the operation to execute.
System.Nullable<System.Guid>	currentSyncSource	A guid identifying the client that last synced the given entity object

FindOrCreateCommand(String, DbConnection)

Create DB command by looking it up in a cache of prepared commands or creating it.

Declaration

protected abstract DbCommand FindOrCreateCommand(string sqlText, DbConnection connection)

Parameters

Type	Name	Description
System.String	sqlText	The SQL command text; always a SELECT statement.
System.Data.Common.DbConnection	connection	The database connection on which the command will be executed.

Returns

Type	Description
System.Data.Common.DbCommand	DB command from the cache or newly created command.

Remarks

Implementers who want to create a cache of prepared commands should look for a cached command for sqlText. If the cache contains an appropriate command, a reference to this command should be returned. If it doesn't, a new command should be created and returned. After DbClient is done with the command, FinishCommand(DbCommand) will be called. Use that method to clean up (e.g. dispose newly created command).

FinishCommand(DbCommand)

Called after DbClient is done with the command.

Declaration

protected abstract void FinishCommand(DbCommand command)

Parameters

Type	Name	Description
System.Data.Common.DbCommand	command	A command previously returned by FindOrCreateCommand(String, DbConnection).

GetConnection()

Creates a connection with the provided System.Data.Common.DbProviderFactory and opens the created connection.

Declaration

protected virtual DbConnection GetConnection()

Returns

Type	Description
System.Data.Common.DbConnection	Returns an open System.Data.Common.DbConnection object.

GetConnectionString(DbClientSettings)

Extracts the connection string from a set of settings.

Declaration

protected virtual string GetConnectionString(DbClientSettings settings)

Parameters

Type	Name	Description
DbClientSettings	settings	Settings to extract from.

Returns

Type	Description
System.String	Final connection string.

GetDataAdapter()

Creates a data adapter.

Declaration

protected DbDataAdapter GetDataAdapter()

Returns

Type	Description
System.Data.Common.DbDataAdapter	New data adapter

GetLastUpdateVersionsOfEntities(String[])

Gets the last update versions of all non-system entities.

Declaration

public IDictionary<string, ulong> GetLastUpdateVersionsOfEntities(string[] entities)

Parameters

Type	Name	Description
System.String[]	entities	A list of entities to get the update version for.

Returns

Type	Description
System.Collections.Generic.IDictionary<System.String, System.UInt64>	returns a dictionary of entity name and last update version.

IgnoreExceptionDuringCyclicConstraintHandling(Exception)

Declaration

protected virtual bool IgnoreExceptionDuringCyclicConstraintHandling(Exception e)

Parameters

Type	Name	Description
System.Exception	e

Returns

Type	Description
System.Boolean

OpenConnectionAsync(CancellationToken)

Opens a new connection.

Declaration

protected abstract Task<DbConnection> OpenConnectionAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task<System.Data.Common.DbConnection>	Returns the newly opened connection.

ReleaseConnection(Boolean)

Releases the internally stored db connection.

Declaration

protected void ReleaseConnection(bool forceClose = false)

Parameters

Type	Name	Description
System.Boolean	forceClose	Force release even when the connection mode does not require it.

RollbackTransaction()

Rolls a transaction back

Declaration

public void RollbackTransaction()

Remarks

This methods rolls the current transaction back. In case of nested transactions the transaction nesting level (see TransactionCount) is decremented.

To call this method from IronPython or another dynamic language the DataContext is to be used. That is, to start a transaction from a dynamic language, call Context.RollbackTransaction();

Exceptions

Type	Condition
System.InvalidOperationException	There is currently no open transaction

SetThreadCulture()

Sets calling threads (UI)Culture to this.CurrentUserCulture if available.

Declaration

protected void SetThreadCulture()

SplitAndExecuteCommandsInTransaction(DbCommand)

Executes the given command

Declaration

protected void SplitAndExecuteCommandsInTransaction(DbCommand command)

Parameters

Type	Name	Description
System.Data.Common.DbCommand	command	Command that should be executed

Remarks

If the command consists of multiple statements that are separated by "GO" the methods splits up the statements and executes each one of them separately. All separate statements are included in a single transaction.

TryCommitTransaction()

Commits the current transaction

Declaration

public bool TryCommitTransaction()

Returns

Type	Description
System.Boolean	Value indicating whether the operation was successfull

Remarks

This methods commits the current transaction. In case of nested transactions the transaction nesting level (see TransactionCount) is decremented.

To call this method from IronPython or another dynamic language the DataContext is to be used. That is, to start a transaction from a dynamic language, call Context.TryCommitTransaction();

Exceptions

Type	Condition
System.InvalidOperationException	There is currently no open transaction

TryCommitTransactionInternal()

Commits the current transaction

Declaration

protected bool TryCommitTransactionInternal()

Returns

Type	Description
System.Boolean	Value indicating whether the operation was successfull

Remarks

This methods commits the current transaction. In case of nested transactions the transaction nesting level (see TransactionCount) is decremented.

Exceptions

Type	Condition
System.InvalidOperationException	There is currently no open transaction

TryRollbackTransaction()

Rolls a transaction back

Declaration

public bool TryRollbackTransaction()

Returns

Type	Description
System.Boolean	Value indicating whether the operation was successfull

Remarks

This methods rolls the current transaction back. In case of nested transactions the transaction nesting level (see TransactionCount) is decremented.

To call this method from IronPython or another dynamic language the DataContext is to be used. That is, to start a transaction from a dynamic language, call Context.TryRollbackTransaction();

Exceptions

Type	Condition
System.InvalidOperationException	There is currently no open transaction

TryRollbackTransactionInternal()

Rolls a transaction back

Declaration

protected bool TryRollbackTransactionInternal()

Returns

Type	Description
System.Boolean	Value indicating whether the operation was successfull

Remarks

This methods rolls the current transaction back. In case of nested transactions the transaction nesting level (see TransactionCount) is decremented.

Exceptions

Type	Condition
System.InvalidOperationException	There is currently no open transaction

Events

BlobGarbageCleanupFinished

Occurs when the BLOB garbage cleanup has started.

Declaration

public event DbClient.BlobGarbageCleanupWorkerFinished BlobGarbageCleanupFinished

Event Type

Type	Description
DbClient.BlobGarbageCleanupWorkerFinished