NPv.DataAccess.Abstractions 2.5.0

NPv.DataAccess.Abstractions

Minimal interface contract for generic repository access in .NET applications.

📢 Version status

• v2.5 is the new stable version of NPv.DataAccess.Abstractions and is recommended for all new and existing integrations.
• Previous versions are now considered out of service and are no longer maintained.

✨ Overview

This library defines core abstractions for working with persistent data in a clean, provider-agnostic way. It includes:

• IGenericRepository — for standard CRUD operations on aggregate roots or entities
• ISqlExecutor — for executing raw SQL queries and commands asynchronously

These abstractions are designed to support layered architectures, promote separation of concerns, and enable swapping implementations (e.g., EF Core, Dapper) with minimal friction.

🧱 Interfaces

IGenericRepository

Standard CRUD contract for entity-oriented persistence:

Task<TEntity?> GetAsync<TEntity>(Guid id, CancellationToken ct, IReadOnlyCollection<string>? includes = null);
Task<TEntity?> GetAsync<TEntity>(Expression<Func<TEntity, bool>>? filter, CancellationToken ct, IReadOnlyCollection<string>? includes = null);
Task<IReadOnlyList<TEntity>> ListAsync<TEntity>(
    CancellationToken ct,
    Expression<Func<TEntity, bool>>? filter = null,
    Func<IQueryable<TEntity>, IOrderedQueryable<TEntity>>? orderBy = null,
    IReadOnlyCollection<string>? includes = null);
Task<IReadOnlyList<TEntity>> PageAsync<TEntity>(
    int page,
    int pageSize,
    CancellationToken ct,
    Expression<Func<TEntity, bool>>? filter = null,
    Func<IQueryable<TEntity>, IOrderedQueryable<TEntity>>? orderBy = null,
    IReadOnlyCollection<string>? includes = null);
Task<int> CountAsync<TEntity>(CancellationToken ct, Expression<Func<TEntity, bool>>? filter = null);
Task AddAsync<TEntity>(TEntity entity, CancellationToken ct);
Task DeleteAsync<TEntity>(Guid id, CancellationToken ct);

Include examples (current behavior)

includes uses string-based navigation paths:

var order = await repo.GetAsync<Order>(
    id,
    ct,
    new[] { "Items", "Customer", "Customer.Address" });

var orders = await repo.ListAsync<Order>(
    ct,
    filter: x => x.Status == OrderStatus.Created,
    includes: new[] { "Items.Product" });

ISqlExecutor

Lightweight abstraction over raw SQL execution, ideal for high-performance scenarios using Dapper or similar tools:

Task<T> QueryFirstAsync<T>(string sql, CancellationToken ct, object? parameters = null);
Task<T?> QueryFirstOrDefaultAsync<T>(string sql, CancellationToken ct, object? parameters = null);
Task<T> QuerySingleAsync<T>(string sql, CancellationToken ct, object? parameters = null);
Task<T?> QuerySingleOrDefaultAsync<T>(string sql, CancellationToken ct, object? parameters = null);
Task<IEnumerable<T>> QueryAsync<T>(string sql, CancellationToken ct, object? parameters = null);
Task<int> ExecuteAsync(string sql, CancellationToken ct, object? parameters = null);

⏹️ CancellationToken

All async methods require a CancellationToken ct. Pass the application/request token from top-level boundaries so cancellation flows into repository/SQL layers. If no token is available, pass CancellationToken.None explicitly at the call site. Cancellation is propagated into EF Core/Dapper operations; OperationCanceledException is allowed to bubble.

public sealed class OrdersController(IGenericRepository repo)
{
    [HttpPost]
    public async Task<IActionResult> Create(CreateOrderRequest request, CancellationToken ct)
    {
        await repo.AddAsync(new Order { /* ... */ }, ct);
        return Ok();
    }
}

🔧 Usage

Implement the interface in your data layer (e.g., using EF Core):

For IGenericRepository

public class EfGenericRepository : IGenericRepository { ... }

For ISqlExecutor

Implement using your SQL technology of choice, e.g. via Dapper:

public class DapperSqlExecutor : ISqlExecutor { ... }

Inject ISqlExecutor where you need to run raw SQL without managing connections or boilerplate manually.

📦 Installation

This package is published as part of the NPv.Foundation.Net architecture.

To install via NuGet:

dotnet add package NPv.DataAccess.Abstractions

🧩 Related packages

• NPv.DataAccess.Ef – EF Core implementation of IGenericRepository
• NPv.DataAccess.Dapper.Executor – Dapper-based implementation of ISqlExecutor