mersolutionCore

mersolutionCore is a lightweight, cross-platform ORM and fluent query builder built specifically for .NET Standard — works seamlessly on both .NET Framework and modern .NET.

Explore the full documentation at mersocore.com.

---

🚀 Why mersolutionCore?

Modern .NET applications need a reliable, fast, and easy-to-use database layer. mersolutionCore gives you the perfect balance between productivity and control:

• Lightweight Architecture: No heavy dependencies — built directly on ADO.NET for maximum speed.
• Fluent Query Builder: Chainable methods for clean, readable queries without raw SQL.
• Model-Based ORM: Object-oriented database management with full CRUD, relationships, and lifecycle hooks.
• Cross-Platform: A single .NET Standard 2.0 library that runs everywhere .NET runs.
• Zero Config: Just set your connection string and call EnsureCreated() — tables are created automatically.

---

✨ Core Features

• ORM — Model<T> with CRUD, relationships, soft deletes, timestamps and lifecycle events
• Fluent Query Builder — chainable WHERE, JOIN, ORDER, GROUP, LIMIT, aggregate and pagination
• Multi-Database — SQL Server, MySQL, MariaDB, PostgreSQL, SQLite via a unified IDbCommand interface
• DbContext & MerSet<T> — typed entity sets, EnsureCreated, EnsureDeleted, EnsureFresh
• Migrations — code-first schema management with Schema, Migrator, MigrationRunner
• Caching — in-memory key/value (MersoCache) and query-level cache (QueryCache)
• Validation — fluent and attribute-based validation (MersoValidator, [Required], [Email], …)
• Transactions — MersoTransaction.Run() / TryRun() with automatic rollback on failure
• Bulk Operations — high-performance BulkInsert, BulkUpdate, BulkDelete, BulkUpsert
• Raw Queries — RawQuery.Query<T>(), Scalar<T>(), Execute(), QueryTable()
• JSON Columns — JsonValue<T>, JsonDictionary, JsonList<T> column wrappers
• Observers & Events — MersoObserver<T> and IMersoEvents model lifecycle hooks
• Global Scopes — automatic query filters via [GlobalScope] attribute
• Connection Pool — built-in ADO.NET connection pooling
• Cryptography — AES/TripleDES encryption, SHA/MD5/HMAC hashing (Crypto, Security)
• Utilities — TextHelper, StringExtensions, HttpClientHelper, JwtHelper

---

📖 Quick Links

Resource	Link
Official Website	mersocore.com
Full Documentation	mersocore.com/docs
Getting Started	Installation Guide
GitHub	mersolution/mersocore

---

🏁 Getting Started

Installation

dotnet add package mersolutionCore

Or add a project reference:

<ProjectReference Include="..\mersolutionCore\mersolutionCore.csproj" />

---

Quick Start

1. Configure the Database

using mersolutionCore.Config;

// SQL Server
DbConfig.ConfigureSqlServer(@".\SQLEXPRESS", "MyDatabase");

// MySQL / MariaDB
DbConfig.ConfigureMySQL("localhost", "mydb", "root", "password");

// PostgreSQL
DbConfig.ConfigurePostgreSQL("localhost", "mydb", "postgres", "secret");

// SQLite
DbConfig.ConfigureSQLite("./app.db");

2. Define a Model

using mersolutionCore.ORM;
using mersolutionCore.ORM.Entity;

[Table("Users")]
public class User : Model<User>
{
    [PrimaryKey(AutoIncrement = true)]
    public int Id { get; set; }

    [Column("Name", Length = 100)]
    public string Name { get; set; } = "";

    [Column("Email", Length = 255)]
    public string Email { get; set; } = "";

    [Column("IsActive")]
    public bool IsActive { get; set; } = true;

    [CreatedAt]  public DateTime? CreatedAt { get; set; }
    [UpdatedAt]  public DateTime? UpdatedAt { get; set; }
    [SoftDelete] public DateTime? DeletedAt { get; set; }
}

3. Create a DbContext

using mersolutionCore.ORM;

public class AppDbContext : DbContext
{
    static AppDbContext() => DbConfig.ConfigureSqlServer(@".\SQLEXPRESS", "MyDatabase");

    public MerSet<User>    Users    { get; set; } = null!;
    public MerSet<Product> Products { get; set; } = null!;

