Interface IDbContextCommands

Namespace

NuvTools.Data.EntityFrameworkCore.Context

Assembly

NuvTools.Data.EntityFrameworkCore.dll

Defines common database context operations for transaction management, CRUD operations with Result pattern, and execution strategies.

public interface IDbContextCommands

Properties

CurrentTransaction

Gets the current active transaction, or null if no transaction is active.

IDbContextTransaction? CurrentTransaction { get; }

Property Value

IDbContextTransaction

Methods

AcquireTransactionLockAsync(string, CancellationToken)

Acquires an exclusive, database-wide lock identified by name, held until the current transaction commits or rolls back. Callers competing for the same name are serialized; different names never block each other.

Task AcquireTransactionLockAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

Lock name. Identifies what is being serialized, e.g. "contract-number:53".

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task

A task that completes once the lock is held.

Remarks

Use it to serialize a read-then-write that the schema alone cannot make atomic — allocating the next value of a per-tenant sequence, for instance, where every writer reads the same maximum and collides on a unique index. It is an advisory lock: it guards nothing by itself, only callers that ask for the same name.

A transaction must be active (see BeginTransactionAsync(CancellationToken)). Without one the lock is released as soon as the statement ends and protects nothing, so the call throws instead.

The statement itself lives in the provider package — pg_advisory_xact_lock in NuvTools.Data.EntityFrameworkCore.PostgreSQL, sp_getapplock (LockOwner Transaction) in NuvTools.Data.EntityFrameworkCore.SqlServer — behind IDbContextTransactionLock, and is registered by that package's AddDatabase helpers. With no such package in play (an in-memory context built by hand in a test) there is nothing to serialize and the call does nothing.

AddAndSaveAsync<TEntity, TKey>(TEntity, CancellationToken)

Adds a new entity to the database and saves changes, returning the entity's primary key.

Task<IResult<TKey>> AddAndSaveAsync<TEntity, TKey>(TEntity entity, CancellationToken cancellationToken = default) where TEntity : class

Parameters

entity TEntity

The entity to add.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<IResult<TKey>>

A task that represents the asynchronous operation, containing the result with the primary key.

Type Parameters

TEntity

The type of the entity.

TKey

The type of the primary key.

AddAndSaveWithCompositeKeyAsync<TEntity>(TEntity, CancellationToken)

Adds a new entity with a composite key to the database and saves changes.

Task<IResult<object[]>> AddAndSaveWithCompositeKeyAsync<TEntity>(TEntity entity, CancellationToken cancellationToken = default) where TEntity : class

Parameters

entity TEntity

The entity to add.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<IResult<object[]>>

A task that represents the asynchronous operation, containing the result with the composite key values.

Type Parameters

TEntity

The type of the entity.

BeginTransactionAsync(CancellationToken)

Begins a new database transaction asynchronously.

Task<IDbContextTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<IDbContextTransaction>

A task that represents the asynchronous operation, containing the database transaction.

CommitTransactionAsync(CancellationToken)

Commits the current transaction asynchronously.

Task CommitTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task

A task that represents the asynchronous operation.

ExecuteWithStrategyAsync(Func<CancellationToken, Task>, CancellationToken)

Executes an action within the database execution strategy for connection resiliency.

Task ExecuteWithStrategyAsync(Func<CancellationToken, Task> action, CancellationToken cancellationToken = default)

Parameters

action Func<CancellationToken, Task>

The action to execute within the strategy.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task

A task that represents the asynchronous operation.

See Also

https://docs.microsoft.com/en-us/ef/core/miscellaneous/connection-resiliency

ExecuteWithStrategyAsync<T>(Func<CancellationToken, Task<T>>, CancellationToken)

Executes an action within the database execution strategy for connection resiliency and returns a result.

Task<T> ExecuteWithStrategyAsync<T>(Func<CancellationToken, Task<T>> action, CancellationToken cancellationToken = default)

Parameters

action Func<CancellationToken, Task<T>>

The action to execute within the strategy.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<T>

A task that represents the asynchronous operation, containing the result of the action.

Type Parameters

T

The type of the result returned by the action.

See Also

https://docs.microsoft.com/en-us/ef/core/miscellaneous/connection-resiliency

RemoveAndSaveAsync<TEntity>(params object[])

Removes an entity from the database and saves changes.

Task<IResult> RemoveAndSaveAsync<TEntity>(params object[] keyValues) where TEntity : class

Parameters

keyValues object[]

The primary key values of the entity to remove.

Returns

Task<IResult>

A task that represents the asynchronous operation, containing the result of the remove operation.

Type Parameters

TEntity

The type of the entity.

RemoveAndSaveAsync<TEntity>(object[], CancellationToken)

Removes an entity from the database and saves changes.

Task<IResult> RemoveAndSaveAsync<TEntity>(object[] keyValues, CancellationToken cancellationToken = default) where TEntity : class

Parameters

keyValues object[]

The primary key values of the entity to remove.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<IResult>

A task that represents the asynchronous operation, containing the result of the remove operation.

Type Parameters

TEntity

The type of the entity.

RollbackTransactionAsync(CancellationToken)

Rolls back the current transaction asynchronously.

Task RollbackTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task

A task that represents the asynchronous operation.

SaveChangesAsync(CancellationToken)

Saves all changes made in this context to the database asynchronously.

Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<int>

A task that represents the asynchronous operation, containing the number of state entries written to the database.

UpdateAndSaveAsync<TEntity>(TEntity, params object[])

Updates an existing entity in the database and saves changes.

Task<IResult> UpdateAndSaveAsync<TEntity>(TEntity entity, params object[] keyValues) where TEntity : class

Parameters

entity TEntity

The entity with updated values.

keyValues object[]

The primary key values of the entity to update.

Returns

Task<IResult>

A task that represents the asynchronous operation, containing the result of the update operation.

Type Parameters

TEntity

The type of the entity.

UpdateAndSaveAsync<TEntity>(TEntity, object[], CancellationToken)

Updates an existing entity in the database and saves changes.

Task<IResult> UpdateAndSaveAsync<TEntity>(TEntity entity, object[] keyValues, CancellationToken cancellationToken = default) where TEntity : class

Parameters

entity TEntity

The entity with updated values.

keyValues object[]

The primary key values of the entity to update.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<IResult>

A task that represents the asynchronous operation, containing the result of the update operation.

Type Parameters

TEntity

The type of the entity.