API 文档

FreeSqlBuilder

方法返回值说明
UseConnectionStringthis设置连接串
UseSlavethis设置从数据库,支持多个
UseConnectionFactorythis设置自定义数据库连接对象(放弃内置对象连接池技术)
UseAutoSyncStructurethis【开发环境必备】自动同步实体结构到数据库,程序运行中检查实体创建或修改表结构
UseNoneCommandParameterthis不使用命令参数化执行,针对 Insert/Update,也可临时使用 IInsert/IUpdate.NoneParameter()
UseGenerateCommandParameterWithLambdathis生成命令参数化执行,针对 lambda 表达式解析
UseLazyLoadingthis开启延时加载功能
UseMonitorCommandthis监视全局 SQL 执行前后
UseNameConvertthis转换实体、属性名称 Entity Property -> Db Filed
Build<T>IFreeSql<T>创建一个 IFreeSql 对象,注意:单例设计,不要重复创建

IFreeSql

属性返回值说明
AdoIAdo数据库访问对象,封装了类似 SqlHelper 操作:ExecuteNonQuery/ExecuteScalar/ExecuteConnectTest 等
AopIAop所有 AOP 拦截方法都在这里
CodeFirstICodeFirst封装 CodeFirst 模式开发相关方法
DbFirstIDbFirst封装 DbFirst 模式开发相关方法
GlobalFilterGlobalFilter全局过滤设置,可默认附加为 Select/Update/Delete 条件
方法返回值参数说明
Select<TEntity>ISelect<TEntity>准备查询数据
Insert<TEntity>IInsert<TEntity>无/TEntity/TEntity[]准备插入
Update<TEntity>IUpdate<TEntity>准备更新数据
Delete<TEntity>IDelete<TEntity>准备删除
InsertOrUpdate<TEntity>IInsertOrUpdate<TEntity>插入或更新数据
TransactionvoidAction开启事务(不支持异步),其他事务
扩展方法返回值参数说明
Select<T1, T2, ... T10>ISelect准备多表查询
CreateDbContextDbContext创建普通数据上下文档对象,该对象功能类似于 EFCore
SetDbContextOptions-Action设置此 IFreeSql 下 DbContext 选项设置
GetRepository<TEntity, TKey>BaseRepository返回默认仓库功能实现
CreateUnitOfWorkIUnitOfWork创建基于仓储功能的工作单元,务必使用 using 包含使用

BaseRepository<TEntity, TKey>

属性返回值说明
EntityTypeType仓储正在操作的实体类型,注意它不一定是 TEntity
UnitOfWorkIUnitOfWork正在使用的工作单元
OrmIFreeSql正在使用的 Orm
DbContextOptionsDbContextOptions正在使用的 DbContext 设置,修改设置不影响其他
DataFilterIDataFilter<TEntity>仓储过滤器,本对象内生效
SelectISelect<TEntity>准备查询数据
方法返回值参数说明
AsTypevoidType改变仓储正在操作的实体类型
GetTEntityTKey根据主键,查询数据
FindTEntityTKey根据主键,查询数据
DeleteintTKey根据主键删除数据
DeleteintLambda根据 lambda 条件删除数据
DeleteintTEntity删除数据
DeleteintIEnumerable<TEntity>批量删除数据
Insert-TEntity插入数据,若实体有自增列,插入后的自增值会填充到实体中
Insert-IEnumerable<TEntity>批量插入数据
Update-TEntity更新数据
Update-IEnumerable<TEntity>批量更新数据
InsertOrUpdate-TEntity插入或更新数据
FlushState-清除状态管理数据
Attach-TEntity附加实体到状态管理,可用于不查询就更新或删除
Attach-IEnumerable<TEntity>批量附加实体到状态管理
AttachOnlyPrimary-TEntity只附加实体的主键数据到状态管理
SaveMany-TEntity, string保存实体的指定 ManyToMany/OneToMany 导航属性(完整对比)
BeginEdit-List<TEntity>准备编辑一个 List 实体
EndEditint完成编辑数据,进行保存动作

状态管理,可实现 Update 只更新变化的字段(不更新所有字段),灵活使用 Attach 和 Update 用起来非常舒服。

DbContext 与 BaseRepository 功能大致类似。

DbContext 自身 = 完整事务,BaseRepository 不一定有事务(可通过设置其 UnitOfWork 属性)。


ICodeFirst

