SqlEntity 5.8.4

SqlEntity

使用对象化Sql通过ADO.Net访问数据库,建立数据关系映射,中重度架构,构建明确的表和列类型,支持类Linq查询语法

理论上,这个模型可以适用于所有ADO.Net访问数据库的形式,但现在仅适配了SqlServer

可用于 .net standard 2.0/2.1 和 .net framework 4.6/4.7/4.8 及 .net 5/6/7/8/9

使用说明和示例正在续写中 ( 所有代码都由 C# 编写 )

本说明共有6个部分

1. 数据库访问对象 DAO
2. 表结构对象 TableSchma 及列对象 Field
3. 表访问对象 TableAccess 及行实体 RowEntity
4. 根对象 RootBase 及树形逻辑架构
5. 更高级的用法
6. API列表

一. 数据库访问对象 DAO

• 首先创建DAO类的实例
• 使用Open方法建立连接
• 使用Execute方法执行Sql语句或存储过程
• 使用Select方法执行Select语句并返回DataSet
• 使用From方法按LinQ流水线风格, 生成Sql执行并填充到指定对象

使用SqlEntity, 需要在安装好之后, 引入一个命名空间

using SqlEntity;

数据库连接示例

public Result<DAO> CreateDao()
{
    var dao = new DAO(Helper.GetSettingBySqlServer());
    //三种不同的连接方式, 按具体情况选用
    //var result = dao.Open("数据库连接参数");
    //var result = dao.Open("服务器IP","数据库名","用户名","密码");
    var result = dao.Open(DaoConnectionArgs.LoadFile("配置文件路径"));
    var ret = new Result<DAO>();
    //返回的文本不是1,就表示出错了
    if (result != "1") return ret.ToError(result);
    return ret.ToOK(dao);
}

数据库操作示例

public void DaoAccessTest()
{
    //DAO创建失败时提示错误信息,并返回null.
    var dao = CreateDao().WhenNull(err => MessageBox.Show("数据库连接失败: " + err));
    if (dao == null) return;

    //Run示例. Run用来执行一段Sql, 并返回是否成功.
    //这里可以执行Insert/Update/Delete/Declare/Set等等,支持多条Sql语句
    //Execute方法用来去服务器执行Sql, 只有执行失败时才会执行参数的委托
    //Execute有多个重载,可以根据需要选用
    bool result1 = dao.Run("Sql指令或存储过程").Execute(err => MessageBox.Show("执行失败: " + err));

    //Select示例1. 专用来执行单个Select, 并返回结果集(DataTable)
    Result<DataTable> result2 = dao.Select("Select语句,只返回一个Select结果集");
    DataTable datatable = result2.WhenNull(err => MessageBox.Show("Sql执行失败: " + err));

    //Select示例2. 专用来执行多个Select, 并返回多个结果集(DataSet)
    Result<DataSet> result3 = dao.SelectM("Select语句,返回多个Select结果集");
    if (result3.Item == null) MessageBox.Show("Sql执行失败: "+result3.ErrText);
    DataSet dataset = result3.Item;

    //还可以使用From构建LinQ风格的Select执行过程,这放在后面再讲
}

==直到现在都没有看到对象化Sql,是因为这需要你首先构建表结构==

二. 表结构对象 TableSchma 及列对象 Field

• 使用DAO对象就可以直接操作数据库了,如果这就是你要的,那你就没有必要向下看了.

• 但是SqlEntity最让人印象深刻的功能实现, 是Sql的对象化, 在代码中实现数据库的表结构就成了最关键的一个步骤. 你需要为数据库当中的所有表都做一个表结构的映射, 这为你后续的功能实现带来很多好处.

• Sql的对象化就完全依赖TableSchema(表结构对象)实现的, 除此之外, ==你还可以用它进行数据库结构检查==(几句代码实现查找数据库当中结构定义是否符合要求)

• 当然, 最有魅力的还是Linq风格的链式语法, 它能直接绑定到对象, 就像市场上现在最流行的ORM那样, 但是我这里不是使用表达式树实现的Sql生成, 而是使用运算符重载, 这是C#的一个古老而实用的功能, 是它让Sql对象化实现得以如此丰富多彩.

• 支持的数据库数据类型是有限的, 你必须使用下列类型构建数据库表结构映射

  SqlEntity 的 Field 类型	对应的 SqlServer 类型	对应的 C# 值类型
  FieldInt	int, smallint, tinyint, bigint	int, long
  FieldChars	varchar(n), varchar(max), char(n)	string
  FieldText	nvarchar(n), nvarchar(max)	string
  FieldDate	datetime, datetime2(n), date	datetime
  FieldReal	decimal(m,n)	decimal, double
  FieldBytes	varbinary(n), varbinary(max)	byte[]
  FieldBool	bit	bool
  FieldGuid	uniqueidentifier	Guid

//表结构实体类必须从 TableSchema 继承.
//TableCaptionAttribute 不是必须的.
//类名就是表名(自动去掉Schema后缀,此例中表名为Ware)
[TableCaption("商品档案表")]
public class WareSchema : TableSchema
{
    public WareSchema()
    {
        //此句设置表的主键.
        SetPrimaryKey(Id);
        //此句设置表的自增列.
        SetAutoNumberColumn(Id);
        //此句设置表的聚集索引.
        SetMainIndex(false, CreateTime);
        //添加唯一索引, 一个表可以有多个索引
        AddUniqueIndex(Name);
        //添加不唯一索引
        //AddNotUniqueIndex(TypeId);

        //上面的语句用于初始化数据库, 以及数据库结构检查
    }

    /// <summary>商品编号, Int类型, 列名就是成员名</summary>
    public FieldInt Id = new FieldInt();
    /// <summary>商品名称, nvarchar(30), 列名就是成员名</summary>
    public FieldText Name = new FieldText(30);
    /// <summary>类型编号, int, 列名就是成员名</summary>
    public FieldInt TypeId = new FieldInt();
    /// <summary>建档时间, datetime2(2), 列名就是成员名</summary>
    public FieldDate CreateTime = new FieldDate();
    /// <summary>单价, decimal(9,2), 列名就是成员名</summary>
    public FieldReal Price = new FieldReal();
    /// <summary>库存数量, smallint, 列名就是成员名</summary>
    public FieldInt Store = new FieldInt(EmDataTypeInt.SmallInt);
    public FieldText Unity = new FieldText(4);
    /// <summary>条形码, varchar(13), 列名就是成员名</summary>
    public FieldChars Ean13 = new FieldChars(13);
    /// <summary>积分倍率, decimal(5,2), 列名就是成员名. </summary>
    public FieldReal ValueRate = new FieldReal(5, 2);
}

使用Sql对象化构建Select语句, 并返回执行结果 ( 数据集 )

例1

//生成的Sql相当于: Select Price from Ware where id=12;
//From 表示一个 Select 的开始
//Where 用来生成Sql的条件
//Select 用来生成返回值列表
//Run 可以实现把值绑定到对象的过程.
//Run 其中的 s 来源于 Select 方法返回的对象, r 是 DataReader 对象,
//    r 包含了返回的数据(第一行数据), 此例中 r[s] 表示取列s的值返回
var value1 = dao.From<WareSchema>()
    .Where(s => s.Id == 12)
    .Select(s => s.Price)
    .RunFirst((s, r) => r[s]);
if (value1.Item == null)
{
    MessageBox.Show(value1.ErrText);
}
else
{
    MessageBox.Show(value1.Item?.ToString("0.00"));
}

上例返回的是一个 Result<decimal?>, 下例返回的是一个 Result<匿名对象>, 这个对象有两个属性: Name 和 Price, 它是在 RunFirst 当中建立的

例2

//生成的Sql相当于: Select Name,Price from Ware where id=12;
var obj1 = dao.From<WareSchema>()
    .Where(s => s.Id == 12)
    .Select(s => new { s.Name, s.Price })
    .RunFirst((s, r) => new { Name = r[s.Name], Price = r[s.Price] });
if (value1.Item == null)
{
    MessageBox.Show(value1.ErrText);
}
else
{
    MessageBox.Show("Name: " + obj1.Item.Name + " Price: "
        + (obj1.Item.Price?.ToString("0.00") ?? ""));
}

前例都只是返回了第一行数据(用RunFirst), 本例返回所有符合条件的行(用Run)

例3

//生成的Sql相当于: Select Id,Name,Price from Ware where Name like '%矿泉水%';
var list1 = dao.From<WareSchema>()
    .Where(s => s.Name.LikeAll("矿泉水"))
    .Select(s => new { s.Id, s.Name, s.Price })
    .Run((s, r) => new { Id = r[s.Id], Name = r[s.Name], Price = r[s.Price] ?? 0 });
if (list1.Item == null) { MessageBox.Show(list1.ErrText); return; }
foreach (var item in list1.Item)
{
    MessageBox.Show("Id: " + item.Id + " Name: " + item.Name
        + " Price: " + item.Price.ToString("0.00"));
}

上例返回的是匿名对象,下面是返回 Entity01 自定义对象

例4

//Entity01 当中定义了 Select 映射关系, 其中的 Total 是通过计算得到的值
//生成的Sql相当于: Select Id, Name, Price, Store, Price*Store Total from Ware where Name like '%矿泉水%';
//Entity01 对象实体类的定义在下面
var wareSchema = new WareSchema();
var list2 = dao.From(wareSchema)
    .Where(s => s.Name.LikeAll("矿泉水"))
    .Select(Entity01.Select)
    .Run<Entity01>();
if (list2.Item == null) { MessageBox.Show(list2.ErrText); return; }
foreach (var item in list2.Item)
{
    MessageBox.Show("Id: " + item.Id + " Name: " + item.Name
        + " Total: " + item.Total.ToString("0.00"));
}

上例是单表查询, 接下来展示两个表的 Join 查询,

例5

//From 方法最多支持 5 个表的 Join 查询
//WareTypeSchema 表结构类的定义在下面
//Entity02 对象实体类的定义在下面
var typeSchema = new WareTypeSchema();
var list3 = dao.From(wareSchema).InnerJoin(typeSchema)
    .On((s1, s2) => s1.Name.LikeAll("矿泉水") & s1.TypeId == s2.Id)
    .Select(Entity02.Select)
    .Run<Entity02>();
foreach (var item in list3.Item)
{
    MessageBox.Show("Id: " + item.Id + " Name: " + item.Name + " TypeName: "
        + item.TypeName + " Total: " + item.Total.ToString("0.00"));
}

Entity01 的类型定义

/// <summary>
/// 对象实体类, 用来接收从数据库返回的数据. 
/// 它本身就是一个普通的类. 
/// 数据映射机制是由使用方 ( 比如 From 的 Run 方法 / Fill 方法 ) 制定的.
/// 默认的映射机制是按同名规则, 使用反射技术自动完成数据映射
/// </summary>
public class Entity01
{
    public int Id;
    public string Name;
    public decimal Price;
    public int Store;
    public decimal Total;

    /// <summary>
    /// 这里定义 Select 返回值与对象成员的映射关系. 
    /// 返回的匿名对象成员与类成员同名, 就形成了对应关系. 
    /// 必须保证实体类的成员类型与返回值类型形成对应关系.
    /// </summary>
    public static object Select(WareSchema s)
    {
        return new { s.Id, s.Name, s.Price, s.Store, Total = s.Price * s.Store };
    }
}

WareTypeSchema 的类型定义

public class WareTypeSchema : TableSchema
{
    public WareTypeSchema()
    {
        SetPrimaryKey(Id);
        AddUniqueIndex(Name);

        //上面的语句用于初始化数据库, 以及数据库结构检查
    }

    public FieldInt Id = new FieldInt();
    public FieldText Name = new FieldText(20);
}

Entity02 的类型定义

public class Entity02
{
    public int Id;
    public string Name;
    public string TypeId;
    public string TypeName;
    public decimal Price;
    public int Store;
    public decimal Total;

    public static object Select(WareSchema s1, WareTypeSchema s2)
    {
        return new
        {
            s1.Id,
            s1.Name,
            s1.TypeId,
            TypeName = s2.Name,
            s1.Price,
            s1.Store,
            Total = s1.Price * s1.Store,
        };
    }
}

三. 表访问对象 TableAccess 及行实体 RowEntity

1. 表访问对象 ( TableAccesser ) 存在的意义:

• TableAccesser 是专门用来和数据库交互的, 它包含一个 TableSchema 对象的实例, 内部包含了专门用来访问这个表的许多方法, 使用它访问数据库会事半功倍.

• 虽然使用 DAO.From 也能访问数据库表了, 可以直接合成 Sql 并执行, 但有些情况下, 我们可能仅仅需要运行一个简单的 Select, 却需要搬弄复杂的 Linq, 感觉很麻烦.

• 对数据库表的操作不只是有 Select, 还有 Insert, Update, Delete 等等其它操作.

• 表访问对象可以相互关联/包含, 从而形成关系树, 最后全部建立在根对象 RootBase 当中, 形成一个包含所有表的对象树, 从而掌控全局.

2. 表访问对象的创建方法:

例子: 这里创建了两个表访问对象: 商品表 和 商品分类表, 其中 商品表 当中包含了 商品分类表 访问对象的实例

public class WareSimple : TableAccessor<WareSchema>
{
    public WareTypeSimple Type = new WareTypeSimple();
}

public class WareTypeSimple : TableAccessor<WareTypeSchema>
{

}

表访问对象的创建和使用

//创建商品表访问对象的实例,它内部还包含了商品分类表
var ware = new WareSimple();
//使用InjectDao传入DAO的实例
ware.InjectDao(dao);
//使用 Linq 方法获取编号为 1 的商品品名
string wareName = ware.From()
    .Where(s => s.Id == 1)
    .Select(s => new { s.Name })
    .RunFirst((s, r) => r[s.Name])
    .WhenErr(err => MessageBox.Show(err));
//向商品分类表插入一行数据
bool result = ware.Type.Insert(s => new[] { s.Id == 1, s.Name == "默认分类" })
    .Execute(err => MessageBox.Show(err));
//更新商品分类表的数据
result = ware.Type.Update(s => s.Id == 1, s => new[] { s.Name == "分类1" })
    .Execute(err => MessageBox.Show(err));

表访问对象当中包含了非常多的方法, 请查阅 API 文档了解详细信息

3. 行实体 RowEntity

所谓行实体, 就是用来表示一行数据的实体类, 行实体必须从 RowEntity 继承.

行实体类的成员类型和名称必须和表结构对象(TableSchema)一一对应. 如果确有例外, 可以重写 Fill__Row 方法自己完成数据映射.

public class WareRow : RowEntity<WareSchema>
{
    /// <summary>商品编号</summary>
    public int Id;
    /// <summary>商品名称</summary>
    public string Name;
    /// <summary>类型编号</summary>
    public int TypeId;
    /// <summary>建档时间</summary>
    public DateTime CreateTime;
    /// <summary>单价</summary>
    public decimal Price;
    /// <summary>库存数量</summary>
    public int Store;
    public string Unity;
    /// <summary>条形码</summary>
    public string Ean13;
    /// <summary>积分倍率</summary>
    public decimal ValueRate;
}

public class WareTypeRow : RowEntity<WareTypeSchema>
{
    public int Id;
    public string Name;
}

现在,我们重新建立表访问对象, 注意这里的 TableAccesser 是带两个泛型类型的.

public class Ware : TableAccessor<WareSchema, WareRow>
{
    public WareType Type = new WareType();

    public Ware()
    {
        // 创建一个关系, 此句专门用于初始化数据库, 以及数据库结构检测
        Type.AddFKeys(this).NoDelete(r => r.Id, p => p.TypeId);
    }
}

public class WareType : TableAccessor<WareTypeSchema, WareTypeRow>
{

}

这样的表访问对象包含的方法, 可以更方便的返回行实体对象, 对于需要经常获取整行数据的表非常合适.

public void Test1()
{
    //DAO创建失败时提示错误信息,并返回null.
    var dao = CreateDao().WhenNull(err => MessageBox.Show("数据库连接失败: " + err));
    if (dao == null) return;
    //创建商品表访问对象的实例,它内部还包含了商品分类表
    var ware = new Ware();
    //使用InjectDao传入DAO的实例
    ware.InjectDao(dao);
    //使用 FindClassic 方法获取编号为 1 的商品数据实体
    //FindClassic 方法用来返回符合条件的第一行
    // 返回数据为经过包装的 WareRow实例
    var wareRow = ware.FindClassic(s => s.Id == 1);
    if (wareRow.ErrText != "") MessageBox.Show(wareRow.ErrText);
    // Select * from ware where name like %矿泉水%
    // 执行Sql并返回结果集合
    // FindAllClassic 方法用来返回所有符合条件的数据实体列表
    // 返回数据为经过包装的 List<WareRow>实例
    var wareList = ware.FindAllClassic(s => s.Name.LikeAll("矿泉水"));
}

到这里,你就能方便的获取到你需要的任何数据了,但这还没完,后面还有更高级的功能.

四. 根对象 RootBase 及树形逻辑架构

我已经可以很方便的访问数据了, 为什么还要创建根对象? 它到底有什么用?

• RootBase 是根对象的基类, 你应该在你的应用程序中创建一个类, 让它继承 RootBase.
• 根对象应包含数据库当中的全部表的表访问对象 ( TableAccesser ). 根对象做为访问数据库的唯一对象, 代表了整个数据库.
• 根对象包含的 TableAccesser 并不是平铺的, 而是按包含关系形成的树形结构, 这样可以用最方便的方式找到你需要的表, 利于操作. 同时也会直观地看到各个表之间的关系.
• 每次访问数据库的时候, 都是从一个Root对象开始, 会让你在操作数据库的时候非常方便简单, 你不用刻意记住数据库当中到底有哪些表, 叫什么名字, 只要翻一翻Root对象的成员就能找到.
• 不论是 WinForm 还是 WebApi, 都应只创建一个根对象的实例, 之后反复使用它, 所以它必须是无状态的对象.
• 只有创建了根对象, 才能使用更高级的功能. 比如空数据库创建所有表, 让你的数据库可以从零创建出来; 数据库结构检测, 让数据库结构一直与程序保持同步. 这些功能对于数据处理方面的软件来说非常重要.

示例1

/// <summary>数据访问的根对象,只应创建一个实例</summary>
public class RootTop : RootBase
{
    public RootTop(DAO theDao) : base(theDao)
    {
    }

    public Admin Admin = new Admin();
    public Ware Ware = new Ware();
}

// 下面是相关的表访问对象

/// <summary>管理员表结构</summary>
public class AdminSchema : TableSchema
{
    public AdminSchema()
    {
        SetPrimaryKey(Id);

        //上面的语句用于初始化数据库, 以及数据库结构检查
    }

    public FieldChars Id = new FieldChars(15);
    public FieldText Name = new FieldText(20);
    public FieldBytes Password = new FieldBytes();
}

/// <summary>管理员表访问对象</summary>
public class Admin : TableAccessor<AdminSchema>
{

}

实例化Root对象

/// <summary>Root对象应用示例</summary>
public class StartApp
{
    // 此对象是全局静态成员, 可以在程序各处直接使用
    public static RootTop Root { get; set; }

    public void Main()
    {
        var dao = CreateDao();
        if (dao.Item == null)
        {
            MessageBox.Show("数据库连接失败: " + dao.ErrText);
            return;
        }
        // 实例化Root对象
        Root = new RootTop(dao.Item);
        // 接下来进行其它初始化过程
        // 此代码仅是对应用程序启动初始化的模拟
        // 对于 WebApi 应用, 一般是使用注入的方法, 把Root对象按单例模式注入
    }

    public static Result<DAO> CreateDao()
    {
        var dao = new DAO(Helper.GetSettingBySqlServer());
        //三种不同的连接方式, 按具体情况选用
        //var result = dao.Open("数据库连接参数");
        //var result = dao.Open("服务器IP","数据库名","用户名","密码");
        var result = dao.Open(DaoConnectionArgs.LoadFile("配置文件路径"));
        var ret = new Result<DAO>();
        //返回的文本不是1,就表示出错了
        if (result != "1") return ret.ToError(result);
        return ret.ToOK(dao);
    }
}

有了 Root 对象, 我们可以在程序的任何位置使用它, 就可以随时方便快捷的访问数据库了.

Root 对象的使用很简单, 不特意举例了. 下面说两个和 Root 对象有关的重要功能:

1. 获取生成数据库全表的创建语句. 可以用来在程序刚刚安装完成时, 从一个空数据库创建所有表.

    // 初始化数据库表结构
    if (Root.Dao.TableNameExist(Root.Admin.Schema.Table.Name) == "0")
    {
        //生成创建逻辑单元所需要的所有表/列/关系的SQL语句
        var createSql = Root.GetCreateTableSQL();
        if (!Root.Dao.Run(createSql).Execute(err => MessageBox.Show("数据库表结构初始化失败")))
        {
            return;
        }
    }
   

2. 数据库结构检测. Winform 可以在应用程序启用时检查, 检查失败时中止程序的加载; Webapi 可以做一个专门的检查入口. 显示检查的结果.

    // 数据库结构检测.
    var schema = new Schemas();
    var result = schema.Create(dao.Item);
    if (result != "1")
    {
        MessageBox.Show("获取数据库结构时失败: " + result);
        return;
    }
    var check = Root.SchemaCheck(schema);
    if (check.Description != "")
    {
        MessageBox.Show("数据库结构不匹配: \r\n 类型: " + check.CheckType
            + "\r\n 说明: " + check.Description
            + "\r\n 相关操作: " + check.CreateText);
        return;
    }
   

五. 进阶篇 ( 文章规划中 )

Result 对象.

( DAO ) 使用数据库连接参数文件连接数据库.

( TableSchema ) 计算列及对象.

( TableSchema ) By.

( TableSchema ) Case.

( Operator ) 支持的运算符

( Linq ) 仿 Linq 链式语法的运用规则.

( TableAccessor ) Find.

( TableAccessor ) If.

( TableAccessor ) 多 Select 及多 Command

( Sql对象 ) SqlSelect.

( Sql对象 ) SqlInsert SqlUpdate SqlDelete SqlMerge.

六. API 列表 ( 文章规划中 )

2024-12-16: 解决Linq的 Select(s=>s.列对象), 这样直接使用列对象时， 会出错的Bug