SmartSql

# SmartSqlMap

SmartSql 的真正强大在于它的映射语句，这是它的魔力所在。由于它的异常强大，映射器的 XML 文件就显得相对简单。如果拿它跟具有相同功能的 ADO.NET 代码进行对比，你会立即发现省掉了将近 96% 代码量， SmartSql 为聚焦于 SQL 而构建，以尽可能地为你减少麻烦，这也是和其他ORM本质区别所在。

属性 说明
Scope 域,用于SqlMap定义Sql声明范围
xmlns 命名空间,固定值："http://SmartSql.net/schemas/SmartSqlMap.xsd"

# SmartSqlMap 子标签

属性 说明
ParameterMaps 参数映射（ParameterMap）集
Caches 缓存策略（Cache）集
Statements 语句（Statement）集
ResultMaps 结果映射（ResultMap）集
MultipleResultMaps 多结果映射（MultipleResultMap）集

# ResultMap

    <ResultMap Id="UserExtendResultMap">
      <Result Column="Data" Property="Info" TypeHandler="Json"/>
    </ResultMap>
属性 说明
Id 唯一性编号

# ResultMap.Result

属性 说明
Column 列名
Property 属性名
TypeHandler 类型处理器，内置（Json/Xml）

# ParameterMap

    <ParameterMap Id="UserExtendParameterMap">
      <Parameter Property="Info" TypeHandler="Json"/>
    </ParameterMap>
属性 说明
Id 唯一性编号

# ParameterMap.Parameter

属性 说明
Property 属性名
TypeHandler 类型处理器，内置（Json/Xml）

# MultipleResultMap

    <MultipleResultMap Id="QueryByPage_Map">
      <Result  Property="Total"/>
      <Result  Property="List"/>
    </MultipleResultMap>

    public class QueryByPageResponse
    {
        public int Total { get; set; }
        public IEnumerable<T_Entity> List { get; set; }
    }
属性 说明
Id 唯一性编号

# MultipleResultMap.Result

属性 说明
Property 属性

# Statement标签

属性 说明
Id 唯一性编号
Cache 缓存策略编号,引用自Cache标签
CommandType Text/StoredProcedure , Default:Text
SourceChoice Unknow/Write/Read , Default:Unknow
ResultMap ResultMap.Id 用于结果映射，列表VS属性名映射，以及字段类型处理器处理
ParameterMap ParameterMap.Id
MultipleResultMap MultipleResultMap.Id，用于返回多结果集映射

# Statement 筛选子标签

标签 真条件
IsNotEmpty !(null or 空字符串 or 空IEnumerable)
IsEmpty null or 空字符串 or 空IEnumerable
IsEqual 与比较值相等
IsNotEqual 参数不等于比较值
IsTrue 参数为 true
IsFalse 参数为 false
IsGreaterEqual 参数大于等于比较值
IsGreaterThan 参数大于比较值
IsLessEqual 参数小于等于比较值
IsLessThan 参数小于比较值
IsNotNull 参数不等于 null
IsNull 参数等于 null
IsProperty 查询对象包含属性名
Switch Switch 标签
Case Switch标签的子标签,等于比较值
Default Switch标签的子标签,未命中任何Case子标签时命中此标签

# Tag标签 公共属性

属性 说明
Prepend 前缀（选填）
Property 属性 （必填）
Required 严格模式：1或true 则此属性必须存在，如无此参数则报错 （选填，默认0）

# IsNotEmpty

针对IEnumerable类型参数的说明：

  1. 对于sql 中常见的in 操作可以使用此标签进行sql构造
  2. 例子中 Ids 也可以用 List<long>{1,2,3} 等价替换
  3. 对于生成的内部逻辑中部分中的名称为@参数名_下标格式的参数请避免前端业务中传递进来
      <IsNotEmpty Prepend="And" Property="FLong">
        T.FLong=@FLong
      </IsNotEmpty>
      <IsNotEmpty Prepend="And" Property="Ids">
          T.Id in @Ids
      </IsNotEmpty>

