WingWell.Util.Database

轻量级 ORM 框架，基于 XML 映射，提供实体 CRUD、条件查询、批量操作、事务、原生 SQL 等数据库访问能力。仅支持 SQL Server。

功能一览

快速开始

dotnet add package WingWell.Util.Database -s https://nuget.wingwell.cloud/v3/index.json

定义实体

继承 PersistentObject，属性名须与 XML ORMapping 配置中的 attribute name 一致：

using WingWell.Util.Database;

public class User : PersistentObject
{
    public int UserId { get; set; }
    public string UserName { get; set; }
    public string Email { get; set; }
    public bool IsActive { get; set; }
    public DateTime CreateTime { get; set; }
}

单对象 CRUD

// 新增（自增主键自动回填）
var user = new User { UserName = "Tom", Email = "tom.liu@wingwell.cn" };
user.Insert();

// 按主键查询
var user = new User { UserId = 1 };
bool found = user.Retrieve();  // true = 查到，false = 不存在

// 更新（对象须已 Retrieve 或 Insert 过）
user.UserName = "NewName";
user.Update();

// 删除
user.Delete();

条件查询 — RetrieveCriteria<T>

var criteria = new RetrieveCriteria<User>();
criteria.AddEqualTo("IsActive", true);
criteria.AddMatch("UserName", "Tom");             // LIKE '%Tom%'
criteria.AddMatchPrefix("Email", "tom");          // LIKE 'tom%'
criteria.AddGreaterThan("CreateTime", "2024-01-01");
criteria.OrderBy("CreateTime", FieldOrderBy.Descending);

List<User> users = criteria.GetCollection();      // 实体列表
DataTable dt = criteria.GetDataTable();           // DataTable
User first = criteria.GetFirstObject();           // 第一条
PersistenceCursor<User> cursor = criteria.GetCursor(); // 游标遍历

过滤方法一览

attributeName 是实体属性名（如 UserName），不是数据库列名（如 user_name），框架通过 XML 自动映射。

value 支持类型：string bool short int long double decimal float

批量更新 — UpdateCriteria<T>

var criteria = new UpdateCriteria<User>();
criteria.AddEqualTo("IsActive", true);                 // WHERE
criteria.AddAttributeForUpdate("UserName", "NewName");  // SET
int affected = criteria.Execute();

批量删除 — DeleteCriteria<T>

var criteria = new DeleteCriteria<User>();
criteria.AddEqualTo("IsActive", false);
int affected = criteria.Execute();

事务

所有 CRUD 和 Criteria 方法都支持 Transaction 重载：

var ts = new Transaction();
try
{
    ts.BeginTransaction();

    var user = new User { UserName = "Tom" };
    user.Insert(ts);

    var criteria = new UpdateCriteria<User>();
    criteria.AddEqualTo("UserId", user.UserId);
    criteria.AddAttributeForUpdate("IsActive", true);
    criteria.Execute(ts);

    ts.CommitTransaction();
}
catch
{
    ts.RollbackTransaction();
    throw;
}

跨数据源事务：

ts.BeginTransaction(new List<string> { "db1", "db2" });

原生 SQL — DataAccess

复杂 JOIN / 聚合等 Criteria 无法满足时使用：

// 查询 → DataTable
DataTable dt = DataAccess.ExecuteQuery("dbName",
    "SELECT * FROM Users WHERE Age > @Age",
    new Parameter("Age", 18));

// 执行 → 受影响行数
int rows = DataAccess.Execute("dbName",
    "UPDATE Users SET IsActive = 0 WHERE LastLogin < @Date",
    new Parameter("Date", "2023-01-01"));

// 行数统计
int count = DataAccess.RowCount("dbName",
    "SELECT * FROM Users WHERE IsActive = 1");

// 分页（pageIndex 从 0 开始）
DataTable page = DataAccess.ExecutePageQuery("dbName",
    "SELECT * FROM Users WHERE IsActive = 1",
    pageIndex: 0, pageSize: 20,
    new KeySorterValue("CreateTime", Sorter.DESC));

所有方法均支持 Transaction 重载：

DataTable dt = DataAccess.ExecuteQuery("dbName", sql, parameters, transaction, timeout);

参数化查询

使用 Parameter 类传参，框架自动加 @ 前缀，防止 SQL 注入：

new Parameter("ParamName", value)
new List<Parameter> { new("Name", "Tom"), new("Age", 18) }

注意事项