LiteOrm.Common 8.0.16

LiteOrm

📖 English Version

A lightweight, high-performance .NET ORM framework that combines micro-ORM speed with full-ORM ergonomics. It is a strong fit for projects that need predictable performance and flexible SQL composition.

Table of Contents

• Core Features

• Requirements

• Installation

• Quick Start

• Key Features

• Documentation & Resources

• Contributing

• License

🎯 Core Features

• Ultra-Fast Performance: Performance close to native Dapper, far exceeding EF Core

• Multi-Database Support: Native support for SQL Server, MySQL, Oracle, PostgreSQL, SQLite

• Flexible Querying: Multiple query methods via Lambda, Expr, or ExprString

• Automatic Associations: Implement JOIN queries via attributes without manual SQL writing

• Declarative Transactions: AOP transaction management via [Transaction] attribute

• Dynamic Sharding: Table routing via IArged interface

• Async Support: Complete async/await support

• Type Safety: Strong-typed generic interfaces with compile-time type checking

📋 Requirements

• .NET 8.0+ or .NET Standard 2.0 (.NET Framework 4.6.1+)

• Dependencies: Autofac, Castle.Core

📦 Installation

dotnet add package LiteOrm

🚀 Quick Start

1. Configure Connection

In appsettings.json:

{

    "LiteOrm": {

        "Default": "DefaultConnection",

        "DataSources": [

            {

                "Name": "DefaultConnection",

                "ConnectionString": "Server=localhost;Database=TestDb;...",

                "Provider": "MySqlConnector.MySqlConnection, MySqlConnector"

            }

        ]

    }

}

In Program.cs:

Console:

var host = Host.CreateDefaultBuilder(args)

    .RegisterLiteOrm()

    .Build();

ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);

builder.Host.RegisterLiteOrm();

2. Define Entity

using LiteOrm.Common;



[Table("Users")]

public class User

{

    [Column("Id", IsPrimaryKey = true, IsIdentity = true)]

    public int Id { get; set; }



    [Column("UserName")]

    public string UserName { get; set; }



    [Column("Email")]

    public string Email { get; set; }



    [Column("CreateTime")]

    public DateTime? CreateTime { get; set; }

}

3. Define a service (optional)

public interface IUserService :

    IEntityService<User>, IEntityServiceAsync<User>

{

}



public class UserService : EntityService<User>, IUserService

{

}

4. Use the service

// Insert

var user = new User { UserName = "admin", Email = "admin@test.com" };

await userService.InsertAsync(user);



// Query

var users = await userService.SearchAsync(u => u.Email.Contains("test"));



// Update

user.Email = "newemail@test.com";

await userService.UpdateAsync(user);



// Delete

await userService.DeleteAsync(user);



// Pagination

var page = await userService.SearchAsync(

    q => q.Where(u => u.CreateTime > DateTime.Today)

          .OrderByDescending(u => u.CreateTime)

          .Skip(0).Take(10)

);

💡 Key Features

Lambda Queries

var users = await userService.SearchAsync(u => u.Age > 18);

Best for most day-to-day queries where readability and compile-time checking matter most.

Expr queries

using static LiteOrm.Common.Expr;

var expr = Prop("Age") > 18 & Prop("Status") == 1;

var users = await userService.SearchAsync(expr);

Best for dynamically assembled filters, admin search screens, and query-builder style scenarios.

ExprString queries (.NET 8.0+)

using static LiteOrm.Common.Expr;

int minAge = 18;

var expr = Prop("Age") > 25;

var users = await objectViewDAO.Search(

    $"WHERE {expr} AND Age > {minAge}"

).ToListAsync();

var dataTable = await dataViewDAO.Search(

    $"SELECT Id, UserName FROM Users WHERE {Prop("Age")} > {minAge}",

    isFull: true

).GetResultAsync();

Use this as the DAO-side SQL entry when Lambda or pure Expr is not enough. It can represent either a Search condition fragment or a full SQL statement. Service query APIs do not expose ExprString.

Automatic associations

[Table("Orders")]

public class Order

{

    [Column("Id", IsPrimaryKey = true)]

    public int Id { get; set; }



    [Column("UserId")]

    [ForeignType(typeof(User))]

    public int UserId { get; set; }

}



public class OrderView : Order

{

    [ForeignColumn(typeof(User), Property = "UserName")]

    public string UserName { get; set; }

}



var orders = await orderService.SearchAsync<OrderView>();

Declarative transactions

[Transaction]

public async Task CreateUserWithOrder(User user, Order order)

{

    await userService.InsertAsync(user);

    order.UserId = user.Id;

    await orderService.InsertAsync(order);

}

Dynamic sharding

public class Log : IArged

{

    [Column("Id", IsPrimaryKey = true)]

    public int Id { get; set; }



    [Column("CreateTime")]

    public DateTime CreateTime { get; set; }



    string[] IArged.TableArgs => [CreateTime.ToString("yyyyMM")];

}

查询时可通过 tableArgs、WithArgs(...) 或 Expr.From<T>(...) 显式指定分表参数；主表指定的 TableArgs 会传递给同作用域或下级作用域中的后续表，未显式指定时会继续沿用这组参数。若表名包含多个占位符（如 Sales_{0}_{1}），也可以分别传入 ["US", "2025"] 这样的多维参数，避免手工拼接分表名。不同表还可以错开使用不同占位符位置，例如 Table1_{0} 与 Table2_{1} 可共享同一个参数数组，让一组 TableArgs 同时驱动多张表。