调用

     DbSession.Query<Object>(new RequestContext
     {
         Scope = nameof(IsNotEmptyTest),
         SqlId = "Query",
         Request = new { FLong = 1,Ids=new long[]{1,2,3} }
     });

（内部逻辑）参数绑定前sql

SELECT
	* 
FROM
	T_Entity T 
WHERE
	T.FLong =@FLong
And id In (@Ids_0,@Ids_1,@Ids_2)

最终转换Sql

SELECT
	* 
FROM
	T_Entity T 
WHERE
	T.FLong =1
And id In (1,2,3)

# IsEmpty

      <IsEmpty Prepend="And" Property="Name" Required="1">
        T.Name=@Name
      </IsEmpty>

# IsEqual

      <IsEqual Prepend="And" Property="Name">
        T.Name=1
      </IsEqual>

# IsNotEqual

      <IsNotEqual Prepend="And" Property="Name">
        T.Name=1
      </IsNotEqual>

# IsTrue

        <IsTrue Prepend="And" Property="FBool">
          T.FBool=1
        </IsTrue>

# IsFalse

        <IsFalse Prepend="And" Property="FBool">
          T.FBool=0
        </IsFalse>

# IsGreaterEqual

        <IsGreaterEqual Prepend="And" Property="FInt" CompareValue="0">
          T.FInt=@FInt
        </IsGreaterEqual>

# IsGreaterThan

        <IsGreaterThan Prepend="And" Property="FInt" CompareValue="0">
          T.FInt=@FInt
        </IsGreaterThan>

# IsLessEqual

        <IsLessEqual Prepend="And" Property="FInt" CompareValue="0">
          T.FInt=@FInt
        </IsLessEqual>

# IsLessThan

        <IsLessThan Prepend="And" Property="FInt" CompareValue="0">
          T.FInt=@FInt
        </IsLessThan>

# IsNotNull

        <IsNotNull Prepend="And" Property="NullStatus">
          T.NullStatus=@NullStatus
        </IsNotNull>

# IsNull

        <IsNull Prepend="And" Property="NullStatus">
          T.NullStatus=@NullStatus
        </IsNull>

# IsProperty

        <IsProperty Prepend="And" Property="NullStatus">
          T.NullStatus=@NullStatus
        </IsProperty>

# Switch-Case-Default

 <Switch Prepend="Order By" Property="OrderBy">
        <Case CompareValue="1">
          T.SortId ASC
        </Case>
        <Default>
          T.SortId Desc,Id Asc
        </Default>
      </Switch>

# Statement 其他子标签

标签 说明
Env 用于判断全局变量 DbProvider
Include 引用外部Statement
Dynamic 动态标签,用于包裹筛选标签,匹配的第一个筛选标签的前缀将忽略
Where 继承至Dynamic,用于包裹筛选标签,匹配的第一个筛选标签前缀被忽略,并添加 Where 前缀
For 用于参数为IEnumerable,遍历参数动态拼接Sql
Set 继承至Dynamic,用于Update,包裹筛选标签,匹配的第一个筛选标签前缀被忽略,并添加 Set 前缀,必须匹配至少一个子标签，否则将抛出SmartSqlException异常。
Placeholder 占位符标签，用于替换参数键值

# Env

鉴于部署对于不同DB环境的配置或语法有不同，为了让一套代码适应多种DB场景，可以用此标签。

    <Statement Id="GetEntity">
      Select * From T_Entity T
      <Where>
        <Env DbProvider="SqlServer" Prepend="And">
          <IsNotEmpty  Property="FLong">
            T.FLong=@FLong
          </IsNotEmpty>
        </Env>
        <Env DbProvider="Mysql" Prepend="And">
          <IsNotEmpty Property="FLong">
            T.FLong=?FLong
          </IsNotEmpty>
          limit 1
        </Env>
      </Where>
    </Statement>

