Table of Contents

Class DbClient

Namespace
TimeCockpit.Data.Database
Assembly
TimeCockpit.Data.dll

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

public abstract class DbClient : IDisposable
Inheritance
System.Object
DbClient
Implements
System.IDisposable
Derived
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()

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.

public byte[] BlobEncryptionKey { get; set; }

Property Value

System.Byte[]

ConnectionName

Gets or sets the name of the connection

public string ConnectionName { get; set; }

Property Value

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

protected DbTransaction CurrentTransaction { get; }

Property Value

System.Data.Common.DbTransaction

DatabaseConnectionMode

Gets or sets the database connection mode.

public DatabaseConnectionMode DatabaseConnectionMode { get; set; }

Property Value

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

protected object DbConnectionLockObject { get; }

Property Value

System.Object

RetryStrategy

Gets the retry strategy for database operations.

protected RetryStrategy RetryStrategy { get; set; }

Property Value

TimeCockpit.Common.Database.RetryStrategy

SkipBlobGarbageCollection

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

protected virtual bool SkipBlobGarbageCollection { get; }

Property Value

System.Boolean

SupportsNoCheckConstraint

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

public abstract bool SupportsNoCheckConstraint { get; }

Property Value

System.Boolean

SupportsTableValuedParameters

Gets a value indicating whether this db client supports TVPs.

public abstract bool SupportsTableValuedParameters { get; }

Property Value

System.Boolean

TenantSchema

Gets the database schema the instance of DbClient operates on.

public string TenantSchema { get; }

Property Value

System.String

TransactionCount

Gets the nesting level of the current transaction

public int TransactionCount { get; }

Property Value

System.Int32

Remarks

TransactionCount is zero if no transaction is currently open.

See Also

UserAccountId

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

public Guid UserAccountId { get; }

Property Value

System.Guid

Methods

AddSqlParameters(IEnumerable<QueryParameter>, DbCommand)

Adds the SQL parameters to a query.

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

Parameters

queryParameters System.Collections.Generic.IEnumerable<QueryParameter>

The query parameters to use..

cmd System.Data.Common.DbCommand

An instance of System.Data.SqlClient.SqlCommand.

BeginTransaction()

Begins a new transaction

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

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

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

System.InvalidOperationException

There is currently no open transaction

Create(DbClientSettings)

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

public static DbClient Create(DbClientSettings settings)

Parameters

settings DbClientSettings

And instance DbClientSettings that defines the behavior of the created DbClient instance.

Returns

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

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.

protected DbConnection CreateAndOpenConnection()

Returns

System.Data.Common.DbConnection

Opened db connection.

DeleteBlobGarbage(DbConnection, IEnumerable<BlobGarbageRow>)

Deletes rows from the blob garbage collection

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

Parameters

connection System.Data.Common.DbConnection

Database connection used to access the database

blobGarbageCollection System.Collections.Generic.IEnumerable<BlobGarbageRow>

Guids of the blob that should be deleted

Dispose()

Releases database connection.

public void Dispose()

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

Executes a database operation.

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

Parameters

commandCreator System.Func<System.Data.Common.DbConnection, System.UInt64, System.Data.Common.DbCommand>

Function that is used to create the database command object.

synContent System.Boolean

Indicates if an changes of an entity object or model entity are synced.

Returns

System.UInt64

Version of the database operation

ExecuteOperation(Operation, Nullable<Guid>)

Executes an operation.

public void ExecuteOperation(Operation operation, Guid? currentSyncSource)

Parameters

operation Operation

Contains the operation to execute.

currentSyncSource System.Nullable<System.Guid>

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.

protected abstract DbCommand FindOrCreateCommand(string sqlText, DbConnection connection)

Parameters

sqlText System.String

The SQL command text; always a SELECT statement.

connection System.Data.Common.DbConnection

The database connection on which the command will be executed.

Returns

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.

protected abstract void FinishCommand(DbCommand command)

Parameters

command System.Data.Common.DbCommand

A command previously returned by FindOrCreateCommand(String, DbConnection).

GetConnection()

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

protected virtual DbConnection GetConnection()

Returns

System.Data.Common.DbConnection

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

GetConnectionString(DbClientSettings)

Extracts the connection string from a set of settings.

protected virtual string GetConnectionString(DbClientSettings settings)

Parameters

settings DbClientSettings

Settings to extract from.

Returns

System.String

Final connection string.

GetDataAdapter()

Creates a data adapter.

protected DbDataAdapter GetDataAdapter()

Returns

System.Data.Common.DbDataAdapter

New data adapter

GetLastUpdateVersionsOfEntities(String[])

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

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

Parameters

entities System.String[]

A list of entities to get the update version for.

Returns

System.Collections.Generic.IDictionary<System.String, System.UInt64>

returns a dictionary of entity name and last update version.

IgnoreExceptionDuringCyclicConstraintHandling(Exception) 

protected virtual bool IgnoreExceptionDuringCyclicConstraintHandling(Exception e)

Parameters

e System.Exception

Returns

System.Boolean

OpenConnectionAsync(CancellationToken)

Opens a new connection.

protected abstract Task<DbConnection> OpenConnectionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken System.Threading.CancellationToken

The cancellation token.

Returns

System.Threading.Tasks.Task<System.Data.Common.DbConnection>

Returns the newly opened connection.

ReleaseConnection(Boolean)

Releases the internally stored db connection.

protected void ReleaseConnection(bool forceClose = false)

Parameters

forceClose System.Boolean

Force release even when the connection mode does not require it.

RollbackTransaction()

Rolls a transaction back

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

System.InvalidOperationException

There is currently no open transaction

SetThreadCulture()

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

protected void SetThreadCulture()

SplitAndExecuteCommandsInTransaction(DbCommand)

Executes the given command

protected void SplitAndExecuteCommandsInTransaction(DbCommand command)

Parameters

command System.Data.Common.DbCommand

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

public bool TryCommitTransaction()

Returns

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

System.InvalidOperationException

There is currently no open transaction

TryCommitTransactionInternal()

Commits the current transaction

protected bool TryCommitTransactionInternal()

Returns

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

System.InvalidOperationException

There is currently no open transaction

TryRollbackTransaction()

Rolls a transaction back

public bool TryRollbackTransaction()

Returns

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

System.InvalidOperationException

There is currently no open transaction

TryRollbackTransactionInternal()

Rolls a transaction back

protected bool TryRollbackTransactionInternal()

Returns

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

System.InvalidOperationException

There is currently no open transaction

Events

BlobGarbageCleanupFinished

Occurs when the BLOB garbage cleanup has started.

public event DbClient.BlobGarbageCleanupWorkerFinished BlobGarbageCleanupFinished

Event Type

DbClient.BlobGarbageCleanupWorkerFinished