Azka 10.0.0-alpha3

Azka Framework

A lightweight, high-performance data access framework for .NET that provides Repository, Unit of Work, and Specification patterns with fluent query building capabilities.

Features

• Repository Pattern - Clean abstraction for CRUD operations
• Unit of Work Pattern - Transaction management with nested transaction support
• Specification Pattern - Composable queries with fluent API
• High-Performance Mapping - Fast object mapper using DynamicMethod compilation
• Relationship Support - One-to-many and many-to-one relationships with automatic JOIN handling
• Metadata-Driven - Automatic metadata generation through reflection
• Attribute-Based Configuration - Simple attributes for entity-to-table mapping

Installation

dotnet add package Azka

Quick Start

1. Define Your Entity

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; }
}

2. Create a 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);
    }
}

3. Use Repository via Unit of Work

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

// Inject only Unit of Work
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);
    }

    public async Task AddUserAsync(User user)
    {
        await _unitOfWork.Users.AddAsync(user);
    }
}

4. Use Unit of Work

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

public class UserService
{
    private readonly IAppUnitOfWork _unitOfWork;

    public UserService(IAppUnitOfWork unitOfWork)
    {
        _unitOfWork = unitOfWork;
    }

    public async Task CreateUserWithPostAsync(User user, Post post)
    {
        var token = _unitOfWork.Begin();
        try
        {
            user = await _unitOfWork.Users.AddAsync(user);
            post.UserId = user.Id;
            await _unitOfWork.Posts.AddAsync(post);

            _unitOfWork.Commit(token);
        }
        catch
        {
            _unitOfWork.Rollback();
            throw;
        }
    }
}

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);
    }
}

Attributes

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

Attribute Examples

[Table("Users", "dbo")]          // 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; }
}

Unit of Work API

The Unit of Work pattern manages transactions with support for nested transactions:

public interface IUnitOfWork : IDisposable
{
    TransactionToken Begin();              // Returns a token for tracking
    void Commit(TransactionToken token);    // Commit with token
    void Rollback();                       // Rollback all
}

Note: Create a custom UnitOfWork implementation (e.g., IAppUnitOfWork) that inherits from BaseUnitOfWork to expose repositories, so services only inject the Unit of Work:

public sealed class AppUnitOfWork : BaseUnitOfWork, IAppUnitOfWork
{
    public AppUnitOfWork(IServiceProvider serviceProvider, IDbConnection connection)
        : base(serviceProvider, connection)
    {
    }

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

Nested Transaction Support

public async Task ComplexOperationAsync()
{
    var token = _unitOfWork.Begin();
    try
    {
        // This can call other methods that also call Begin()
        await NestedOperationAsync();

        _unitOfWork.Commit(token);
    }
    catch
    {
        _unitOfWork.Rollback();
        throw;
    }
}

private async Task NestedOperationAsync()
{
    var nestedToken = _unitOfWork.Begin();
    try
    {
        // Do work here
        _unitOfWork.Commit(nestedToken);  // Only commits if parent commits
    }
    catch
    {
        _unitOfWork.Rollback();
        throw;
    }
}

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