Skip to content
FreeSql 官方文档FreeSql 官方文档
指南
  • 参考

      • API 文档
        • FreeSqlBuilder
          • IFreeSql
            • BaseRepository<TEntity, TKey>
              • ICodeFirst
                • IDbFirst
                  • ISelect
                    • IInsert
                      • IUpdate
                        • IDelete
                        • 更新日志
                          • 与 Dapper 比较
                            • 与 EntityFramework 比较

                          API 文档

                          2021年2月5日大约 10 分钟约 2915 字

                          此页内容
                          • FreeSqlBuilder
                          • IFreeSql
                          • BaseRepository<TEntity, TKey>
                          • ICodeFirst
                          • IDbFirst
                          • ISelect
                          • IInsert
                          • IUpdate
                          • IDelete

                          # API 文档

                          • http://124.70.130.97:8082/api/FreeSql.htmlopen in new window

                          # 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语句,返回被删除的记录
                          在 GitHub 上编辑此页open in new window
                          上次编辑于: 2021/2/9 下午8:19:44
                          贡献者: luoyunchong
                          Copyright © 2018-present nicye