FreeSql （三）实体特性

FreeSql是功能强大的 .NET ORM，支持 .NetFramework 4.0+、.NetCore 2.1+、Xamarin 等支持 NetStandard 所有运行平台。

v1.4.0+ 已自动识别 EFCore 实体特性 Key/Required/NotMapped/MaxLength/StringLength/DatabaseGenerated/Table/Column

主键(Primary Key)

class Topic {
    [Column(IsPrimary = true)]    
    public int Id { get; set; }
}

约定：

• 当没有指明主键时，命名为 id 的字段将成为主键；（不区分大小写）

• 当主键是 Guid 类型时，插入时会自动创建（有序、不重复）的值，所以不需要自己赋值；（支持分布式）

自增(Identity)

class Topic {
    [Column(IsIdentity = true)]    
    public int Id { get; set; }
}

约定：

• 当没有指明主键时，标记自增的成员将成为主键；

唯一键(Unique Key)、索引（Index）

[Index("uk_phone", "phone", true)]
[Index("uk_group_index", "group,index", true)]
[Index("uk_group_index22", "group, index22 desc", true)]
class AddUniquesInfo{
    public Guid id { get; set; }    
    public string phone { get; set; }    
    public string group { get; set; }    
    public int index { get; set; }    
    public string index22 { get; set; }
}

第三个参数 true 的时候是唯一键，false 的时候是普通索引。

数据库类型(DbType)

class Topic {
    [Column(DbType = "varchar(128) NOT NULL")]    
    public string Title { get; set; }
}

可以在类型上指定 NOT NULL，也可以通过 [Column(IsNullable = false)] 设置；

decimal 指定长度 [Column(DbType = "decimal(10,2)")] 或者 [Column(Precision = 10, Scale = 2)]

string 指定长度 [Column(DbType = "varchar(128)")] 或者 [MaxLength(128)] 或者 [Column(StringLength = 128)]，当长度 -1 时产生的映射如下：

注意：Oracle nclob 需要 v1.3.2+ 版本才支持，否则将映射 nvarchar2(4000)

注意：MySql [MaxLength(-2)] 或者 [Column(StringLength = -2)] 映射类型 longtext，其他数据库的映射规则与 -1 相同

服务器时间(ServerTime)

class Topic {

    [Column(ServerTime = DateTimeKind.Utc, CanUpdate = false)]    
    public DateTime CreateTime { get; set; }
    
    [Column(ServerTime = DateTimeKind.Utc)]    
    public DateTime UpdateTime { get; set; }
}

使用数据库时间执行插入数据，注意：

1、一但设置了这个特性，插入的时候设置属性值是无效的；

2、插入实体执行成功后，实体的值还是 c# 时间；

v1.1.0 - ServerTime 特性，对 Update 方法时也能生效

可空(Nullable)

class Topic {
    [Column(IsNullable = false)]    
    public string Title { get; set; }
}

在不指定 DbType、IsNullable 时，FreeSql 提供默认设定，如：

• int -> not null（不可为空）

• int? -> null（可空）

一般在使用 string 类型时，才需要手工指明是否可空（string 默认可空）；

忽略(Ignore)

class Topic {
    [Column(IsIgnore = true)]    
    public string Title { get; set; }
}

当实体有属性不需要映射的时候使用，内部自动忽略了对象的映射；

当实体内的属性不是可接受的类型时，可以不用指定该特定，如下不必要的指定：

class Topic {
    [Column(IsIgnore = true)]    
    public Topic Parent { get; set; }
}

乐观锁(RowVersion)

class Topic {
    public Guid id { get; set; }    
    public string Title { get; set; }

    [Column(IsVersion = true)]    
    public int Version { get; set; }
}

更新整个实体数据时，在并发情况下极容易造成旧数据将新的记录更新。

乐观锁的原理，是利用实体某字段，如：long version，更新前先查询数据，此时 version 为 1，更新时产生的 SQL 会附加 where version = 1，当修改失败时（即 Affrows == 0）抛出异常（DbUpdateVersionException）。

每个实体只支持一个乐观锁属性。

适用 SetSource 更新，无论使用什么方法更新 version 的值都会增加 1

自定义类型映射(MapType)

class EnumTestMap {    
    public Guid id { get; set; }

    [Column(MapType = typeof(string))]    
    public ToStringMapEnum enum_to_string { get; set; }
    [Column(MapType = typeof(string))]    
    public ToStringMapEnum? enumnullable_to_string { get; set; }

    [Column(MapType = typeof(int))]    
    public ToStringMapEnum enum_to_int { get; set; }
    [Column(MapType = typeof(int?))]    
    public ToStringMapEnum? enumnullable_to_int { get; set; }

    [Column(MapType = typeof(string))]    
    public BigInteger biginteger_to_string { get; set; }
    [Column(MapType = typeof(string))]    
    public BigInteger? bigintegernullable_to_string { get; set; }
}public enum ToStringMapEnum { 中国人, abc, 香港 }

BigInteger 也可以映射使用，但请注意：仅仅是 CURD 方便， Equals == 判断可以使用，无法实现 + - * / 等操作；

v0.9.15 版本还可以将值对象映射成 typeof(string)，安装扩展包：

dotnet add package FreeSql.Extensions.JsonMap

