Nahmadov.DapperForge.SqlServer 1.0.1

Nahmadov.DapperForge v1

Lightweight Dapper-based data access with an EF-style surface (DapperDbContext + DapperSet<TEntity>) and fluent model building. This doc is for maintainers and consumers of v1.

Highlights

• Immediate execution: no change tracker, no SaveChanges.
• Fluent model builder plus data annotation support.
• SQL generation with pluggable dialects (SqlServer, Oracle).
• Mapping conventions: table name from type or [Table], key from [Key], Id, or {TypeName}Id.
• Auto-generated keys by default; override with Property(x => x.Id).AutoGenerated(false) or provide [DatabaseGenerated].
• Expression-to-SQL translator for WhereAsync/FirstOrDefaultAsync supports comparisons, null checks, booleans, string Contains/StartsWith/EndsWith (with case-insensitive option), and collection Contains → IN.
• Validation via [Required]/[StringLength] on insert/update; read-only entities protected.

Quick Start

// Registration (SqlServer; Oracle also supported)
services.AddDapperDbContext<AppDapperDbContext>(options =>
{
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"));
});

// Use inside a scoped service
var users = await _db.Users.WhereAsync(u => u.IsActive && u.Name.StartsWith("a"), ignoreCase: true);
var id = await _db.Users.InsertAndGetIdAsync(new User { Name = "Alice", IsActive = true });
await _db.Users.DeleteByIdAsync(id);

Mapping with fluent API:

modelBuilder.Entity<User>(b =>
{
    b.ToTable("Users", "dbo");
    b.Property(u => u.Name).HasColumnName("username").HasMaxLength(100).IsRequired();
    b.Property(u => u.Id).AutoGenerated(false); // opt out of default identity
});

Sample App (samples/ConnectionSample)

• Demonstrates registration, seeding, CRUD, validation errors, read-only queries, and all predicate translations including IN.
• Configure user secrets under FullSample:
  • Provider: SqlServer (default) or Oracle
  • SqlServerConnectionString or OracleConnectionString (fallback ConnectionString for SqlServer)
• Tables expected (schemata align with fluent/attribute mappings):
  • Customers: Id (identity), FullName (nvarchar(120) not null), Email (nvarchar(200)), City (nvarchar(100)), IsActive (bit), CreatedAt (datetime), LastLogin (datetime null; read-only in fluent config).
  • SupportTickets: TicketId (identity), CustomerId (int FK), Title (nvarchar(200) not null), Description (nvarchar(500)), Status (nvarchar(50) not null), IsEscalated (bit), OpenedOn (datetime), ClosedOn (datetime null).
  • AuditLogs: Id (identity), Entity (nvarchar(100)), Action (nvarchar(50)), Details (nvarchar(200)), CreatedAt (datetime). Run the sample:

cd samples/ConnectionSample
dotnet run

Core Concepts

• DapperDbContext wraps a connection factory and dialect, exposes low-level Dapper wrappers plus Set<TEntity>().
• DapperSet<TEntity> provides GetAllAsync, FindAsync, WhereAsync(Expression), FirstOrDefaultAsync, InsertAsync, InsertAndGetIdAsync, UpdateAsync, DeleteAsync, DeleteByIdAsync.
• SqlGenerator<TEntity> builds SELECT/INSERT/UPDATE/DELETE; skips generated/read-only columns.
• EntityValidator<TEntity> enforces required/length rules and read-only restrictions before SQL.
• Dialects (ISqlDialect): identifier quoting, parameter formatting, boolean literals, insert-returning-key SQL.

Expression Translation (supported patterns)

• Comparisons: ==, !=, >, >=, <, <=
• Null checks: x.Prop == null, x.Prop != null
• Booleans: x.IsActive, !x.IsActive, x.IsActive == true/false
• Strings: Contains, StartsWith, EndsWith (optional case-insensitive lowering)
• Collections: list.Contains(x.Prop) → Prop IN (...) (empty list ⇒ 1=0)
• Logical: &&, ||, !

Limitations (v1)

1. No change tracker or SaveChanges; operations execute immediately.
2. Keys assumed single-column.
3. No paging helpers/soft-delete conventions.
4. Expression translator intentionally limited to common filters.
5. Oracle dialect returns null for InsertReturningId unless extended.
6. No logging hooks beyond console SQL echo in DapperDbContext.LogSql.

Testing

Run all tests:

dotnet test

Key coverage:

• SQL generation (identity handling, quoting)
• Predicate translation (booleans, nulls, LIKE, case-insensitive, IN)
• Context connection/transaction behavior with fakes

Versioning

This document and code reflect Version 1 of Nahmadov.DapperForge.