📚 Documentation & Resources

Start with the docs hub, then follow the section that matches your scenario.

• Documentation Hub - Bilingual docs hub organized into Getting Started, Core Usage, Advanced Topics, and Extensibility

• Docs Hub (中文) - Chinese and English docs hub with the same learning-path structure

• API Index - Scenario-based API and capability entry points

• Example Index - Example entry points grouped by scenario

• Database Compatibility Notes - Common cross-database differences and validation tips

• AI Guide - Compact appendix for assistants and quick orientation

• GitHub Repository - Source code and issue tracking

• Demo Project - Feature demonstrations

• Performance Report - Detailed benchmark reports

🤝 Contributing

Found a bug? Have a suggestion? Please open an Issue or Pull Request.

📄 License

MIT License

Back to top

📖 中文版本

LiteOrm 是一个轻量级、高性能的 .NET ORM 框架，兼顾微型 ORM 的执行效率和完整 ORM 的易用性，适合对性能敏感且需要灵活处理复杂 SQL 的场景。

目录

• 核心特性

• 环境要求

• 安装

• 快速入门

• 常见特性

• 相关资源

• 贡献与反馈

• 开源协议

🎯 核心特性

• 极速性能：性能接近原生 Dapper，远超 EF Core

• 多数据库支持：原生支持 SQL Server、MySQL、Oracle、PostgreSQL、SQLite

• 灵活查询：支持基于 Lambda、Expr 或 ExprString 的多种查询方式

• 自动关联：通过特性实现无损的 JOIN 查询，无需手写 SQL

• 声明式事务：[Transaction] 特性实现 AOP 事务管理

• 动态分表：IArged 接口支持分表路由

• 异步支持：完整的 async/await 支持

• 类型安全：强类型泛型接口，编译时类型检查

📋 环境要求

• .NET 8.0+ 或 .NET Standard 2.0（兼容 .NET Framework 4.6.1+）

• 依赖库：Autofac、Castle.Core

📦 安装

dotnet add package LiteOrm

🚀 快速入门

1. 配置连接

appsettings.json:

{

    "LiteOrm": {

        "Default": "DefaultConnection",

        "DataSources": [

            {

                "Name": "DefaultConnection",

                "ConnectionString": "Server=localhost;Database=TestDb;...",

                "Provider": "MySqlConnector.MySqlConnection, MySqlConnector"

            }

        ]

    }

}

Program.cs:

控制台应用：

var host = Host.CreateDefaultBuilder(args)

    .RegisterLiteOrm()

    .Build();

ASP.NET Core 应用：

var builder = WebApplication.CreateBuilder(args);

builder.Host.RegisterLiteOrm();

2. 定义实体

using LiteOrm.Common;



[Table("Users")]

public class User

{

    [Column("Id", IsPrimaryKey = true, IsIdentity = true)]

    public int Id { get; set; }



    [Column("UserName")]

    public string UserName { get; set; }



    [Column("Email")]

    public string Email { get; set; }



    [Column("CreateTime")]

    public DateTime? CreateTime { get; set; }

}

3. 定义服务（可选）

public interface IUserService :

    IEntityService<User>, IEntityServiceAsync<User>

{

}



public class UserService : EntityService<User>, IUserService

{

}

4. 使用服务

// 插入

var user = new User { UserName = "admin", Email = "admin@test.com" };

await userService.InsertAsync(user);



// 查询

var users = await userService.SearchAsync(u => u.Email.Contains("test"));



// 更新

user.Email = "newemail@test.com";

await userService.UpdateAsync(user);



// 删除

await userService.DeleteAsync(user);



// 分页

var page = await userService.SearchAsync(

    q => q.Where(u => u.CreateTime > DateTime.Today)

          .OrderByDescending(u => u.CreateTime)

          .Skip(0).Take(10)

);

💡 常见特性

• Lambda 查询：默认优先的查询方式，适合大多数日常业务筛选

• Expr 表达式：适合后台筛选、查询构造器等动态条件拼装场景

• ExprString 查询：仅在 DAO 层使用，可传 Search 条件片段或完整 SQL

• Lambda 与 Expr 组合：在保留强类型可读性的同时复用动态条件

• 自动关联：无损的 JOIN 查询

• 声明式事务：基于特性的 AOP 事务

• 动态分表：自动分表路由

📚 文档与资源

建议先从文档中心进入，再按“入门篇 / 核心使用篇 / 高级特性篇 / 扩展开发篇”的路径继续阅读。

• 中文文档中心 - 按入门、核心使用、高级特性、扩展开发组织的文档入口

• English Docs Hub - Same bilingual docs hub with aligned learning-path sections

• API 索引 - 按使用场景整理的接口与能力入口

• 示例索引 - 按场景整理的示例入口

• 数据库差异与兼容性说明 - 常见跨数据库差异与排查建议

• AI 使用指南 - 面向 AI 和快速查阅场景的附录

• GitHub 仓库 - 源代码与问题跟踪

• Demo 项目 - 功能演示

• 性能报告 - 详细的性能基准

🤝 贡献与反馈

欢迎提交 Issue 或 Pull Request。

📄 开源协议

MIT 协议

回到顶部