fsql.UseJsonMap(); 
//开启功能class TestConfig{    
    public int clicks { get; set; }    
    public string title { get; set; }
}
[Table(Name = "sysconfig")]public class S_SysConfig{
    [Column(IsPrimary = true)]    
    public string Name { get; set; }

    [JsonMap]    
    public TestConfig Config { get; set; }
}

字段位置(Position)

适用场景：当实体类继承时，CodeFirst创建表的字段顺序可能不是想要的，通过该特性可以设置顺序。

创建表时指定字段位置，如：[Column(Position = 1]，可为负数即反方向位置；

可插入(CanInsert)、可更新(CanUpdate)

该字段是否可以插入或更新，默认值true，指定为false插入或更新时该字段会被忽略。

当指明了 InsertColumn/UpdateColumns 等方法时，该特性作用可能失效。例如 CanInsert = false 时，又指明了 InsertColumns 该属性，则仍然会插入。

自定义插入值(InsertValueSql)

执行 Insert 方法时使用此值，它的语法是 SQL。

注意：如果是 getdate() 这种请可考虑使用 ServerTime，因为它对数据库间作了适配。

class Type{
    [Column(InsertValueSql = "'xxx'")]    
    public string Name { get; set; }
}

fsql.Insert(new Type()).ExecuteAffrows();
//INSERT INTO `type`(`Name`) VALUES('xxx')

自定义重写(RewriteSql)、重读(RereadSql)

写入时重写 SQL、读取时重写 SQL，适合 geography 类型的读写场景。

[Column(
    DbType = "geography", 
    RewriteSql = "geography::STGeomFromText({0}, 4236)", 
    RereadSql = "{0}.STAsText()"
    )]
    public string geo { get; set; }
    //插入：INSERT INTO [ts_geocrud01]([id], [geo]) VALUES(@id_0, geography::STGeomFromText(@geo_0, 4236))
    //查询：SELECT TOP 1 a.[id], a.[geo].STAsText() 
    //FROM [ts_geocrud01] a 
    //WHERE (a.[id] = 'c7227d5e-0bcf-4b71-8f0f-d69a552fe84e')

名称

FreeSql 默认使用实体的类名，或属性名与数据库映射，也可以指定映射的名称；

指定实体的表名，指定 Name 后，实体类名变化不影响数据库对应的表。FreeSql尽量支持了对多数据库或schema支持，不防试试指定表名为：其他数据库.表名，不同数据库的指定方式有差异，这一点以后深入解答。

[Table(Name = "db2.tb_topic111")]
class Topic 
{  
    //...
}

注意：尽量不要使用带点的表名，只有 MySql/Sqlite 对此类表名支持 CodeFirst。但是它不影响 CRUD 功能，使用 [Table(Name = "`sys.config`")] 解决

指定实体的表名，修改为实体类名。指定数据库旧的表名，修改实体命名时，同时设置此参数为修改之前的值，CodeFirst才可以正确修改数据库表；否则将视为【创建新表】。

[Table(OldName = "Topic")]
class Topic2 
{
  //...
}

实体的属性也有相同的功能，[Column(Name = "xxx")]

禁用迁移

IFreeSql.CodeFirst.IsAutoSyncStructure 可设置全局【自动迁移结构】功能，也可通过 FreeSqlBuilder.UseAutoSyncStructure(true) 创建 IFreeSql 的时候设置功能。

当【实体类】对应的是数据库【视图】或者其他时，可通过 [Table(DisableSyncStructure = true)] 禁用指定的实体迁移操作。

[Table(DisableSyncStructure = true)]
class ModelDisableSyncStructure {
    [Column(IsPrimary = false)]
    public int pkid { get; set; }
}

备注

FreeSql CodeFirst 支持将 c# 代码内的注释，迁移至数据库的备注。先决条件：

1、实体类所在程序集，需要开启 xml 文档功能；

2、xml 文件必须与程序集同目录，且文件名：xxx.dll -> xxx.xml；

v1.5.0+ 版本增加了对 Description 特性的解析，优先级低于 c# 代码注释；

系列文章导航

FreeSql （一）入门及安装 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二）自动迁移实体 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三）实体特性 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （四）实体特性 Fluent Api - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （五）插入数据 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （六）批量插入数据 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （七）插入数据时忽略列 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （八）插入数据时指定列 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （九）删除数据 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十）更新数据 - 学习文档 - 零一的世界 (vtzw.com)FreeSql （十一）更新数据 Where - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十二）更新数据时指定列 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十三）更新数据时忽略列 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十四）批量更新数据 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十五）查询数据 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十六）分页查询 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十七）联表查询 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十八）导航属性 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （十九）多表查询 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十）多表查询 WhereCascade - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十一）查询返回数据 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十二）Dto 映射查询 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十三）分组、聚合 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十四）Linq To Sql 语法使用介绍 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十五）延时加载 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十六）贪婪加载 Include、IncludeMany - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十七）将已写好的 SQL 语句，与实体类映射进行二次查询 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十八）事务 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （二十九）Lambda 表达式 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三十）读写分离 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三十一）分表分库 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三十二）Aop - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三十三）CodeFirst 类型映射 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三十四）CodeFirst 迁移说明 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三十五）CodeFirst 自定义特性 - 学习文档 - 零一的世界 (vtzw.com)

FreeSql （三十六）进阶 仓储系列文档 - 学习文档 - 零一的世界 (vtzw.com)