[C#]JCoder.Db4Net.ORM，基于JCoder.Db4Net的ORM库，轻量的MIT协议类库

# JCoder.Db4Net.ORM

属性
作者(Authors)	Jackie Law
版权(Copyright)	Copyright © Jackie Law. All rights reserved.
协议	MIT
联系(QQ)	1378071853
联系(Wechat)	JackieLaw1024
联系(Email)	JackieLaw-dev@outlook.com

---

一.架构说明

JCoder.Db4Net.ORM
语言	C#
协议	MIT
.Net框架	.Net Standard2.1; .Net Framework 4.7.2; .Net 7; .Net 6;
简述	Database类库，一个基于JCoder.Db4Net的ORM库。

---

1.1 引用类库

引用类库	版本
JCoder.Db4Net	>=2.23.0

---

1.2 相关类库

相关类库	说明
JCoder.Db4Net	一款为方便使用数据库的操作类库。
JCoder.Db4Net.ORM	一个基于JCoder.Db4Net的ORM库。
JCoder.Db4Net.Sqlite	一个基于JCoder.Db4Net且支持Sqlite的库。
JCoder.Db4Net.MySql	一个基于JCoder.Db4Net且支持Mysql的库。
JCoder.Db4Net.SqlServer	一个基于JCoder.Db4Net且支持SqlServer的库 。
JCoder.Mock4Net	一款简易版的用于模拟数据的功能库。
JCore.Log4Net	一款用于日志的类库。

---

二.获取方式

1. 版本要求：>=2.23.0
2. 以版本2.23.0为例

获取方式	描述
Package Manager	Install-Package JCoder.Db4Net.ORM -Version 2.23.0
.Net CLI	dotnet add package JCoder.Db4Net.ORM --version 2.23.0
PackageReference	<PackageReference Include="JCoder.Db4Net.ORM" Version="2.23.0" />
Paket CLI	paket add JCoder.Db4Net.ORM --version 2.23.0
Script&Interactive	#r "nuget: JCoder.Db4Net.ORM, 2.23.0"
Cake	// Install as a Cake Addin #addin nuget:?package=JCoder.Db4Net.ORM&version=2.23.0 // Install as a Cake Tool #tool nuget:?package=JCoder.Db4Net.ORM&version=2.23.0

---

三.使用说明

3.1 主要类与接口

名称	类型	描述
Orm	类	工具类，主要用于数据库在数据对象上的通用处理。

---

3.2特性说明

Attribute类	应用位置	描述
DbDatabaseAttribute	Class、Struct	数据库的相关信息，可用于通过Entity进行CRUD。
DbTableAttribute	Class、Struct	数据库的数据表信息，可用于通过Entity进行CRUD。
DbViewAttribute	Class、Struct	数据库的视图信息，可用于通过Entity进行查询等操作。
DbRefTableAttribute	Property	(未完成)关联的数据表信息，可用于通过Entity获取关联的副表数据。
DbFieldAttribute	Property	数据列信息，可用于通过Entity进行CRUD。
DbFieldExtendAttribute	Property	数据列的扩展信息。
DbFieldPropertyAttribute	Property	数据列的属性信息。
DbNumberExtAttribute	Property	数字型数据列的扩展信息。
DbStringExtAttribute	Property	文本型数据列的扩展信息。
DbTimeExtAttribute	Property	时间型数据列的扩展信息。
DbAllowNullAttribute	Property	数据列是否允许为Null值。
DbAutoIncrementAttribute	Property	数据列是否自动增长。
DbPrimaryKeyAttribute	Property	数据列是否为主键数据列。
DbForeignKeyAttribute	Property	数据列是否为外键数据列。
DbGuidAttribute	Property	(未完成)数据列是否为GUID数据列。
DbIndexAttribute	Property	数据表的索引列信息。
DbIndexFieldPropertyAttribute	Property	数据表的索引列的扩展属性信息。
DbIgnoreAttribute	Property	进行与数据库相关的处理时，将忽略标记的字段与属性。
DbIgnoreInsertAttribute	Property	进行Insert处理时，将忽略标记的字段与属性。
DbIgnoreUpdateAttribute	Property	进行Update处理时，将忽略标记的字段与属性。
DbEnumNameAttribute	Property	Entity数据转换为DataTable时，将枚举字段、属性转换为枚举名称的数据列。
DbFieldRouteAttribute	Property	Entity数据转换为DataTable时，根据路径获取标记属性对象中的实例值。
DbIgnoreConvertionAttribute	Property	Entity数据转换为DataTable时，将忽略标记的字段与属性。
DbJsonAttribute	Property	(未完成)Entity数据转换为DataTable时，将字段、属性转换为Json格式的数据列。
DbNameAttribute	Class、Struct、Property	名称信息。可应用于以下情况，1.定义DataTable的数据列名称；2.定义DataTable的Table名称；
DbSortAttribute	Property	排序信息。可用于Entity转换为DataTable时的DataColumn顺序。

---

3.3 函数名称说明

注意事项	描述
函数名称包含Entity或Entities	属性数据处理以DbAttribute优先。
函数名称包含Object或Objects	属性数据有多种处理方式。 OnlyProperty方式直接忽略DbAttribute。 OnlyDbAttribute方式只处理有DbAttribute的。 DbAttributeFirst方式以DbAttribute优先。

---

3.4 扩展使用

1)ToEntity1st（查询数据，并将首条数据转换为数据实例）

