Azka 10.0.0-alpha.8

Azka Framework Core

A lightweight core package for building data access layers in .NET using Repository, Unit of Work, Specification, metadata mapping, and SQL query helper patterns.

Azka is the core building block. It defines contracts and reusable infrastructure, but it does not ship a concrete database provider or ready-to-use repository implementation.

What This Package Provides

• Repository Contracts - IRepository<T> and IViewRepository<T> abstractions for CRUD and read queries
• Unit of Work Contracts - IUnitOfWork, BaseUnitOfWork, and transaction scope delegation through IDatabaseContext
• Specification Pattern - Composable query descriptions with a fluent API
• Object Mapping - Reflection metadata and DynamicMethod-based mapping from IDataReader or dynamic rows
• Relationship Metadata - One-to-many and many-to-one metadata through attributes
• SQL Query Helpers - Helpers for SELECT, JOIN, WHERE, ordering, paging, and specification-driven query generation
• Dependency Injection Helper - Assembly scanning for application-defined repository implementations

Applications are expected to provide concrete IDatabaseContext and repository implementations, or use a separate package that supplies them.

What This Package Does Not Provide

• A concrete database provider implementation
• A built-in connection string or database configuration model
• A ready-to-use concrete repository class
• Automatic application startup registration beyond repository assembly scanning

Installation

dotnet add package Azka

This installs the core Azka package. You still need to register your concrete database context and repository implementations in your application.

Core Concepts

Entity Mapping

using Azka.Common.Annotations;

[Table("Users")]
public class User
{
    [Key]
    [Column("id")]
    public int Id { get; set; }

    [Column("username")]
    public required string Username { get; set; }

    [Column("email")]
    public required string Email { get; set; }

    // One-to-many relationship
    [WithMany("user_id")]
    public ICollection<Post> Posts { get; set; } = new List<Post>();
}

[Table("Posts")]
public class Post
{
    [Key]
    [Column("id")]
    public int Id { get; set; }

    [Column("title")]
    public required string Title { get; set; }

    [Column("user_id")]
    public int UserId { get; set; }

    // Many-to-one relationship
    [WithOne("user_id")]
    public User? User { get; set; }
}

Specification

using Azka.Common.Abstractions.Specifications;

public class ActiveUserPostsSpecification : Specification<User>
{
    public ActiveUserPostsSpecification(int userId)
    {
        Query.Where(u => u.Id == userId);
        Query.Include(u => u.Posts);
        Query.OrderByDesc(u => u.Id);
    }
}

Application Unit of Work Contract

public interface IAppUnitOfWork : IUnitOfWork
{
    IRepository<User> Users { get; }
    IRepository<Post> Posts { get; }
}

Application Unit of Work Implementation

Your application defines the concrete Unit of Work and exposes the repositories it needs. BaseUnitOfWork resolves those repositories from the application's dependency injection container.

public sealed class AppUnitOfWork : BaseUnitOfWork, IAppUnitOfWork
{
    public AppUnitOfWork(IServiceProvider serviceProvider, IDatabaseContext databaseContext)
        : base(serviceProvider, databaseContext)
    {
    }

    public IRepository<User> Users => GetRepository<IRepository<User>>();
    public IRepository<Post> Posts => GetRepository<IRepository<Post>>();
}

Repository Usage

Services should depend on the application Unit of Work rather than directly constructing repositories.

public class UserService
{
    private readonly IAppUnitOfWork _unitOfWork;

    public UserService(IAppUnitOfWork unitOfWork) => _unitOfWork = unitOfWork;

    public async Task<User?> GetUserWithPostsAsync(int userId)
    {
        var spec = new ActiveUserPostsSpecification(userId);
        return await _unitOfWork.Users.SingleOrDefaultAsync(spec);
    }
}

Repository API

Azka core defines repository contracts only. Concrete packages, such as Azka.PostgreSQL, or your own infrastructure project decide how the operations are executed against a database.

Repository Contract Types

Use IViewRepository<T> when a module should only expose reads. Use IRepository<T> when the module owns writes for the entity.

IViewRepository<T>

IViewRepository<T> uses ISpecification<T> for every read operation, so filtering, includes, ordering, and paging can be described outside the repository implementation.

Example read-only repository contract:

public interface IUserReadRepository : IViewRepository<User>
{
}

IRepository<T>

IRepository<T> extends IViewRepository<T> for write-capable repositories.

Example write-capable repository contract:

public interface IUserRepository : IRepository<User>
{
}

Application-specific repositories can add domain methods, but common queries should usually be represented as specifications so they remain composable and reusable.

