Table of Contents

Class TransactionScopeBase

Namespace
Excalibur.Data.Persistence
Assembly
Excalibur.Data.Abstractions.dll

Provides a base implementation for ITransactionScope and ITransactionScopeCallbacks with common state management, callback registration, and disposal logic.

public abstract class TransactionScopeBase : ITransactionScope, IAsyncDisposable, IDisposable, ITransactionScopeCallbacks
Inheritance
TransactionScopeBase
Implements
Inherited Members

Remarks

This base class consolidates shared logic that was duplicated across SqlServer, Postgres, and other transaction scope implementations:

  • Transaction state (TransactionId, IsolationLevel, Status, StartTime, Timeout)
  • Callback registration (OnCommit, OnRollback, OnComplete)
  • Thread-safe callback/provider collections via lock
  • Disposed/active guard methods

Derived classes implement provider-specific commit, rollback, and disposal logic.

Constructors

TransactionScopeBase(IsolationLevel, TimeSpan)

Initializes a new instance of the TransactionScopeBase class.

protected TransactionScopeBase(IsolationLevel isolationLevel, TimeSpan timeout)

Parameters

isolationLevel IsolationLevel

The transaction isolation level.

timeout TimeSpan

The transaction timeout.

Properties

Disposed

Gets a value indicating whether this scope has been disposed.

protected bool Disposed { get; set; }

Property Value

bool

IsolationLevel

Gets the isolation level of the transaction.

public IsolationLevel IsolationLevel { get; }

Property Value

IsolationLevel

The isolation level of the transaction.

StartTime

Gets the transaction start time.

public DateTimeOffset StartTime { get; }

Property Value

DateTimeOffset

The transaction start time.

Status

Gets the transaction status.

public TransactionStatus Status { get; protected set; }

Property Value

TransactionStatus

The transaction status.

Timeout

Gets or sets the transaction timeout.

public TimeSpan Timeout { get; set; }

Property Value

TimeSpan

The transaction timeout.

TransactionId

Gets the unique identifier for this transaction scope.

public string TransactionId { get; }

Property Value

string

The unique identifier for this transaction scope.

Methods

CommitAsync(CancellationToken)

Commits the transaction across all enlisted providers.

public abstract Task CommitAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A task representing the asynchronous operation.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

Releases managed and unmanaged resources.

protected abstract void Dispose(bool disposing)

Parameters

disposing bool

true to release managed resources; false for unmanaged only.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public abstract ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

EnlistConnectionAsync(IDbConnection, CancellationToken)

Enlists a database connection in the transaction.

public abstract Task EnlistConnectionAsync(IDbConnection connection, CancellationToken cancellationToken)

Parameters

connection IDbConnection

The connection to enlist.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A task representing the asynchronous operation.

EnlistProviderAsync(IPersistenceProvider, CancellationToken)

Enlists a persistence provider in the transaction.

public abstract Task EnlistProviderAsync(IPersistenceProvider provider, CancellationToken cancellationToken)

Parameters

provider IPersistenceProvider

The provider to enlist.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A task representing the asynchronous operation.

ExecuteCommitCallbacksAsync()

Executes commit callbacks, collecting any exceptions.

protected Task<List<Exception>?> ExecuteCommitCallbacksAsync()

Returns

Task<List<Exception>>

List of exceptions from failed callbacks, or null if all succeeded.

ExecuteCompleteCallbacksAsync(List<Exception>?)

Executes complete callbacks, appending any exceptions to the provided list.

protected Task<List<Exception>?> ExecuteCompleteCallbacksAsync(List<Exception>? errors)

Parameters

errors List<Exception>

List to append exceptions to. May be null; will be created if needed.

Returns

Task<List<Exception>>

The errors list (may be null if no errors occurred).

ExecuteRollbackCallbacksAsync()

Executes rollback callbacks, collecting any exceptions.

protected Task<List<Exception>?> ExecuteRollbackCallbacksAsync()

Returns

Task<List<Exception>>

List of exceptions from failed callbacks, or null if all succeeded.

GetEnlistedProviders()

Gets all enlisted providers.

public IEnumerable<IPersistenceProvider> GetEnlistedProviders()

Returns

IEnumerable<IPersistenceProvider>

Collection of enlisted providers.

OnCommit(Func<Task>)

Registers a callback to be executed after the transaction commits.

public void OnCommit(Func<Task> callback)

Parameters

callback Func<Task>

The callback to execute.

OnComplete(Func<TransactionStatus, Task>)

Registers a callback to be executed when the transaction completes (commit or rollback).

public void OnComplete(Func<TransactionStatus, Task> callback)

Parameters

callback Func<TransactionStatus, Task>

The callback to execute.

OnRollback(Func<Task>)

Registers a callback to be executed after the transaction rolls back.

public void OnRollback(Func<Task> callback)

Parameters

callback Func<Task>

The callback to execute.

RollbackAsync(CancellationToken)

Rolls back the transaction across all enlisted providers.

public abstract Task RollbackAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A task representing the asynchronous operation.

ThrowIfCallbackErrors(List<Exception>?)

Throws an AggregateException if any callback errors occurred.

protected void ThrowIfCallbackErrors(List<Exception>? errors)

Parameters

errors List<Exception>

The list of errors to check.

ThrowIfDisposed()

Throws ObjectDisposedException if this scope has been disposed.

protected void ThrowIfDisposed()

ThrowIfNotActive()

Throws InvalidOperationException if this scope is not in Active status. Also checks for timeout.

protected void ThrowIfNotActive()

TryEnlistProvider(IPersistenceProvider)

Thread-safe enlist of a provider.

protected bool TryEnlistProvider(IPersistenceProvider provider)

Parameters

provider IPersistenceProvider

The provider to enlist.

Returns

bool

True if provider was newly enlisted; false if already enlisted.