# Include

这个元素可以被用来定义可重用的 SQL 代码段，这些 SQL 代码可以被包含在其他语句中。常用场景：公共的查询条件。比如下面代码中的Query 引用了 QueryParams 代码段。

    <Statement Id="QueryParams">
      <IsNotEmpty  Property="FLong">
        T.FLong=@FLong
      </IsNotEmpty>
    </Statement>
    <Statement Id="Query">
      Select * From T_Entity T
      <Where>
        <Include Prepend="And" RefId="QueryParams" Required="1"/>
      </Where>
    </Statement>

# Dynamic

此元素用来包裹标签集合，来进行对标签动态生成。让内部标签有统一的风格。

注：Dynamic会清除内部第一层第一个标签的Prepend，自身也可以添加Prepend.

<Statement Id="GetUser">
      Select * From T_User T
      <Dynamic Prepend="Where">
        <IsNotEmpty Prepend="And" Property="UserName">
          T.UserName=@UserName
        </IsNotEmpty>
      </Dynamic>
    </Statement>

# 调用

 var user = SqlMapper.QuerySingle<User>(new RequestContext
  {
      Scope = nameof(DynamicTest),
      SqlId = "GetUser",
      Request = new { UserName = "SmartSql" }
  });

# 生成的Sql

SELECT
	* 
FROM
	T_User T 
WHERE
	T.UserName ='SmartSql'

# Where

此标签继承于Dynamic 等价于 形式： Dynamic Prepend="Where" 同样会去除第一层子标签Prepend。

属性 说明
Min 最少匹配数量限制（默认无限制）

# 配置：

    <Statement Id="GetUser">
      Select * From T_User T
      <Where>
        <IsNotEmpty Prepend="And" Property="UserName">
          T.UserName=@UserName
        </IsNotEmpty>
      </Where>
    </Statement>

# 调用

  var user = SqlMapper.QuerySingle<User>(new RequestContext
  {
      Scope = nameof(WhereTest),
      SqlId = "GetUser",
      Request = new { UserName = "SmartSql" }
  });

# 生成Sql

SELECT
	* 
FROM
	T_User T 
WHERE
	T.UserName ='SmartSql'

# Set

此标签继承于Dynamic 等价于 形式： Dynamic Prepend="Set" 同样会去除第一层子标签Prepend。

 <Statement Id="UpdateUser">
      Update T_User
      <Set>
        <IsProperty Prepend="," Property="UserName">
          UserName=@UserName
        </IsProperty>
        <IsProperty Prepend="," Property="Status">
          Status=@Status
        </IsProperty>
      </Set>
      Where Id=@Id
    </Statement>

# 调用

 var iRows = SqlMapper.Execute(new RequestContext
  {
      Scope = nameof(SetTest),
      SqlId = "UpdateUser",
      Request = new { UserName = "MySmartSql",Status=1,Id=1 }
  });

# 生成Sql

UPDATE T_User 
SET 
UserName = 'SmartSql'
,Status = 1 
WHERE
	Id =1

# Placeholder

替换字符串占位符 （此标签直接会以字符串的形式替换标签位，所以存在Sql注入的风险）

    <Statement Id="Query">
     Select * from T_User as T
     Where T.Id in(
     <Placeholder Property="Placeholder"></Placeholder>
     )
    </Statement>

# 调用


 var UserList = SqlMapper.Query<User>(new RequestContext
  {
      Scope = nameof(PlaceholderTest),
      SqlId = "Query",
      Request = new { Placeholder= "Select TUE.UserId From T_UserExtendedInfo as TUE" }
  });

# 生成Sql


SELECT
	* 
FROM
	T_User AS T 
WHERE
	T.ID IN ( SELECT TUE.UserId FROM T_UserExtend AS TUE )

# Cache 标签

