Dapper.Smoothie 1.2.5

Dapper.Smoothie - dapper的易用扩展库

Connection 的直接扩展方法

Dapper.Smoothie 包含了一些辅助方法，包括插入、获取、更新、删除记录.

Dapper.Smoothie 的扩展方法完整列表如下：

T Get<T>(id);
IEnumerable<T> GetAll<T>();
int Insert<T>(T obj);
int Insert<T>(Enumerable<T> list);
bool Update<T>(T obj);
bool Update<T>(Enumerable<T> list);
bool Delete<T>(T obj);
bool Delete<T>(Enumerable<T> list);
bool DeleteAll<T>();

要使用这些扩展方法，要求所涉及的实体类(或接口)必须包含主键属性。Dapper 会自动将名为 "id" (不区分大小写)的属性作为主键，当然前提这个属性是存在的。

public class Car
{
    public int Id { get; set; } // 默认主键
    public string Name { get; set; }
}

如果实体类(或接口)不符合上述约定，则使用带有[Key] 或 [ExplicitKey] 特性的属性作为主键.

public class User
{
    [Key]
    int TheId { get; set; }
    string Name { get; set; }
    int Age { get; set; }
}

[Key] 用于数据库自动赋值的字段(例如:自递增字段), 而 [ExplicitKey] 用于在代码中显式赋值的字段.

默认的表名映射规则

• 默认情况下表名为实体类的类型名，比如前面的Car和User类对应的默认表名为Car和User；
• 如果实体用的接口类型，则表名映射规则是接口名去掉首字母I。例如，实体接口为 IPerson，则表名默认为Person；

Get 方法

通过主键获取一个指定实体对象

var car = connection.Get<Car>(1);

或者表中的所有数据。

var cars = connection.GetAll<Car>();

Insert 方法

插入一个实体

connection.Insert(new Car { Name = "Volvo" });

或者插入一个实体列表

connection.Insert(cars);

1. 插入方法返回受影响的行数
2. 插入一个实体时，原实体对象的属性值如果是数据库生成的，则在插入成功后，自动更新到实体的相应属性中（包括主键）

Update 方法

更新一个实体

connection.Update(new Car() { Id = 1, Name = "Saab" });

或更新一个实体列表。

connection.Update(cars);

Delete 方法

删除一个指定主键对应的实体

connection.Delete(new Car() { Id = 1 });

或者删除一个实体列表

connection.Delete(cars);

或者删除表中所有实体

connection.DeleteAll<Car>();

Async 异步方法

上述这些方法均有想对应的异步方法，比如Get对应的是GetAsync，功能上是等同的。

tableName 可选参数

上述这些方法包括其对应的异步方法，均带有一个tableName的可选参数，用于在一些特殊情况下弃用默认的映射规则对应的表名，而使用参数值指定的表名。

特殊 Attributes

Dapper.Smoothie 具有一些可选属性:

• [Table("Tablename")] - 声明实体使用一个不同于类名的表名，可以用在者实体上类或接口上

  [Table ("emps")]
  public class Employee
  {
      public int Id { get; set; }
      public string Name { get; set; }
  }
  

• [Key] - 表明此属性是一个数据库自动赋值的主键

  public class Employee
  {
      [Key]
      public int EmployeeId { get; set; }
      public string Name { get; set; }
  }
  

• [ExplicitKey] - 声明此属性是显式赋值的键，该键不是由数据库自动赋值的

  public class Employee
  {
      [ExplicitKey]
      public Guid EmployeeId { get; set; }
      public string Name { get; set; }
  }
  

• [Write(true/false)] - 声明此属性可、不可写

• [Computed] - 声明此属性是一个计算字段，不应该更新此字段

限制和警告

SQLite

SQLiteConnection 暴露了一个 Update 事件，该事件与 Dapper.Smoothie 提供的 Update 扩展方法冲突. 有两个办法解决冲突.

1. 显式从 SqlMapperExtensions 中调用 Update 方法

   SqlMapperExtensions.Update(_conn, new Employee { Id = 1, Name = "Mercedes" });
   

2. 通过传递类型参数给 Update 方法，使其成为唯一签名

   connection.Update<Car>(new Car() { Id = 1, Name = "Maruti" });
   

snake 命名法的设置

当 Dapper 的全局配置项 DefaultTypeMap.MatchNamesWithUnderscores 设置为 true 时，表名和字段名将经过前述规则获取到后，将再进行一次snake命名法的转换。

比如名为User的类，表名将映射为user；UserRole 将映射为 user_role。这样在使用 postgresql 等大小写敏感的数据库时，将变的很有用。

流式操作 DbSet<T>

我们为数据库连接 IDbConnection 扩展了一个可用表达式流式操作数据的 DbSet<T> 方法，该方法将返回一个带有对 T 类型向对应数据库表操作的对象。这些操作包括：

• 筛选条件 (Where,And,Or)
• 排序 (OrderBy,OrderByDescing)
• 输出限定 (Limit)
• 查询实体或实体列表或某属性集合 (Query,QueryAsync,First,FirstAsync,FirstOrDefault,FirstOrDefaultAsync,Single,SingleAsync,SignleOrDefault,SignleOrDefaultAsync)
• 去重 (Distinct,DistinctAsync)，
• 统计 (Sum,SumAsync,Avg,AvgAsync,Max,MaxAsync,Min,MinAsync)
• 存在性 (Exist,ExistsAsync)，
• 存在性检查 (IfExists,IfNotExists)及其若成立将执行的委托(Then,ThenAsync)，
• 插入数据 (Insert,InserAsync)，
• 更新数据 (Set,Update,UpdateAsync),
• 删除数据 (Delete,DeleteAsync)

DbSet<T>的一些限制和提示

• 在设置了Limit 参数后，统计(Sum,SumAsync,Avg,AvgAsync,Max,MaxAsync,Min,MinAsync)、去重(Distinct,DistinctAsync)、存在性(Exist,ExistsAsync)和无参的存在性检查(IfExists,IfNotExists)，均是对Limit限定查询后结果进行的

• 所有的 IfExists,IfNotExists 在一个流中只能使用一次

• Then 的委托，只对在 IfExists 或 IfNotExists 的结果为true时执行

• IfExists 或 IfNotExists 对 Insert 是有事务性保护的

• 如果要设置 Limit，强烈建议也加上排序 (OrderBy,OrderByDescing) 设置

• 多次设置 Limit，后面的设置会覆盖前面的设置

• 多条排序 (OrderBy,OrderByDescing)规则的先后顺序，影响查询结果的先后顺序

• [查询条件]、[排序规则]、[输出限定]、[存在性检查] 等这些大的组合之间先后顺序，不影响查询结果

• Set 可以设置多次，若对同一个属性设置了多次值，则只有最后一次对该属性的设置有效

• Set 与 Update 或 UpdateAsync 对应，不允许在没有任何 Set 设置的情况下执行Update 或 UpdateAsync

• Delete 或 DeleteAsync 只对 筛选条件 (Where,And,Or) 和 存在性检查 (IfExists,IfNotExists) 有效，其他设置会被忽略

• First,FirstAsync,Single,SingleAsync 在无有效数据情况下，将抛出异常

• Single,SingleAsync 在有效数据超过1条时，也将抛出异常