DataTables.API
0.10.5
See the version list below for details.
dotnet add package DataTables.API --version 0.10.5
NuGet\Install-Package DataTables.API -Version 0.10.5
<PackageReference Include="DataTables.API" Version="0.10.5" />
paket add DataTables.API --version 0.10.5
#r "nuget: DataTables.API, 0.10.5"
// Install DataTables.API as a Cake Addin #addin nuget:?package=DataTables.API&version=0.10.5 // Install DataTables.API as a Cake Tool #tool nuget:?package=DataTables.API&version=0.10.5
DataTables
适用于.NET Core的服务端与Unity客户端的数据表解决方案。
Table of Contents
Concept
- 支持常见的数据表格式, 如Excel 2007-365(*.xlsx), CSV等。
- 支持数据表的并行导出, 通过使用并行导出,大幅提高数据表的导出速度。
- 支持表格型与矩阵形的数据配置, 支持常见的数据表配置以及二维矩阵表配置。
- 导出数据定义代码文件, 通过数据表中定义的代码格式自动生成对应的数据格式代码文件,并提供方便的API接口,方便在终端环境内读取数据文件。
- 导出数据内容二进制文件, 通过紧凑组织的二进制文件,加快读取性能以及缩减配置文件体积大小。
数据表格式定义
标签页(sheet)定义格式:
- 标签页名称以
#
开头将不会导出;
表格型(Table)定义格式:
- 第一行:表头格式定义行,使用
DTGen
开头,主要定义表级别的一些配置 - 第二行:列名称定义行,支持列注释、标签过滤等功能
- 第三行:字段名称定义行
- 第四行:字段类型定义行
表头格式定义行
以,
分隔的参数定义,大小写不敏感,支持以下功能:
- DTGen: 标识该Sheet支持导出(实际可有可无,不强制要求),默认是
DTGen=Table
; - Title: 该Sheet的中文名称,将出现在类定义的注释栏里;
- Class: 该Sheet的类名称,同时正确的格式才会导出该Sheet;
- Child: 支持按Sheet进行分表,即同一个Class的若存在SubTitle定义,将会导出成多个数据文件,加载时单次仅仅加载一个文件;
- DisableTagsFilter: 禁用对各列按标签进行导出,输入标签由导出工具运行时提供;
- Index: 对指定列进行索引,导出后将提供快捷接口进行查询,查询结果为单个记录;支持同时配置多个Index;支持同时配置多个列,以
&
拼接; - Group: 对指定列进行分组,导出后将提供快捷接口进行查询,查询结果为多个记录;支持同时配置多个Group;支持同时配置多个列,以
&
拼接;
列名称定义行
功能支持:
- 支持在列字段文本以
#
字符开头,代表该列注释,不再参与后续的导出; - 支持在列字段文本以
@ + 大写英文字母
结尾,代表该列支持按标签导出,一个英文字母代表一个标签,具体导出哪些标签由命令行运行时指定;
字段名称定义行
由英文字母数字与下划线组成,同时不能以数字开头;大小写敏感;
字段类型定义行
支持以下字段定义:
short
,int
,long
,ushort
,uint
,ulong
float
,double
bool
DateTime
Array
: StartWiths Array string, like Array<int>, Array<string>Enum
: StartWiths Enum string, like Enum<ColorT>Dictionary
: StartWiths Map string, like Map<int, int>, Map<int, string>JSON
: 支持将单元格文本转化为JSON对象Custom
: 支持自定义类的导出, 自定义类必须拥有带一个字符串形参的构造函数
矩阵型(Matrix)定义格式:
- 第一行:表头格式定义行,使用
DTGen=Matrix
开头,主要定义表级别的一些配置 - 第一列:X轴值内容,剔除头两个单元格;
- 第二行:Y轴值内容,剔除头一个单元格;
表头格式定义行
以,
分隔的参数定义,大小写不敏感,支持以下功能:
- DTGen: 标识该Sheet支持导出, 以
DTGen=Matrix
识别; - Title: 该Sheet的中文名称,将出现在类定义的注释栏里;
- Class: 该Sheet的类名称,同时正确的格式才会导出该Sheet;
- Matrix: 定义X轴、Y轴以及单元格的值类型,如
Matrix=<X轴值类型>&<Y轴值类型>&<单元格值类型>
;
Getting Started(.NET Core)
DataTables uses C# to C# code-generator. Runtime library API is the same but how to code-generate has different way between .NET Core and Unity. This sample is for .NET Core(for Unity is in below sections).
Install the core library(Runtime and Annotations).
PM> Install-Package DataTables
Prepare the example excel table definition like following.
Edit the .csproj
, add DataTables.MSBuild.Tasks and add configuration like following.
<ItemGroup>
<PackageReference Include="DataTables.API" Version="0.8.4" />
<PackageReference Include="DataTables.MSBuild.Tasks" Version="0.8.4" PrivateAssets="All" />
</ItemGroup>
<Target Name="DataTablesGen" BeforeTargets="BeforeBuild">
<DataTablesGenerator UsingNamespace="$(ProjectName)" InputDirectory="$(ProjectDir)" CodeOutputDirectory="$(ProjectDir)Tables" DataOutputDirectory="$(ProjectDir)Datas" PrefixClassName="DR" />
</Target>
After the build, generated files(DataTableManagerExtension.cs
and Tables/DR***.cs
) in CodeOutputDirectory, generated data files(Datas/***.bin
) in DataOutputDirectory.
Finally, you can regsiter and query by these files.
// 预加载指定数据表,然后,进行查询
var manager = new DataTableManager();
// 使用默认的数据表数据文件加载器
manager.SetDataTableHelper(new DefaultDataTableHelper("<Data Files Dir>"));
// 预加载DTScene数据表
manager.CreateDataTable<DTScene>(null);
// 由于默认数据表加载器是同步调用的方式,若可在Preload之后直接查询数据,否则要放在callback内
var drScene1 = manager.GetDataTable<DRScene>().GetDataRow(x => x.Id == 2000);
var drScene2 = manager.GetDataTable<DRScene>().GetDataRowById(2000);
// -----------------------
// 预加载全部数据表,然后,查询任意数据表的内容示例:
var manager = new DataTableManager();
// 使用默认的数据表数据文件加载器
manager.SetDataTableHelper(new DefaultDataTableHelper("<Data Files Dir>"));
// 预加载所有的数据表
manager.Preload(() => Console.WriteLine("数据表全部加载完毕"));
// 由于默认数据表加载器是同步调用的方式,若可在Preload之后直接查询数据,否则要放在callback内
var drScene1 = manager.GetDataTable<DRScene>().GetDataRow(x => x.Id == 2000);
var drScene2 = manager.GetDataTable<DRScene>().GetDataRowById(2000);
You can invoke all indexed query by IntelliSense.
Getting Started(Unity)
Check the releases page, download DataTables.Unity.unitypackage
(runtime) and DataTables.Generator.zip
(cli code-generator).
Prepare the example table definition like following.
use the DataTables code generator by commandline. Commandline tool support platforms are win-x64
, osx-x64
and linux-x64
.
Usage: DataTables.Generator [options...]
Options:
-i, -inputDirectory <String> Input file directory(search recursive). (Required)
-co, -codeOutputDirectory <String> Code Output file directory. (Required)
-do, -dataOutputDirectory <String> Data Output file directory. (Required)
-n, -usingNamespace <String> Namespace of generated files. (Required)
-p, -prefixClassName <String> Prefix of class names. (Default: )
-t, -filterColumnTags <String> Tags of filter columns. (Default: )
-f, -forceOverwrite <Boolean> Overwrite generated files if the content is unchanged. (Default: false)
DataTables.Generator.exe -i "C:\UnitySample" -co "C:\UnitySample\Generated" -do "C:\UnitySample\DataTable" -n "UnitySample" -p "DR"
The rest is the same as .NET Core version.
// 预加载指定数据表,然后,进行查询
var manager = new DataTableManager();
// 使用默认的数据表数据文件加载器
manager.SetDataTableHelper(new DefaultDataTableHelper("<Data Files Dir>"));
// 预加载DTScene数据表
manager.CreateDataTable<DTScene>(null);
// 由于默认数据表加载器是同步调用的方式,若可在Preload之后直接查询数据,否则要放在callback内
var drScene1 = manager.GetDataTable<DRScene>().GetDataRow(x => x.Id == 2000);
var drScene2 = manager.GetDataTable<DRScene>().GetDataRowById(2000);
// -----------------------
// 预加载全部数据表,然后,查询任意数据表的内容示例:
var manager = new DataTableManager();
// 使用默认的数据表数据文件加载器
manager.SetDataTableHelper(new DefaultDataTableHelper("<Data Files Dir>"));
// 预加载所有的数据表
manager.Preload(() => Console.WriteLine("数据表全部加载完毕"));
// 由于默认数据表加载器是同步调用的方式,若可在Preload之后直接查询数据,否则要放在callback内
var drScene1 = manager.GetDataTable<DRScene>().GetDataRow(x => x.Id == 2000);
var drScene2 = manager.GetDataTable<DRScene>().GetDataRowById(2000);
You can invoke all indexed query by IntelliSense.
UPM Package
Install via git URL
Requires a version of unity that supports path query parameter for git packages (Unity >= 2019.3.4f1, Unity >= 2020.1a21). You can add https://github.com/PhonixGame/DataTables.git?path=src/DataTables.Unity/Assets/Scripts/DataTables
to Package Manager
or add "game.phonix.datatables": "https://github.com/PhonixGame/DataTables.git?path=src/DataTables.Unity/Assets/Scripts/DataTables"
to Packages/manifest.json
.
If you want to set a target version, UniTask uses the *.*.*
release tag so you can specify a version like #0.9.5
. For example https://github.com/PhonixGame/DataTables.git?path=src/DataTables.Unity/Assets/Scripts/DataTables#0.9.5
.
Install via OpenUPM
The package is available on the openupm registry. It's recommended to install it via openupm-cli.
openupm add game.phonix.datatables
Optimization
在提供的API中有一些宏定义,可用于调整API接口相关:
DT_CHECK_NOT_FOUND
: 在Unity中定义该宏,可在调用查询相关接口时,检测到目标条目不存在时,会输出警告级别日志。
Code Generator
DataTables has one kinds of code-generator. .NET Core Global/Local Tools
.
.NET Core Global/Local Tools
can install from NuGet(DataTables.Generator
), you need to install .NET runtime. Here is the sample command of install global tool.
dotnet tool install --global DataTables.Generator
Options:
-i, -inputdirectories <String[]> Input file directory(search recursive). (Required)
-co, -codeoutputdir <String> Code output file directory. (Required)
-do, -dataoutputdir <String> Data output file directory. (Required)
-ins, -importnamespaces <String> Import namespaces of generated files, split with char '&' for multiple namespaces. (Default: )
-n, -usingnamespace <String> Namespace of generated files. (Default: )
-p, -prefixclassname <String> Prefix of class names. (Default: )
-t, -filtercolumntags <String> Tags of filter columns. (Default: )
-f, -forceoverwrite Overwrite generated files if the content is unchanged. (Optional)
After install, you can call by dotnet DataTables.Generator
command. This is useful to use in CI. Here is the sample of CircleCI config.
version: 2.1
executors:
dotnet:
docker:
- image: mcr.microsoft.com/dotnet/core/sdk:2.2
environment:
DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
NUGET_XMLDOC_MODE: skip
jobs:
gen-datatables:
executor: dotnet
steps:
- checkout
- run: dotnet tool install --global DataTables.Generator
- run: dotnet DataTables.Generator -i "inputDir" -co "client\Assets\Scripts\Game\DataTables" -do "client\Assets\AssetBundles\DataTables" -n Demo.DataTales
/* git push or store artifacts or etc...... */
License
This library is under the MIT License.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net7.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.11.3 | 83 | 7/24/2024 |
0.11.2 | 157 | 5/8/2024 |
0.11.1 | 99 | 5/7/2024 |
0.10.10 | 117 | 5/7/2024 |
0.10.9 | 109 | 5/6/2024 |
0.10.8 | 109 | 5/6/2024 |
0.10.6 | 322 | 11/3/2023 |
0.10.5 | 154 | 11/1/2023 |
0.10.4 | 159 | 10/26/2023 |
0.10.3 | 176 | 10/11/2023 |
0.10.1 | 164 | 9/22/2023 |
0.9.16 | 183 | 8/31/2023 |
0.9.15 | 165 | 8/30/2023 |
0.9.13 | 207 | 7/26/2023 |
0.9.12 | 180 | 7/26/2023 |
0.9.11 | 195 | 7/25/2023 |
0.9.10 | 193 | 7/25/2023 |
0.9.9 | 180 | 7/25/2023 |
0.9.8 | 180 | 7/25/2023 |
0.9.7 | 196 | 7/25/2023 |
0.9.6 | 188 | 7/25/2023 |
0.9.5 | 193 | 7/19/2023 |
0.9.4 | 198 | 7/7/2023 |
0.9.3 | 205 | 6/26/2023 |
0.9.2 | 203 | 6/26/2023 |
0.9.1 | 219 | 6/25/2023 |
0.9.0 | 203 | 6/20/2023 |
0.8.19 | 203 | 6/7/2023 |
0.8.18 | 199 | 6/7/2023 |
0.8.15 | 209 | 6/6/2023 |
0.8.14 | 208 | 6/6/2023 |
0.8.13 | 197 | 6/6/2023 |
0.8.12 | 208 | 6/6/2023 |
0.8.4 | 209 | 5/30/2023 |
0.8.3 | 189 | 5/29/2023 |
0.8.2 | 213 | 5/28/2023 |
0.8.1 | 210 | 5/27/2023 |
0.8.0 | 192 | 5/26/2023 |
0.7.3 | 220 | 5/12/2023 |
0.7.2 | 260 | 4/6/2023 |
0.7.0 | 269 | 3/28/2023 |
0.6.6 | 267 | 3/28/2023 |
0.6.3 | 274 | 3/27/2023 |
0.6.0 | 286 | 3/25/2023 |
0.5.9 | 299 | 3/24/2023 |
0.5.8 | 284 | 3/24/2023 |
0.5.7 | 290 | 3/24/2023 |
0.5.6 | 287 | 3/24/2023 |
0.5.5 | 296 | 3/23/2023 |
0.5.4 | 285 | 3/23/2023 |
0.5.3 | 282 | 3/23/2023 |
0.5.2 | 281 | 3/22/2023 |
0.5.1 | 280 | 3/22/2023 |
0.4.8 | 305 | 3/21/2023 |
0.4.7 | 331 | 2/6/2023 |
0.4.6 | 331 | 2/3/2023 |
0.4.5 | 354 | 1/29/2023 |
0.4.4 | 342 | 1/29/2023 |
0.4.0 | 356 | 1/29/2023 |
0.3.0 | 387 | 1/11/2023 |
0.2.3 | 356 | 1/29/2023 |
0.2.2 | 364 | 12/18/2022 |
0.2.0 | 371 | 12/18/2022 |
0.1.7 | 382 | 12/18/2022 |
0.1.6 | 361 | 12/18/2022 |
0.1.4 | 372 | 12/17/2022 |
0.1.1 | 367 | 12/17/2022 |
0.1.0 | 354 | 12/17/2022 |