属性返回值说明
IsAutoSyncStructurebool【开发环境必备】自动同步实体结构到数据库,程序运行中检查实体表是否存在,然后创建或修改
IsSyncStructureToLowerbool是否转小写映射,适合 pgsql
IsSyncStructureToUpperbool是否转大写映射,适合 oracle、dameng
IsNoneCommandParameterbool是否不使用命令参数化执行,针对 Insert/Update
IsGenerateCommandParameterWithLambdabool是否生成命令参数化执行,针对 where lambda 表达式解析
IsLazyLoadingbool是否开启延时加载导航属性对象,导航属性需要声明 virtual
IsConfigEntityFromDbFirstbool将数据库的主键、自增、索引设置导入,适合 DbFirst 模式,无须在实体类型上设置 [Column(IsPrimary)]。此功能目前可用于 mysql/sqlserver/postgresql/oracle,此功能会影响 IFreeSql 首次访问的速度。若使用 CodeFirst 创建索引后,又直接在数据库上建了索引,若无本功能下一次 CodeFirst 迁移时数据库上创建的索引将被删除
方法返回值参数说明
GetComparisonDDLStatements<TEntity>string将实体类型与数据库对比,返回DDL语句
GetComparisonDDLStatementsstringType[]将多个实体类型与数据库对比,返回DDL语句
GetComparisonDDLStatementsstringType, string将实体类型与数据库对比,返回DDL语句(指定表名)
SyncStructure<TEntity>bool同步实体类型到数据库
SyncStructureboolType[]同步实体类型集合到数据库
SyncStructureboolType, string同步实体类型到数据库(指定表名)
ConfigEntityICodeFirstAction<TableFluent<T>>FluentAPI 配置实体的特性
GetTableByEntityTableInfoType获取类型在ORM内部的元数据

IDbFirst

方法返回值参数说明
GetDatabasesList<string>获取所有数据库
GetTablesByDatabaseList<DbTableInfo>string[]获取指定数据库的表信息,包括表、列详情、主键、唯一键、索引、外键、备注
GetTableByNameDbTableInfostring获取指定单表信息,包括列详情、主键、唯一键、索引、备注
ExistsTableboolstring判断表名是否存在

ISelect

方法返回值参数描述
ToSqlstring返回即将执行的SQL语句
ToListList<T1>执行SQL查询,返回 T1 实体所有字段的记录,若存在导航属性则一起查询返回,记录不存在时返回 Count 为 0 的列表
ToList<T>List<T>Lambda执行SQL查询,返回指定字段的记录,记录不存在时返回 Count 为 0 的列表
ToList<T>List<T>string field执行SQL查询,返回 field 指定字段的记录,并以元组或基础类型(int,string,long)接收,记录不存在时返回 Count 为 0 的列表
ToOneT1执行SQL查询,返回 T1 实体所有字段的第一条记录,记录不存在时返回 null
Anybool执行SQL查询,是否有记录
SumTLambda指定一个列求和
MinTLambda指定一个列求最小值
MaxTLambda指定一个列求最大值
AvgTLambda指定一个列求平均值
【分页】
Countlong查询的记录数量
Count<this>out long查询的记录数量,以参数out形式返回
Skip<this>int offset查询向后偏移行数
Offset<this>int offset查询向后偏移行数
Limit<this>int limit查询多少条数据
Take<this>int limit查询多少条数据
Page<this>int pageIndex, int pageSize分页
【条件】
Where<this>Lambda支持多表查询表达式,多次使用相当于AND
WhereIf<this>bool, Lambda支持多表查询表达式
Where<this>string, parms原生sql语法条件,Where("id = ?id", new { id = 1 })
WhereIf<this>bool, string, parms原生sql语法条件,WhereIf(true, "id = ?id", new { id = 1 })
WhereCascade<this>Lambda实现多表查询时,向每个表中附加条件
【分组】
GroupBy<this>Lambda按选择的列分组,GroupBy(a => a.Name)
GroupBy<this>string, parms按原生sql语法分组,GroupBy("concat(name, ?cc)", new { cc = 1 })
Having<this>string, parms按原生sql语法聚合条件过滤,Having("count(name) = ?cc", new { cc = 1 })
Distinct<this>.Distinct().ToList(x => x.GroupName) 是对指定字段
【排序】
OrderBy<this>Lambda按列排序,OrderBy(a => a.Time),可多次使用
OrderByDescending<this>Lambda按列倒向排序,OrderByDescending(a => a.Time)
OrderBy<this>string, parms按原生sql语法排序,OrderBy("count(name) + ?cc", new { cc = 1 })
OrderByPropertyNamestring, bool按属性名字符串排序(支持导航属性)
【联表】
LeftJoin<this>Lambda左联查询,可使用导航属性,或指定关联的实体类型
InnerJoin<this>Lambda联接查询,可使用导航属性,或指定关联的实体类型
RightJoin<this>Lambda右联查询,可使用导航属性,或指定关联的实体类型
LeftJoin<this>string, parms左联查询,使用原生sql语法,LeftJoin("type b on b.id = a.id and b.clicks > ?clicks", new { clicks = 1 })
InnerJoin<this>string, parms联接查询,使用原生sql语法,InnerJoin("type b on b.id = a.id and b.clicks > ?clicks", new { clicks = 1 })
RightJoin<this>string, parms右联查询,使用原生sql语法,RightJoin("type b on b.id = a.id and b.clicks > ?clicks", new { clicks = 1 })
From<this>Lambda多表查询,3个表以上使用非常方便,目前设计最大支持10个表
【其他】
As<this>string alias = "a"指定别名
Master<this>指定从主库查询(默认查询从库)
CommandTimeout<this>int命令超时设置(秒)
WithTransaction<this>DbTransaction设置事务对象
WithConnection<this>DbConnection设置连接对象
WithLock<this>EnumSqlServer NoLock 等特有的设置
ForUpdate<this>bool排他更新锁,对不同的数据库已作适配,详细说明见注释
AsQueryableIQueryable将 ISelect 转换为 IQueryable,此方法主要用于扩展,比如:abp IRepository GetAll() 接口方法需要返回 IQueryable 对象。注意:IQueryable 方法污染较为严重,请尽量避免此转换
ToTreeList()List<TEntity>将父子关系的数据以 TreeList 的形式返回
AsTreeCte()ISelect(up, pathSelector, level)递归查询父子关系表