Transaction Usage

public class UserService
{
    private readonly IAppUnitOfWork _unitOfWork;

    public UserService(IAppUnitOfWork unitOfWork) => _unitOfWork = unitOfWork;

    public async Task CreateUserWithPostAsync(User user, Post post)
    {
        await using var transaction = await _unitOfWork.BeginTransactionScopeAsync();

        user = await _unitOfWork.Users.AddAsync(user);
        post.UserId = user.Id;
        await _unitOfWork.Posts.AddAsync(post);

        await transaction.CommitAsync();
    }
}

The concrete behavior of BeginTransactionScopeAsync depends on your IDatabaseContext implementation.

Unit of Work API

The Unit of Work pattern coordinates repositories and delegates transaction management to the configured IDatabaseContext.

public interface IUnitOfWork : IDisposable
{
    Task<IDatabaseTransaction> BeginTransactionScopeAsync(CancellationToken cancellationToken = default);
}

BaseUnitOfWork is the reusable base implementation for application Unit of Work classes.

Expose repositories through properties on your application Unit of Work:

public interface IAppUnitOfWork : IUnitOfWork
{
    IUserRepository Users { get; }
    IPostRepository Posts { get; }
}

public sealed class AppUnitOfWork : BaseUnitOfWork, IAppUnitOfWork
{
    public AppUnitOfWork(IServiceProvider serviceProvider, IDatabaseContext databaseContext)
        : base(serviceProvider, databaseContext)
    {
    }

    public IUserRepository Users => GetRepository<IUserRepository>();
    public IPostRepository Posts => GetRepository<IPostRepository>();
}

Because GetRepository<T>() caches resolved repositories, repeated access to _unitOfWork.Users returns the same repository instance for that Unit of Work object.

Transaction Scope Behavior

BeginTransactionScopeAsync(...) returns an IDatabaseTransaction.

public interface IDatabaseTransaction : IAsyncDisposable
{
    TransactionToken Token { get; }
    bool IsCommitted { get; }
    Task CommitAsync(CancellationToken cancellationToken = default);
}

Use await using so the transaction can roll back automatically when the scope exits without a commit.

public async Task SaveChangesAsync(CancellationToken cancellationToken = default)
{
    await using var transaction =
        await _unitOfWork.BeginTransactionScopeAsync(cancellationToken);

    await _unitOfWork.Users.AddAsync(user, cancellationToken);
    await _unitOfWork.Posts.AddAsync(post, cancellationToken);

    await transaction.CommitAsync(cancellationToken);
}

DatabaseTransaction calls the provider's CommitTransactionAsync(...) on CommitAsync(...). If the transaction is disposed before it is committed, it calls RollbackIfNotCommittedAsync(...).

Support for nested transactions, savepoints, shared connections, and rollback depth is provider-specific. Azka core only defines the contract and the transaction wrapper.

Database Context API

IDatabaseContext is the low-level database boundary used by repositories and Unit of Work. Azka core defines the contract; a provider package supplies the implementation.

public interface IDatabaseContext : IDisposable, IAsyncDisposable
{
    Task<T> AddAsync<T>(T entity, CancellationToken cancellationToken = default) where T : class;
    Task<int> UpdateAsync<T>(T entity, CancellationToken cancellationToken = default) where T : class;
    Task<int> DeleteAsync<T>(T entity, CancellationToken cancellationToken = default) where T : class;
    Task<int> DeleteAsync<T>(object id, CancellationToken cancellationToken = default) where T : class;
    Task<T> GetAsync<T>(object id, CancellationToken cancellationToken = default) where T : class;
    Task<IEnumerable<T>> ListAsync<T>(ISpecification<T> specification, CancellationToken cancellationToken = default) where T : class;
    Task<long> CountAsync<T>(ISpecification<T> specification, CancellationToken cancellationToken = default) where T : class;
    Task<IDatabaseTransaction> BeginTransactionScopeAsync(CancellationToken cancellationToken = default);
}

The actual interface also exposes FirstAsync, SingleAsync, raw SQL helpers, and connection helpers.

Entity Operations

Specification Query Operations

Raw SQL Operations

Raw SQL helpers are useful for reports, maintenance commands, or provider-specific queries that do not fit the repository/specification shape.

Prefer the overloads with Dictionary<string, object?> parameters when values come from users or external input.

Connection and Transaction Operations

Repository implementations should generally use the higher-level entity and specification methods. Direct connection access is intended for provider implementations and advanced integration scenarios.

