DataTables.API 0.9.1

DataTables

专注于Excel配置表的导出：目前支持.NET Core的服务端与Unity客户端。

Table of Contents

• Concept
• Getting Started(.NET Core)
• Getting Started(Unity)
• DataTable configuration
• 表头格式定义行
• 列名称定义行
• 字段名称定义行
• 字段类型定义行
• Optimization
• Code Generator
• License

Concept

• Support Many Input File, Support Excel 2007-365(*.xlsx) as input file.
• Memory Efficient, Only use underlying data memory and do aggressively string interning.
• Performance, Similar as dictionary lookup.
• TypeSafe, 100% Type safe by pre code-generation.
• Fast load speed, DataTables Convert Excel files to binary files, so packed files is smaller and load speed is blazing fast.

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.

DataTable configuration

标签页定义格式：

• 标签页名称以#开头将不会导出；

配置表定义格式：

• 第一行：表头格式定义行，使用DataTabeGenerator开头，主要定义表级别的一些配置
• 第二行：列名称定义行，支持列注释、标签过滤等功能
• 第三行：字段名称定义行
• 第四行：字段类型定义行

表头格式定义行

以,分隔的参数定义，大小写不敏感，支持以下功能：

• DataTabeGenerator: 标识该Sheet支持导出（实际可有可无，不强制要求）；
• Title: 该Sheet的中文名称，将出现在类定义的注释栏里；
• Class: 该Sheet的类名称，同时正确的格式才会导出该Sheet；
• Split: 支持按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: 支持自定义类的导出, 自定义类必须拥有带一个字符串形参的构造函数

Optimization

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.