Aore.SqlBuilder.Extensions 1.2.3

Aore.SqlBuilder.Extensions

Aore.SqlBuilder 的 Dapper 执行层扩展：把核心库构建出的 SqlResult 直接跑起来——参数自动转换为 DynamicParameters（含 Oracle 输出参数）、同步/异步执行、分页查询（自动 Count）、自增主键回读、事务与批量操作。

using Aore.SqlBuilder;
using Aore.SqlBuilder.Extensions;

var db = new SqlExecutor(connection, SqlDialect.MySql);

// 查询：构建器 → SQL → Dapper 执行，一步到位
var page = await db.QueryPageAsync(Sql.Select<User>()
    .Where(u => u.Age >= 18)
    .OrderByDescending(u => u.CreateTime), pageNumber: 1, pageSize: 20);

// 插入并回读自增主键
long id = await db.InsertAsync(newUser, returnId: true);

安装

dotnet add package Aore.SqlBuilder.Extensions

依赖：Aore.SqlBuilder（核心库）+ Dapper。目标框架与核心库一致：netstandard2.0 / net462 / net472 / net48 / net8.0 / net9.0 / net10.0（旧框架自动附带 Microsoft.Bcl.AsyncInterfaces）。

两种使用方式

两者执行链路与安全约定完全一致（参数化命令 + 语句校验），门面内部即委托扩展方法。

方式一 · 扩展方法

查询映射（DapperSqlResultExtensions，作用于 IDbConnection + SqlResult）

var sql = Sql.Select<User>().Where(u => u.Age > 18).ToSql(SqlDialect.MySql);

var users  = connection.Query<User>(sql);                        // 实体列表（可 buffered: false）
var users2 = await connection.QueryAsync<User>(sql);             // 异步列表
var first  = connection.QueryFirstOrDefault<User>(sql);          // 首行，无结果返回 null
var one    = connection.QuerySingle<User>(sql);                  // 单行（0 行或多行抛异常）

// 流式查询：不缓冲结果逐行消费，适合大结果集
// 注意：流式期间连接被占用，消费完成前不可复用该连接执行其他命令
await foreach (var u in connection.QueryUnbufferedAsync<User>(sql, cancellationToken))
{
    Process(u);
}

// 参数对象：一般无需手动转换；需要时可显式取出（输出参数以 DbType.Int64 输出方向绑定）
DynamicParameters p = sql.ToDynamicParameters();

语句执行（SqlResultExecutor，作用于 IDbConnection + SqlResult）

int rows   = connection.Execute(sql);                 // 非查询语句，返回受影响行数
object? v  = connection.ExecuteScalar(sql);           // 首行首列标量
long newId = connection.InsertAndGetId(insertSql);    // INSERT（需 ReturnId()）并回读自增主键
// 以上均有 Async 版本（ExecuteAsync / ExecuteScalarAsync / InsertAndGetIdAsync）

InsertAndGetId 的方言处理：Oracle 走 RETURNING id INTO :… 输出参数（封装在参数里，执行后自动读取）；其余方言走同批次 SELECT 首行首列。

分页查询（自动 Count）

// 先执行 Count 统计总数，再执行分页语句取当前页，两次查询共用构建器的条件参数
PagedResult<User> page = connection.QueryPage(
    Sql.Select<User>().OrderBy(u => u.Id), SqlDialect.MySql, pageNumber: 2, pageSize: 20);

var asyncPage = await connection.QueryPageAsync(builder, SqlDialect.MySql, 1, 20);

分页信息会写入传入的构建器，请勿跨调用复用同一个构建器实例。

方式二 · SqlExecutor 门面

var db = new SqlExecutor(connection, SqlDialect.MySql);
// 可选传入 SqlOptions 局部配置：new SqlExecutor(connection, dialect, new SqlOptions { … })

执行器级设置

