NewLife.XCode是一个有10多年历史的开源数据中间件,由新生命团队(2002~2024)开发完成并维护至今,以下简称XCode。
整个系列教程会大量结合示例代码和运行日志来进行深入分析,蕴含多年开发经验于其中。
XCode代码生成的最佳实践是xcodetool.exe+Model.xml,码神工具仍可生成实体类代码,但缺乏维护可能有兼容问题。熟练开发者可使用dotnettoolinstallxcodetool-g安装工具,并使用全局命令xcode+Model.xml来生成代码。
数据模型文件是XCode数据库开发的中心,曾经流行和支持的DBFirst和EntityFirst,经过10多年优胜劣汰,只剩下ModelFirst。
XCode的数据模型文件就是一个Model.xml,(名字可变),同目录配套xcodetool.exe,用于生成基于xml模型文件的多个实体类文件。
核心用法,编辑模型文件model.xml后,双击运行同目录的xcodetool.exe即可根据model.xml生成多个实体类文件!
如果手头没有model.xml,在空白目录运行xcodetool.exe会自动生成一个例子文件。
该工具也可以在XCode源码中编译XCodeTool发布得到。
xcodetool工具随着XCode发布最新版,可通过dotnettool来安装。新建build.bat批处理文件,写入以下代码:
@echooffxcodeIFERRORLEVEL1(echoxcode命令执行失败,正在安装.NET工具...dotnettoolinstallxcodetool-g--prereleasexcode)双击运行build.bat,相同目录和子目录的*.xml模型文件将会自动生成实体类代码文件。如果找不到xml模型文件,则自动输出Model.xml文件作为模板。
(注:2022年开始,以下build.tt用法已过时,不推荐使用)
XCode的数据模型文件就是一个Model.xml,(名字可变),同目录配套Build.tt,用于在vs里调用XCode生成基于xml模型文件的多个实体类文件。
核心用法,在build.tt文件上点击右键选择“运行自定义工具”,即可根据model.xml生成多个实体类文件!
从nuget安装NewLife.XCode时,可以看到项目下多了一个Model.xml和build.tt/build_netcore.tt
nfx项目安装NewLife.XCode才有,netcore项目可从nfx项目中拷贝这两个文件,或者修改项目为netcore+net45混合项目后再安装引用。
(!!!安装XCode后,编译一次项目,确保输出目录中存在newlife.core.dll和xcode.dll,因为build.tt内需要引用这两个文件,也可以拷贝这两个文件到别处并修改build.tt内部引用)
解压拷贝model.xml和build.tt(netcore项目选build_netcore.tt)到需要放置实体类的目标目录。
*.tt文件本质上就是VisualStudio的T4模版,可以在vs中新建一个,并确保其文件属性中的自定义工具为TextTemplatingFileGenerator。
build.tt和model.xml的文件名都可以随意修改,build.tt默认会自动查找当前目录的第一个xml文件来使用。或者修改build.tt文件内容,强制指定文件名
<#@templatelanguage="C#"hostSpecific="true"debug="true"#><#@assemblyname="netstandard"#><#@assemblyname="$(SolutionDir)\DLL\NewLife.Core.dll"#><#@assemblyname="$(SolutionDir)\DLL\XCode.dll"#><#@importnamespace="System.Diagnostics"#><#@importnamespace="System.IO"#><#@importnamespace="XCode.Code"#><#@outputextension=".log"#><#//设置当前工作目录PathHelper.BasePath=Host.ResolvePath(".");//导入模型文件并生成实体类,模型文件、输出目录、命名空间、连接名、中文文件名、表名字段名大小写//EntityBuilder.Build(StringxmlFile=null,Stringoutput=null,StringnameSpace=null,StringconnName=null,BooleanchineseFileName=true,BooleannameIgnoreCase=null);EntityBuilder.Build();//vartables=DAL.ImportFrom("Company.Project.xml");//EntityBuilder.Build(tables);#>在.NETCore3.1/.NET5.0项目使用XCode的build_netcore.tt模板生成时,可能会报以下错误(未能找到文件):
或者报以下错误(正在编译转换:类型"Object"在未引用的程序集中定义。必须添加对程序集的引用):
这是VisualStudio2019的T4模板存在对.NET5.0程序集的兼容问题,只需要强制指定DLL引用位置即可。
上面文件中指定使用解决方案下DLL子目录的NewLife.Core.dll和XCode.dll,需要首先编译任意引用了XCode的项目,并在输出目录中寻找这两个文件,拷贝到DLL子目录中去。
此外,还可以修改EntityBuilder.Build参数来满足个性化需求。
在.NETCore3.1/.NET5.0项目使用XCode的build.tt模板生成时,会报错:
此时我们可以修改模板
安装后启动,菜单中选择“数据建模工具”,会自动列出本机安装的数据库。
(也可以修改配置文件XCoder.exe.config,加入开发数据库的连接信息)
选择并连接数据库,可以看到该库的所有表信息,此时只需要“导出模型”,即可得到该库的model.xml模型文件。
(码神工具在早期2002~2012是XCode的唯一代码生成方式,现在仍可以使用,但由于缺乏维护可能存在一些兼容问题,推荐使用最新的build.tt+model.xml)
Model.xml正是供我们进行数据建模的参考,同时也是XCode内部Membership的模型文件。
头部属性解释:
Tables中的这些属性对本模型文件所有Table有效,各个Table上也可以指定这些属性,以覆盖全局设置
Table.Name就是生成的实体类类名,如果实际表名不同,可用TableName指定表名。
Column.Name就是生成的实体类属性名,如果实际字段名不同,可用ColumnName指定字段名。
字符串长度Length默认50,不建议小于50,-1表示最大ntext
其它字段不建议设置长度,特别不建议给Double和Decimal设置精度
字段Column只需要DataType指定.Net类型即可,反向工程会根据使用数据库的不同而映射到不同数据库类型。
如果不喜欢XCode推荐的数据库类型,可在Column中通过RawType指定原始数据库类型。
Column支持Type指定枚举类型,建议是带命名空间的全名。例如上面User表中Sex类型的字段就是枚举SexKinds
Indexes内放置该表所有索引。
每一行Index为一组索引,Columns内指定索引所需要的字段(注意先后顺序),Unique指定是否唯一索引。
!!XCode反向工程支持自动创建或删除索引。
可以通过码神工具/建模工具,从数据库中导出数据表对应的模型文件;
也可以编码通过DAL.Export导出模型文件;
魔方的系统管理数据库页面,也可以导出模型文件;
模型文件的Table名将会生成实体类类名,Column字段名将会生成实体类属性名,因此命名规范很重要。
模型文件设计要求开发者有一点数据库基础,至少要能明确表、字段和索引的概念。
然而要求又远比数据库要低得多,因为咱们推崇极致简单的原则。
类型
数据库类型
推荐
备注
Int32
整数
int
强烈
优先
String
字符串
nvarchar(50)
默认变长50
DateTime
datetime
Boolean
布尔型
bit
MySql中建议tinyint替代枚举来实现布尔型
Int64
长整型
long
有可能超过21亿的整数,选长整型
Decimal
十进制
money
慎用
高精度货币型时采用
Double
双精度
double
特别慎用,避免浮点运算导致精度丢失
Int16
short
禁用
由Int32替代
Byte
tinyint
Single
single
由Double替代
为了便于开发,XCode默认优待以下字段:
IP组CreateIP/UpdateIP字段对应IPModule,在Web新增或更新时自动赋值;
用户组CreateUser(ID)/UpdateUser(ID)字段对应UserModule,在Web新增或更新时字段赋值;
一句话:用了这些字段,在Insert时自动给CreateAbc赋值,在Update时自动给UpdateAbc赋值!