Interface ITransactionManager

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Owns the transaction associated with the context's connection: starting one, enlisting in a caller-supplied one, and exposing the active transaction to the execution path. Deliberately separate from IConnectionManager (SRP) and not part of IDataContext, so the in-memory context is not forced to implement it.

public interface ITransactionManager

Extension Methods

EntityBuilderExtensions.AsEntityBuilder<T>(object?)

Remarks

Only one transaction is active at a time: starting a second one, or enlisting a transaction while one is active, throws InvalidOperationException. Like the underlying connection, the role is not thread-safe.

Properties

CurrentTransaction

The active transaction, or null when none is enlisted.

DbTransaction? CurrentTransaction { get; }

Property Value

DbTransaction

Methods

BeginTransaction()

Starts a transaction on the context's connection with the provider's default isolation level.

DbTransaction BeginTransaction()

Returns

DbTransaction

The started transaction.

BeginTransaction(IsolationLevel)

Starts a transaction on the context's connection with the given isolation level.

DbTransaction BeginTransaction(IsolationLevel isolationLevel)

Parameters

isolationLevel IsolationLevel

The isolation level to request from the provider.

Returns

DbTransaction

The started transaction.

BeginTransactionAsync(IsolationLevel, CancellationToken)

Asynchronously starts a transaction on the context's connection with the given isolation level.

Task<DbTransaction> BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken = default)

Parameters

isolationLevel IsolationLevel

The isolation level to request from the provider.

cancellationToken CancellationToken

Token used to cancel the operation.

Returns

Task<DbTransaction>

A task producing the started transaction.

BeginTransactionAsync(CancellationToken)

Asynchronously starts a transaction on the context's connection with the provider's default isolation level.

Task<DbTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token used to cancel the operation.

Returns

Task<DbTransaction>

A task producing the started transaction.

CreateSavepoint(string)

Creates a savepoint with the given name on the active (or enlisted) transaction, so a later RollbackToSavepoint(string) can undo only the work done after it.

void CreateSavepoint(string name)

Parameters

name string

The savepoint name: 1-32 characters, ASCII [A-Za-z_][A-Za-z0-9_]*. Any other name throws ArgumentException.

Remarks

The call is delegated to the provider's ADO.NET transaction. Savepoints are not tracked by nextorm: name uniqueness and nesting are the caller's responsibility, and a duplicate valid name is passed to the provider unchanged.

Declared as a default interface method so existing implementations keep compiling; an implementation that does not support savepoints throws NotSupportedException.

Exceptions

NotSupportedException

The provider does not support transactions or savepoints.

InvalidOperationException

No transaction is active on the context.

ArgumentException

The name is not a valid savepoint name.

CreateSavepointAsync(string, CancellationToken)

Asynchronously creates a savepoint with the given name on the active (or enlisted) transaction.

Task CreateSavepointAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

The savepoint name: 1-32 ASCII identifier characters.

cancellationToken CancellationToken

Token passed to the provider's asynchronous savepoint call.

Returns

Task

A task that completes once the savepoint has been created.

Remarks

Declared as a default interface method so existing implementations keep compiling.

Exceptions

NotSupportedException

The provider does not support transactions or savepoints.

InvalidOperationException

No transaction is active on the context.

ArgumentException

The name is not a valid savepoint name.

ReleaseSavepoint(string)

Releases the savepoint with the given name on the active (or enlisted) transaction. Releasing does not commit: the surrounding transaction still owns the work.

void ReleaseSavepoint(string name)

Parameters

name string

The savepoint name: 1-32 ASCII identifier characters.

Remarks

Declared as a default interface method so existing implementations keep compiling. The call is delegated to the provider, so a provider whose release is a no-op (SQL Server) keeps that behaviour instead of nextorm synthesising SQL.

Exceptions

NotSupportedException

The provider does not support transactions or savepoints.

InvalidOperationException

No transaction is active on the context.

ArgumentException

The name is not a valid savepoint name.

ReleaseSavepointAsync(string, CancellationToken)

Asynchronously releases the savepoint with the given name on the active (or enlisted) transaction.

Task ReleaseSavepointAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

The savepoint name: 1-32 ASCII identifier characters.

cancellationToken CancellationToken

Token passed to the provider's asynchronous release call.

Returns

Task

A task that completes once the savepoint has been released.

Remarks

Declared as a default interface method so existing implementations keep compiling.

Exceptions

NotSupportedException

The provider does not support transactions or savepoints.

InvalidOperationException

No transaction is active on the context.

ArgumentException

The name is not a valid savepoint name.

RollbackToSavepoint(string)

Rolls the active (or enlisted) transaction back to the savepoint with the given name, discarding only the work done after it.

void RollbackToSavepoint(string name)

Parameters

name string

The savepoint name: 1-32 ASCII identifier characters.

Remarks

Declared as a default interface method so existing implementations keep compiling. Rolling back to a savepoint does not end the transaction and does not release the savepoint unless the provider does so.

Exceptions

NotSupportedException

The provider does not support transactions or savepoints.

InvalidOperationException

No transaction is active on the context.

ArgumentException

The name is not a valid savepoint name.

RollbackToSavepointAsync(string, CancellationToken)

Asynchronously rolls the active (or enlisted) transaction back to the savepoint with the given name.

Task RollbackToSavepointAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

The savepoint name: 1-32 ASCII identifier characters.

cancellationToken CancellationToken

Token passed to the provider's asynchronous rollback call.

Returns

Task

A task that completes once the rollback has been applied.

Remarks

Declared as a default interface method so existing implementations keep compiling.

Exceptions

NotSupportedException

The provider does not support transactions or savepoints.

InvalidOperationException

No transaction is active on the context.

ArgumentException

The name is not a valid savepoint name.

TryBeginTransaction(out DbTransaction?)

Starts a transaction only when none is active, without throwing when one already is.

bool TryBeginTransaction(out DbTransaction? transaction)

Parameters

transaction DbTransaction

When this method returns true, the transaction it started; when it returns false, the already-active transaction if there is one, otherwise null.

Returns

bool

true when a transaction was started; false when one is already active (including one enlisted with UseTransaction(DbTransaction?)) or the provider does not support transactions.

Remarks

Unlike BeginTransaction(), this never throws because a transaction is already active — it returns the active one instead — and it does not throw when the provider has no transactions at all (for example ClickHouse): it returns false with null in both cases. Any other failure (for instance a connection error) still propagates.

TryBeginTransactionAsync(CancellationToken)

Asynchronously starts a transaction only when none is active, without throwing when one already is. The asynchronous counterpart of TryBeginTransaction(out DbTransaction?); it reports the outcome as a tuple because an async method cannot have an out parameter.

Task<(bool Started, DbTransaction? Transaction)> TryBeginTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token used to cancel the operation.

Returns

Task<(bool Started, DbTransaction Transaction)>

(true, transaction) when a transaction was started; (false, transaction) with the already-active transaction when one is active; (false, null) when the provider does not support transactions.

UseTransaction(DbTransaction?)

Enlists an externally owned transaction (for example the one behind DbContext.Database.CurrentTransaction). The context never commits, rolls back or disposes it. Pass null to detach such an enlisted transaction; a transaction started with BeginTransaction() must be committed, rolled back or disposed instead.

void UseTransaction(DbTransaction? transaction)

Parameters

transaction DbTransaction

The transaction to enlist, or null to detach the current one.