DataTables.API
0.9.13
See the version list below for details.
dotnet add package DataTables.API --version 0.9.13
NuGet\Install-Package DataTables.API -Version 0.9.13
<PackageReference Include="DataTables.API" Version="0.9.13" />
paket add DataTables.API --version 0.9.13
#r "nuget: DataTables.API, 0.9.13"
// Install DataTables.API as a Cake Addin #addin nuget:?package=DataTables.API&version=0.9.13 // Install DataTables.API as a Cake Tool #tool nuget:?package=DataTables.API&version=0.9.13
DataTables
适用于.NET Core的服务端与Unity客户端的数据表解决方案。
Table of Contents
- Concept
- DataTable configuration
- 表格型(Table)定义格式:
- 矩阵型(Matrix)定义格式:
- Getting Started(.NET Core)
- Getting Started(Unity)
- UPM Package
- Optimization
- Code Generator
- License
Concept
- 支持常见的数据表格式, 如Excel 2007-365(*.xlsx), CSV等。
- 支持数据表的并行导出, 通过使用并行导出,大幅提高数据表的导出速度。
- 支持表格型与矩阵形的数据配置, 支持常见的数据表配置以及二维矩阵表配置。
- 导出数据定义代码文件, 通过数据表中定义的代码格式自动生成对应的数据格式代码文件,并提供方便的API接口,方便在终端环境内读取数据文件。
- 导出数据内容二进制文件, 通过紧凑组织的二进制文件,加快读取性能以及缩减配置文件体积大小。
DataTable configuration
标签页(sheet)定义格式:
- 标签页名称以
#
开头将不会导出;
表格型(Table)定义格式:
- 第一行:表头格式定义行,使用
DTGen
开头,主要定义表级别的一些配置 - 第二行:列名称定义行,支持列注释、标签过滤等功能
- 第三行:字段名称定义行
- 第四行:字段类型定义行
表头格式定义行
以,
分隔的参数定义,大小写不敏感,支持以下功能:
- DTGen: 标识该Sheet支持导出(实际可有可无,不强制要求),默认是
DTGen=Table
; - Title: 该Sheet的中文名称,将出现在类定义的注释栏里;
- Class: 该Sheet的类名称,同时正确的格式才会导出该Sheet;
- Child: 支持按Sheet进行分表,即同一个Class的若存在SubTitle定义,将会导出成多个数据文件,加载时单次仅仅加载一个文件;
- EnableTagsFilter: 启用对各列按标签进行导出,输入标签由导出工具运行时提供;
- 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 two kinds of code-generator. MSBuild Task
, .NET Core Global/Local Tools
.
MSBuild Task(DataTables.MSBuild.Tasks
) is recommended way to use in .NET Core csproj.
<DataTablesGenerator
UsingNamespace="string:required"
InputDirectory="string:required"
CodeOutputDirectory="string:required"
DataOutputDirectory="string:required"
PrefixClassName="string:optional, default= "
FilterColumnTags="string:optional, default= "
ForceOverwrite="bool:optional, default=false"
/>
.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
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)
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 | 84 | 7/24/2024 |
0.11.2 | 161 | 5/8/2024 |
0.11.1 | 100 | 5/7/2024 |
0.10.10 | 118 | 5/7/2024 |
0.10.9 | 110 | 5/6/2024 |
0.10.8 | 110 | 5/6/2024 |
0.10.6 | 323 | 11/3/2023 |
0.10.5 | 155 | 11/1/2023 |
0.10.4 | 160 | 10/26/2023 |
0.10.3 | 177 | 10/11/2023 |
0.10.1 | 165 | 9/22/2023 |
0.9.16 | 184 | 8/31/2023 |
0.9.15 | 166 | 8/30/2023 |
0.9.13 | 209 | 7/26/2023 |
0.9.12 | 181 | 7/26/2023 |
0.9.11 | 196 | 7/25/2023 |
0.9.10 | 196 | 7/25/2023 |
0.9.9 | 181 | 7/25/2023 |
0.9.8 | 181 | 7/25/2023 |
0.9.7 | 197 | 7/25/2023 |
0.9.6 | 189 | 7/25/2023 |
0.9.5 | 194 | 7/19/2023 |
0.9.4 | 199 | 7/7/2023 |
0.9.3 | 208 | 6/26/2023 |
0.9.2 | 204 | 6/26/2023 |
0.9.1 | 220 | 6/25/2023 |
0.9.0 | 204 | 6/20/2023 |
0.8.19 | 204 | 6/7/2023 |
0.8.18 | 202 | 6/7/2023 |
0.8.15 | 210 | 6/6/2023 |
0.8.14 | 209 | 6/6/2023 |
0.8.13 | 198 | 6/6/2023 |
0.8.12 | 209 | 6/6/2023 |
0.8.4 | 210 | 5/30/2023 |
0.8.3 | 190 | 5/29/2023 |
0.8.2 | 214 | 5/28/2023 |
0.8.1 | 211 | 5/27/2023 |
0.8.0 | 193 | 5/26/2023 |
0.7.3 | 221 | 5/12/2023 |
0.7.2 | 261 | 4/6/2023 |
0.7.0 | 270 | 3/28/2023 |
0.6.6 | 268 | 3/28/2023 |
0.6.3 | 275 | 3/27/2023 |
0.6.0 | 287 | 3/25/2023 |
0.5.9 | 300 | 3/24/2023 |
0.5.8 | 285 | 3/24/2023 |
0.5.7 | 291 | 3/24/2023 |
0.5.6 | 288 | 3/24/2023 |
0.5.5 | 299 | 3/23/2023 |
0.5.4 | 286 | 3/23/2023 |
0.5.3 | 283 | 3/23/2023 |
0.5.2 | 282 | 3/22/2023 |
0.5.1 | 281 | 3/22/2023 |
0.4.8 | 306 | 3/21/2023 |
0.4.7 | 334 | 2/6/2023 |
0.4.6 | 332 | 2/3/2023 |
0.4.5 | 355 | 1/29/2023 |
0.4.4 | 343 | 1/29/2023 |
0.4.0 | 357 | 1/29/2023 |
0.3.0 | 388 | 1/11/2023 |
0.2.3 | 357 | 1/29/2023 |
0.2.2 | 365 | 12/18/2022 |
0.2.0 | 372 | 12/18/2022 |
0.1.7 | 383 | 12/18/2022 |
0.1.6 | 362 | 12/18/2022 |
0.1.4 | 375 | 12/17/2022 |
0.1.1 | 368 | 12/17/2022 |
0.1.0 | 355 | 12/17/2022 |