DataTables.API 0.8.18

There is a newer version of this package available.
See the version list below for details.
dotnet add package DataTables.API --version 0.8.18                
NuGet\Install-Package DataTables.API -Version 0.8.18                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="DataTables.API" Version="0.8.18" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DataTables.API --version 0.8.18                
#r "nuget: DataTables.API, 0.8.18"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install DataTables.API as a Cake Addin
#addin nuget:?package=DataTables.API&version=0.8.18

// Install DataTables.API as a Cake Tool
#tool nuget:?package=DataTables.API&version=0.8.18                

GitHub Actions Releases

DataTables

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

Table of Contents

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.

ExcelSample

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.

ExcelSample

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.

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • 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.12.17 81 16 days ago
0.12.16 99 25 days ago
0.12.15 82 a month ago
0.12.14 91 a month ago
0.12.13 105 a month ago
0.11.3 103 5 months ago
0.11.2 181 8 months ago
0.11.1 113 8 months ago
0.10.10 126 8 months ago
0.10.9 120 8 months ago
0.10.8 120 8 months ago
0.10.6 334 11/3/2023
0.10.5 168 11/1/2023
0.10.4 169 10/26/2023
0.10.3 184 10/11/2023
0.10.1 172 9/22/2023
0.9.16 191 8/31/2023
0.9.15 173 8/30/2023
0.9.13 215 7/26/2023
0.9.12 189 7/26/2023
0.9.11 202 7/25/2023
0.9.10 204 7/25/2023
0.9.9 188 7/25/2023
0.9.8 190 7/25/2023
0.9.7 205 7/25/2023
0.9.6 196 7/25/2023
0.9.5 207 7/19/2023
0.9.4 205 7/7/2023
0.9.3 214 6/26/2023
0.9.2 210 6/26/2023
0.9.1 226 6/25/2023
0.9.0 212 6/20/2023
0.8.19 215 6/7/2023
0.8.18 208 6/7/2023
0.8.15 217 6/6/2023
0.8.14 216 6/6/2023
0.8.13 206 6/6/2023
0.8.12 217 6/6/2023
0.8.4 216 5/30/2023
0.8.3 196 5/29/2023
0.8.2 222 5/28/2023
0.8.1 218 5/27/2023
0.8.0 200 5/26/2023
0.7.3 233 5/12/2023
0.7.2 267 4/6/2023
0.7.0 282 3/28/2023
0.6.6 275 3/28/2023
0.6.3 282 3/27/2023
0.6.0 294 3/25/2023
0.5.9 306 3/24/2023
0.5.8 292 3/24/2023
0.5.7 297 3/24/2023
0.5.6 294 3/24/2023
0.5.5 306 3/23/2023
0.5.4 291 3/23/2023
0.5.3 290 3/23/2023
0.5.2 288 3/22/2023
0.5.1 289 3/22/2023
0.4.8 313 3/21/2023
0.4.7 340 2/6/2023
0.4.6 340 2/3/2023
0.4.5 362 1/29/2023
0.4.4 349 1/29/2023
0.4.0 364 1/29/2023
0.3.0 399 1/11/2023
0.2.3 366 1/29/2023
0.2.2 372 12/18/2022
0.2.0 378 12/18/2022
0.1.7 390 12/18/2022
0.1.6 369 12/18/2022
0.1.4 382 12/17/2022
0.1.1 382 12/17/2022
0.1.0 362 12/17/2022