// ToEntity1st（查询数据，并将首条数据转换为数据实例）
using JCoder.Db4Net;
using JCoder.Db4Net.ORM;

IDbOperator _operator = new MsSqlFactoryOperator()
{
    ConnectionString = "Server=127.0.0.1;Database=test;Uid = user; Pwd=testpassword;"
};
return this.Operator.ToEntity1st<T>("select top 1 * from table1;");

2)ToEntities（查询数据，并转换为数据实体列表）

// ToEntities（查询数据，并转换为数据实体列表）
using JCoder.Db4Net;
using JCoder.Db4Net.ORM;

IDbOperator _operator = new MsSqlFactoryOperator()
{
    ConnectionString = "Server=127.0.0.1;Database=test;Uid = user; Pwd=testpassword;"
};
return this.Operator.ToEntities<T>("select top 10 * from table1;");

3)CRUD（增删查改）

using JCoder.Db4Net;
using JCoder.Db4Net.ORM;

// Test Entity Class
[DbTable("t_table_test")]
 public class TestEntity
 {
     [DbPrimaryKey]
     [DbAutoIncrement]
     public int Key001 { get; set; }
     [DbPrimaryKey]
     [DbField(IsUnique=true)]
     public string Key002 { get; set; }

     [DbIndex("idx01")]
     public string C003 { get; set; }
 }

IDbOperator _operator = new MsSqlFactoryOperator()
{
    ConnectionString = "Server=127.0.0.1;Database=test;Uid = user; Pwd=testpassword;"
};

TestEntity x = new TestEntity()
{
    Key001 = 101,
    Key002 = "Test PK",
};

// Insert Data（新增数据）
this.Operator.Insert<TestEntity>(x);

// Update Data（更新数据）
x.C003 = "Update Test";
this.Operator.Update<TestEntity>(x);

// Delete Data（删除数据）
this.Operator.Delete<TestEntity>(x);

// Select Data（查询数据）
this.Operator.Select1st<TEntity>(" and Key001=101 and Key002-'Test PK'");

4)Create\Drop Table From Entity（由实体类创建\删除数据库的数据表）

using JCoder.Db4Net;
using JCoder.Db4Net.ORM;

// Test Entity Class
 [DbTable("t_table_test")]
 public class TestEntity
 {
     [DbPrimaryKey]
     [DbAutoIncrement]
     public int Key001 { get; set; }
     [DbPrimaryKey]
     [DbField(IsUnique =true)]
     public string Key002 { get; set; }
     [DbIgnore]
     public string Key003 { get; set; }

     [DbIndex]
     [DbField(AllowNull = false, Default = "", Description = "Test Comment")]
     public string C001 { get; set; }
     [DbIndex("idx01")]
     public string C002 { get; set; }
     [DbIndex("idx01")]
     public string C003 { get; set; }

     [DbIgnore]
     public int C004 { get; set; }
     [DbField(AllowNull = false, Default = "0", Description = "Test Comment2")]
     public int C005 { get; set; }
     [DbNumberFieldExt(Precision = 11, Scale = 2)]
     public double C006 { get; set; }

     [DbField(AllowNull = false, Default = "", Description = "Test Comment2")]
     public string C007 { get; set; }
     public string C008 { get; set; }
     [DbTimeFieldExt(UpdateTimeOnCreate = true, UpdateTimeOnUpdate = true)]
     public DateTime C009 { get; set; }
 }

IDbOperator _operator = new MsSqlFactoryOperator()
{
    ConnectionString = "Server=127.0.0.1;Database=test;Uid = user; Pwd=testpassword;"
};

this.Operator.CreateTable<TestEntity>();
this.Operator.DropTable<TestEntity>();
   

---

3.5 Orm工具类使用

1)转换首条数据为实体对象(支持DbDataReader、DataTable)

using JCoder.Db4Net.ORM;

// data source
var _table = new DataTable();
// Property only.
var _result = JCoder.Db4Net.ORM.Orm.ToObject1st<T>(_table);
var _result = _table.ToObject1st<T>();
// Attributes first
var _result = JCoder.Db4Net.ORM.Orm.ToEntity1st<T>(_table);
var _result = _table.ToEntity1st<T>();

2)将数据转换为实体对象(支持DataRow、IDictionary<string, string>、IDictionary<string, object>))

using JCoder.Db4Net.ORM;