属性 说明
Id 唯一性标号
Type Cache类型继承自ICacheProvider,内置常量:Lru 最近最少使用算法,内存缓存, Fifo 先进先出算法,其他继承自ICacheProvider缓存类型均可,例: Type="SmartSql.Cache.Redis.RedisCacheProvider,SmartSql.Cache.Redis"

# Cache 子标签

标签 说明
FlushInterval 定时刷新策略
FlushOnExecute 事件触发策略
Property 作为 ICacheProvider 初始化参数

# FlushInterval

属性 说明
Hours 时
Minutes 分
Seconds 秒

# FlushOnExecute

属性 说明
Statement 触发刷新缓存的声明

# Parameter

属性 说明
Key 键
Value 值

  <Caches>
    <Cache Id="LruCache" Type="Lru">
      <Property Name="CacheSize" Value="10"/>
      <FlushOnExecute Statement="AllPrimitive.Insert"/>
      <FlushInterval Hours="1" Minutes="0" Seconds="0"/>
    </Cache>
    <Cache Id="FifoCache" Type="Fifo">
      <Property Name="CacheSize" Value="10"/>
    </Cache>
    <Cache Id="RedisCache" Type="${RedisCacheProvider}">
      <Property Name="ConnectionString" Value="${Redis}" />
      <FlushInterval Seconds="60"/>
    </Cache>
  </Caches>

  ...

   <Statement Id="QueryByLruCache"  Cache="LruCache">
      SELECT Top 6 T.* From T_AllPrimitive T;
    </Statement>

# For 标签

属性 说明
Open 左闭合
Separator 分隔符
Close 右闭合
Key 唯一性键名
Property 请求属性名

# 应用场景

# 批量新增

<Statement Id="InsertBatch">
      INSERT INTO T_Entity
      (FString
      ,FDecimal
      ,FNullDecimal
      ,FBool
      ,FNullBool
      ,Status
      ,NullStatus
      ,CreationTime
      ,LastUpdateTime)
      VALUES
      <For Open="" Close="" Key="T" Property="Items" Separator=",">
        (@FString
        ,@FDecimal
        ,@FNullDecimal
        ,@FBool
        ,@FNullBool
        ,@Status
        ,@NullStatus
        ,@CreationTime
        ,@LastUpdateTime)
      </For>
    </Statement>

var items = new List<T_Entity> {
new T_Entity
{
    CreationTime = DateTime.Now,
    FBool = true,
    FDecimal = 1,
    FLong = 1,
    FNullBool = false,
    FString = Guid.NewGuid().ToString("N"),
    FNullDecimal = 1.1M,
    LastUpdateTime = DateTime.Now,
    Status = EntityStatus.Ok
},new T_Entity
{
    CreationTime = DateTime.Now,
    FBool = true,
    FDecimal = 1,
    FLong = 1,
    FNullBool = false,
    FString = Guid.NewGuid().ToString("N"),
    FNullDecimal = 1.1M,
    LastUpdateTime = DateTime.Now,
    Status = EntityStatus.Ok
}
};
_sqlMapper.Execute(new RequestContext
{
Scope = Scope,
SqlId = "InsertBatch",
Request = new { Items = items }
});

# 多 Like 查询

    <Statement Id="Query">
      Select T.* From T_Entity T
      <Where>
        <For Prepend="And" Key="LikeKey" Open="(" Close=")" Property="FStrings" Separator="Or">
          T.FString Like Concat(@LikeKey,'%')
        </For>
      </Where>
    </Statement>

            RequestContext context = new RequestContext
            {
                Scope = Scope,
                SqlId = "Query",
                Request = new { FStrings = new string[] { "SmartSql", "SmartCode" } }
            };
            var list = _sqlMapper.Query<T_Entity>(context);

生成的SQL

Select T.* From T_Entity T With(NoLock)
       Where   (
          T.FString Like Concat(@LikeKey_For__FStrings_0,'%')
         Or
          T.FString Like Concat(@LikeKey_For__FStrings_1,'%')
        )

←