Data Contracts

Overview

VersaTul.Data.Contracts provides shared abstractions for repository-style data access, connection metadata, pagination, and unit-of-work patterns.

It is the base contract layer for data-oriented VersaTul packages such as EF Core and provider-specific access libraries.

When To Use This Package

Use this package when you want to:

  1. Define repository interfaces that stay independent of a concrete data technology.

  2. Standardize unit-of-work behavior across projects.

  3. Pass connection metadata through a common contract.

  4. Represent paged requests and paged results consistently.

  5. Add async stream support to repository abstractions.

Installation

Install the package with the .NET CLI:

dotnet add package VersaTul.Data.Contracts

Or with the Package Manager Console:

PM> NuGet\Install-Package VersaTul.Data.Contracts -Version latest

Core Types And Concepts

IDataConnection

Standardizes how connection strings and provider names are retrieved.

IRepository<TEntity, TKey>

Defines CRUD-style operations, queryable access, async reads, and range operations for a repository.

IAsyncStreamRepository<TEntity, TKey>

Extends the repository model with cancellation-aware async streaming.

IUnitOfWork

Defines transactional save and rollback behavior plus disposal semantics.

IPagedRequest and PagedRequest

Represent page number, page size, and derived skip value.

IPagedResult<T> and PagedResult<T>

Represent paged items, total count, current page, page size, and total page count.

Key Capabilities

  1. Repositories support synchronous and asynchronous Add, Find, Get, and range operations.

  2. Repositories expose both IQueryable and async enumerable access patterns.

  3. Paged request and result models can be reused across APIs and repository layers.

  4. The contracts are flexible enough for EF Core, document databases, and custom persistence layers.

Repository Example

using VersaTul.Data.Contracts;

public interface ICustomerRepository : IRepository<Customer, int>
{
}

public class CustomerService
{
    private readonly ICustomerRepository repository;

    public CustomerService(ICustomerRepository repository)
    {
        this.repository = repository;
    }

    public async Task<Customer> GetAsync(int id)
    {
        return await repository.GetAsync(id);
    }
}

Paging Example

using VersaTul.Data.Contracts;

var request = new PagedRequest
{
    PageNumber = 2,
    PageSize = 25
};

var result = new PagedResult<Customer>
{
    Items = customers,
    TotalCount = 240,
    PageNumber = request.PageNumber,
    PageSize = request.PageSize
};

Notes

  1. IRepository<TEntity, TKey> is intentionally broad enough for multiple backing stores.

  2. IAsyncStreamRepository<TEntity, TKey> is useful when the consumer prefers stream-first enumeration.

  3. IUnitOfWork is most relevant in packages such as EFCore where change tracking and commit behavior are explicit.