// data source
var _dict = new Dictionary<string, string>();   
// Attributes first
var _result = JCoder.Db4Net.ORM.Orm.ToEntity<T>(_dict);  
var _result = _dict.ToEntity<T>();     
// Property only.
var _result = JCoder.Db4Net.ORM.Orm.ToObject<T>(_dict);
var _result = _dict.ToObject<T>();

3)将数据源转换为实体对象列表(支持DbDataReader、DataTable)

using JCoder.Db4Net.ORM;

// data source
var _table = new DataTable();   
// Attributes first
var _result = JCoder.Db4Net.ORM.Orm.ToEntities<T>(_table);
var _result = _table.ToEntities<T>();   
// Property only.
var _result = JCoder.Db4Net.ORM.Orm.ToObjects<T>(_table);
var _result = _table.ToObjects<T>();

4)将数据源转换为实体对象字典(支持DbDataReader、DataTable)

using JCoder.Db4Net.ORM;

// data source
var _table = new DataTable();
_table.Columns.Add(new DataColumn("ID", typeof(string)));

// Property only.
var _result = JCoder.Db4Net.ORM.Orm.ToObjectDict<T>(_table, "ID");
var _result = _table.ToObjectDict<T>("ID");
// Attributes first
var _result = JCoder.Db4Net.ORM.Orm.ToEntityDict<T>(_table, "ID");
var _result = _table.ToEntityDict<T>("ID");

5)将数据填充到已有的实体对象里(支持DbDataReader、DataRow、IDictionary<string, string>、IDictionary<string, object>)

using JCoder.Db4Net.ORM;

var _target = new T();

// data source
var _source = new DbDataReader();   
// Property only.
var _result = JCoder.Db4Net.ORM.Orm.FillInObject<T>(_source, _target);
var _result = _source.FillInObject<T>(_target);
// Attributes first
var _result = JCoder.Db4Net.ORM.Orm.FillInEntity<T>(_source, _target);
var _result = _source.FillInEntity<T>(_target);

6)将实体对象转换为DataTable

using JCoder.Db4Net.ORM;

var _list = new List<T>();
var t = new T();

// Property only.
// 实体对象转换为DataTable
DataTable _table = JCoder.Db4Net.ORM.Orm.ObjectToDataTable(t);
DataTable _table = t.ObjectToDataTable();
// 实体对象列表转换为DataTable
DataTable _table = JCoder.Db4Net.ORM.Orm.ObjectsToDataTable(_list);
DataTable _table = _list.ObjectsToDataTable();

// Attributes first
// 实体对象转换为DataTable
DataTable _table = JCoder.Db4Net.ORM.Orm.EntityToDataTable(t);
DataTable _table = t.EntityToDataTable();
// 实体对象列表转换为DataTable
DataTable _table = JCoder.Db4Net.ORM.Orm.EntitiesToDataTable(_list);
DataTable _table = _list.EntitiesToDataTable();

7)将List转换为DataTable

using JCoder.Db4Net.ORM;

// 将List转换为DataTable（使用特性进行排序，自定义名称等）
public class BoTest
{
     [DbSubField("Width", "S001-Width", Sort = 2120)]//获取Size对象里的Width属性值，并显示为"S001-Width"
     [DbSubField("Height", "S001-Height", Sort = 2121)]//获取Size对象里的Height属性值，并显示为"S001-Height"
     public Size S001 { get; set; }
     public string Key { get; set; }
     [DbEnumName]//枚举显示为文本
     public AttributeTargets AT { get; set; }
     public AttributeTargets AT2 { get; set; }
     [DbSort(100)]
     public string P100 { get; set; }
     [DbSort(111)]//设置排序值（从小到大依次排序）
     public string P111 { get; set; }
     public DateTime CreateTime { get; set; }
     [DbIgnoreConvertion]//转换时忽略
     public int Z001 { get; set; }
}

 var _list = new List<BoTest>();
 for (int i = 0; i < 100; i++)
 {
     _list.Add(new()
     {
         S001 = new(i * 100, i * 1000),
         Key = $"Key_{i}",
         P100 = $"P100_{i}",
         P111 = $"P111_{i}",
         CreateTime = DateTime.Now,
         Z001 = i,
         AT = AttributeTargets.Interface,
         AT2 = AttributeTargets.Delegate,
     });
 }
 var _table = JCoder.Db4Net.ORM.Orm.EntitiesToDataTable(_list);

8)将实体对象转换为Dictionary<string,string>

using JCoder.Db4Net.ORM;

var t = new T();

// Property only.
// 实体对象转换为Dictionary<string,string>
Dictionary<string, string> _dict = JCoder.Db4Net.ORM.Orm.ObjectToDict(t);
Dictionary<string, string> _dict = t.ObjectToDict();

// Attributes first
// 实体对象转换为Dictionary<string,string>
Dictionary<string, string> _dict = JCoder.Db4Net.ORM.Orm.EntityToDict(t);
Dictionary<string, string> _dict = t.EntityToDict();