Specification Builder API

The Specification<T> base class provides a fluent API for building queries:

public class ComplexQuerySpecification : Specification<User>
{
    public ComplexQuerySpecification(string email, int page, int pageSize)
    {
        Query.Where(u => u.Email.Contains(email));
        Query.Include(u => u.Posts);
        Query.OrderBy(u => u.Username);
        Query.Skip((page - 1) * pageSize);
        Query.Take(pageSize);
    }
}

Base Filter Include

BaseFilter provides an Include list for request-driven eager loading. Use navigation property paths as strings, including dot notation for nested navigation properties.

using Azka.Common.Abstractions.Specifications;
using Azka.Common.Abstractions.Specifications.Filters;

public sealed class UserFilter : BaseFilter
{
    public StringFilter? Email { get; set; }
}

public sealed class UserSpecification : Specification<User>
{
    public UserSpecification(UserFilter filter)
    {
        BuildBaseFilterSpecification(filter);

        if (filter.Email is not null)
            BuildSpecification(u => u.Email, filter.Email);
    }
}

var filter = new UserFilter
{
    Include = ["Posts", "Posts.Comments"],
    OrderBy = "Username",
    PerPage = 20,
    Page = 1
};

Empty, duplicate, or invalid include paths are ignored. Valid paths are converted into specification include expressions before the query is executed.

Attributes

Note: Properties marked with [Key] must also include [Column("...")] so the primary key column name can be resolved.

If schema is not provided, Azka metadata uses public as the default schema.

Attribute Examples

[Table("dbo", "Users")]          // With custom schema
public class User { }

[Column("first_name")]           // Map to different column name
public string FirstName { get; set; }

[WithOne("department_id")]        // Foreign key column name
public Department? Department { get; set; }

[WithMany("department_id")]       // Foreign key column name
public ICollection<Employee> Employees { get; set; }

Mapping Rules (Entity Mapper)

• Entities must have a public parameterless constructor.
• [Key] must be paired with [Column("...")] to resolve the primary key column.
• Columns are read from SELECT aliases in the format alias_column (case-insensitive); this is handled automatically when using the built-in query helpers.
• If a property has a backing field named _{camelCaseProperty}, the mapper will set the backing field directly.

Backing Field Mapping Example

If a property has a private backing field named _{camelCaseProperty}, the mapper sets the backing field directly.

[Table("users")]
public class User
{
    [Key]
    [Column("id")]
    public int Id { get; set; }

    private string _username = string.Empty;

    [Column("username")]
    public string Username
    {
        get => _username;
        set => _username = value;
    }

    [Column("email")]
    public string Email { get; set; } = string.Empty;
}

Backing Field for One-to-Many (Read-Only List Exposure)

Use a private List<T> backing field for [WithMany], and expose it as a read-only collection to avoid sharing a mutable list reference.

[Table("users")]
public class User
{
    [Key]
    [Column("id")]
    public int Id { get; set; }

    [Column("username")]
    public string Username { get; set; } = string.Empty;

    [Column("email")]
    public string Email { get; set; } = string.Empty;

    private List<Post> _posts = new();

    [WithMany("user_id")]
    public IReadOnlyCollection<Post> Posts => _posts.AsReadOnly();

    public void AddPost(Post post)
    {
        if (post == null) throw new ArgumentNullException(nameof(post));
        if (_posts.Contains(post)) return;
        post.UserId = Id;
        post.User = this;
        _posts.Add(post);
    }

    public void RemovePost(Post post)
    {
        if (post == null) throw new ArgumentNullException(nameof(post));
        if (_posts.Remove(post))
        {
            post.UserId = default;
            post.User = null;
        }
    }
}

[Table("posts")]
public class Post
{
    [Key]
    [Column("id")]
    public int Id { get; set; }

    [Column("title")]
    public string Title { get; set; } = string.Empty;

    [Column("user_id")]
    public int UserId { get; set; }

    [WithOne("user_id")]
    public User? User { get; set; }
}

Dependency Injection

Azka includes an assembly scanning helper for registering application-defined repositories:

services.AddRepositories(typeof(UserRepository).Assembly);

AddRepositories registers concrete, non-abstract classes that implement IRepository<T> or IViewRepository<T> as scoped services. It does not register IDatabaseContext, IUnitOfWork, database connections, or provider-specific services.

Requirements

• .NET 10.0 or higher
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.1 or higher
• Microsoft.Extensions.Logging.Abstractions 10.0.1 or higher

License

See LICENSE.txt for details.

Links

• NuGet Package
• Documentation