[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 |

[TOC]

一.架构说明

| 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();