    public AppDbContext() : base(DbConfig.CreateConnection) { }
}

// On startup — creates all tables (idempotent)
var db = new AppDbContext();
db.EnsureCreated();

4. CRUD Operations

// Create
var user = new User { Name = "Alice", Email = "alice@example.com" };
user.Save();

// Read
var found  = User.Find(user.Id);
var orFail = User.FindOrFail(99);   // throws ModelNotFoundException

// Update
found.Name = "Bob";
found.Save();

// Soft delete / restore
found.Delete();
found.Restore();

// Hard delete
found.ForceDelete();

5. Fluent Query Builder

var results = User
    .Where("IsActive", true)
    .Where("CreatedAt", ">", DateTime.Today.AddDays(-30))
    .OrderByDesc("CreatedAt")
    .Take(20)
    .Select("Id", "Name", "Email")
    .Get();

// Pagination
var page = User.Query().Where("IsActive", true).Paginate(pageNumber: 1, pageSize: 10);
// page.Items  |  page.TotalCount  |  page.TotalPages  |  page.HasNextPage

// Aggregates
int  count = User.Count();
bool any   = User.Exists();
var  names = User.Pluck("Name");   // List<object>

// Debug — inspect generated SQL
string sql = User.Query().Where("IsActive", true).Take(5).ToSql();

---

Supported Databases

Database	NuGet Package	Default Port	Cross-Platform
SQL Server	Microsoft.Data.SqlClient	1433	✅
MySQL	MySqlConnector	3306	✅
MariaDB	MySqlConnector	3306	✅
PostgreSQL	Npgsql	5432	✅
SQLite	Microsoft.Data.Sqlite	—	✅

---

Project Structure

mersolutionCore/
├── Command/        # IDbCommand, DbFactory — SQL Server / MySQL / MariaDB / PostgreSQL / SQLite drivers
├── Config/         # DbConfig — connection factory and provider configuration
├── ORM/            # ModelBase, QueryBuilder, DbContext, MerSet<T>
│                   #   Migrations, Relations, BulkOperations, Transactions
│                   #   RawQuery, Observers, Events, GlobalScope, JsonColumns
│                   #   ConnectionPool, SoftDeletes
├── Cache/          # MemoryCache, QueryCache
├── Http/           # HttpClientHelper, JwtHelper
├── Library/        # Crypto, Security, TextHelper, StringExtensions
└── Validation/     # MersoValidator, ValidationResult, ValidationAttributes

---

Key Features

Feature	Description
Model-First Migrations	Auto-create tables from model attribute definitions
Fluent Query Builder	Clean chainable query API — no raw SQL needed
Relations	HasOne, HasMany, BelongsTo, BelongsToMany with eager loading
Observers & Events	Model lifecycle hooks — Creating, Created, Updating, Deleting, …
Bulk Operations	Efficient BulkInsert, BulkUpdate, BulkDelete, BulkUpsert
JSON Columns	Map JSON/text columns to C# objects with JsonValue<T>
Validation Attributes	[Required], [Email], [Range], [MinLength], [Url], [Phone], …
Connection Pool	Built-in ADO.NET connection pooling for high-throughput apps
Query Cache	Cache results with MersoCache.Remember() or .Remember() extension
Soft Deletes	[SoftDelete] attribute — Delete(), Restore(), WithTrashed(), OnlyTrashed()
Transactions	MersoTransaction.Run() / TryRun() with automatic rollback
Global Scopes	Automatic WHERE filters applied to every query via [GlobalScope]
Cryptography	AES/TripleDES encryption, SHA-256/MD5/HMAC hashing

---

Compatibility

Platform	Minimum Version
.NET Standard	2.0
.NET Framework	4.6.1+
.NET Core	2.0+
.NET	5, 6, 7, 8, 9+

---

Next Steps

Documentation	Description
Database Config	Configure your connection string and provider
ORM Model	Define models with attributes and relationships
Query Builder	Build complex, chainable queries
Relations	Define and query model relationships
Migrations	Manage database schema with code-first migrations
Caching	Cache queries and results for better performance
Validation	Validate models with attributes or fluent rules
CRUD Examples	Complete working CRUD examples

---

mersolutionCore — a lightweight and fast .NET ORM and query builder by Mersolution Technology