db.Logger = result => Console.WriteLine(result.Sql);  // 每条语句渲染后、执行前回调（可接 ILogger 打印 SQL 与参数）
db.QueryTimeout = 30;                                 // 默认命令超时秒数（方法级 commandTimeout 参数优先）

所有方法的尾参均支持 IDbTransaction? transaction 与 int? commandTimeout。

查询

var list  = db.Query(Sql.Select<User>().Where(u => u.IsActive));              // 实体列表
User? one = db.QueryFirstOrDefault(Sql.Select<User>().Where(u => u.Id == id)); // 首行
var page  = db.QueryPage(Sql.Select<User>().OrderBy(u => u.Id), 1, 20);       // 分页（自动 Count）
long cnt  = db.Count(Sql.Select<User>().Where(u => u.DeptId == 1));           // 统计总数
bool has  = db.Exists(Sql.Select<User>().Where(u => u.UserName == "alice"));  // EXISTS 探测
// 以上均有 Async 版本（QueryAsync / QueryFirstOrDefaultAsync / QueryPageAsync / CountAsync / ExistsAsync）

写入

int rows = db.Execute(statement);                                    // 执行任意 SqlResult（含原生片段产物）
long id  = db.Insert(newUser, returnId: true);                       // 插入并回读自增主键
int cnt  = db.InsertRange(userList);                                 // 批量插入（按参数上限自动分片）
var ids  = db.InsertGetIds(userList);                                // 批量插入回读全部主键
        // （PG/SQL Server 走批量 RETURNING/OUTPUT 一次往返，其余方言逐行插入回读）
int upd  = db.Update(Sql.Update<User>().Set(u => u.Age, 21).Where(u => u.Id == id));
int uby  = db.UpdateBy(user);                                        // 全字段更新 + 主键定位
int ups  = db.Upsert(Sql.Upsert(user).OnKey(u => new { u.Code }));   // Upsert
int del  = db.DeleteByKey(user);                                     // 按主键删除
// 以上均有 Async 版本（InsertAsync / InsertRangeAsync / InsertGetIdsAsync / UpdateAsync / …）

多结果集 / 大表批处理

// 多条语句合并为一次往返，返回 GridReader（用完必须 Dispose）
using (var grid = db.QueryMultiple(new ISqlBuildable[] { usersQuery, ordersQuery }))
{
    var users  = grid.Read<User>().ToList();
    var orders = grid.Read<Order>().ToList();
}

// 大表分页遍历：惰性逐页产出（基于 QueryPage，自动 Count）
foreach (var p in db.IterateAll(Sql.Select<Log>().OrderBy(l => l.Id), pageSize: 1000))
{
    Export(p.Items);
}

// 分批处理：每满一页回调一次
db.Chunk(Sql.Select<Log>().OrderBy(l => l.Id), 1000, page => Export(page.Items));

IterateAll 会逐页改写传入构建器的分页参数，请勿复用该构建器；深翻页场景建议按排序键做 keyset 分页。

事务

using (var tran = connection.BeginTransaction())
{
    var txDb = db.WithTransaction(tran);   // 返回绑定事务的执行器副本
    txDb.Update(deduct);
    txDb.Update(credit);
    tran.Commit();                          // 事务的提交/回滚仍由调用方管理
}

PagedResult<T> 分页结果

安全设计

• 所有命令经参数化命令工厂创建：语句文本仅来源于 SqlResult（构建器生成、标识符经方言转义），绑定前经语句校验（空语句 / NUL 控制字符 / 超 1MB 上限拦截），外部值全部以 IDbDataParameter / DynamicParameters 绑定——不存在字符串拼接用户输入进 SQL 的路径
• Oracle 输出参数自动封装，ToDynamicParameters 对同一 SqlResult 只构建一次并缓存
• 方言值规范化（如 Oracle bool → NUMBER 1/0）在参数绑定前自动完成

与核心库的分工

更多文档见源码仓库 docs/ 目录（06-Dapper集成、09-使用SOP操作手册、12-方法使用手册等）。