IInsert

方法返回值参数描述
AppendData<this>T1 | IEnumerable<T1>追加准备插入的实体
InsertIdentity<this>指明插入自增列
InsertColumns<this>Lambda只插入的列
IgnoreColumns<this>Lambda忽略的列
CommandTimeout<this>int命令超时设置(秒)
WithTransaction<this>DbTransaction设置事务对象
WithConnection<this>DbConnection设置连接对象
ToSqlstring返回即将执行的SQL语句
OnDuplicateKeyUpdateOnDuplicateKeyUpdate<T1>MySql 特有的功能,On Duplicate Key Update
OnConflictDoUpdateOnConflictDoUpdate<T1>PostgreSQL 特有的功能,On Conflict Do Update
ExecuteAffrowslong执行SQL语句,返回影响的行数
ExecuteIdentitylong执行SQL语句,返回自增值
ExecuteInsertedList<T1>执行SQL语句,返回插入后的记录
ExecuteSqlBulkCopyvoidSqlServer 特有的功能,执行 SqlBulkCopy 批量插入的封装
ExecutePgCopyvoidPostgreSQL 特有的功能,执行 Copy 批量导入数据

IUpdate

方法返回值参数描述
SetSource<this>T1 | IEnumerable<T1>更新数据,设置更新的实体
IgnoreColumns<this>Lambda忽略的列
Set<this>Lambda, value设置列的新值,Set(a => a.Name, "newvalue")
Set<this>Lambda设置列的的新值为基础上增加,Set(a => a.Clicks + 1),相当于 clicks=clicks+1
SetDto<this>object根据 dto 更新的方法
SetRaw<this>string, parms设置值,自定义SQL语法,SetRaw("title = ?title", new { title = "newtitle" })
Where<this>Lambda表达式条件,仅支持实体基础成员(不包含导航对象)
Where<this>string, parms原生sql语法条件,Where("id = ?id", new { id = 1 })
Where<this>T1 | IEnumerable<T1>传入实体或集合,将其主键作为条件
WhereExists<this>ISelect子查询是否存在
CommandTimeout<this>int命令超时设置(秒)
WithTransaction<this>DbTransaction设置事务对象
WithConnection<this>DbConnection设置连接对象
ToSqlstring返回即将执行的SQL语句
ExecuteAffrowslong执行SQL语句,返回影响的行数
ExecuteUpdatedList<T1>执行SQL语句,返回更新后的记录

IDelete

方法返回值参数描述
Where<this>Lambda表达式条件,仅支持实体基础成员(不包含导航对象)
Where<this>string, parms原生sql语法条件,Where("id = ?id", new { id = 1 })
Where<this>T1 | IEnumerable<T1>传入实体或集合,将其主键作为条件
WhereExists<this>ISelect子查询是否存在
CommandTimeout<this>int命令超时设置(秒)
WithTransaction<this>DbTransaction设置事务对象
WithConnection<this>DbConnection设置连接对象
ToSqlstring返回即将执行的SQL语句
ExecuteAffrowslong执行SQL语句,返回影响的行数
ExecuteDeletedList<T1>执行SQL语句,返回被删除的记录