# TExcel **Repository Path**: ThingsGateway/TExcel ## Basic Information - **Project Name**: TExcel - **Description**: TExcel 是一个轻量级、高性能、低内存占用的 Excel 读写库，支持 AOT 编译。提供流式操作，支持导出实体列表、多 Sheet、字典，以及导入 Sheet、获取 Sheet 列表、逐行读取等功能。无需任何第三方依赖。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 6 - **Forks**: 0 - **Created**: 2026-04-12 - **Last Updated**: 2026-05-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README 

TExcel - 高性能 .NET Excel 读写库

[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) [![NuGet](https://img.shields.io/nuget/v/TExcel.svg)](https://www.nuget.org/packages/TExcel) [![.NET](https://img.shields.io/badge/.NET-8.0%20%7C%2010.0-blue.svg)](https://dotnet.microsoft.com/) **轻量级、高性能、低内存占用的 Excel 读写库，支持 AOT 编译** **ThingsGateway** 生态系统中的 **Excel** 组件
--- ## 中文 ### 项目简介 TExcel 是一个为 .NET 平台设计的轻量级、高性能 Excel 读写库。它提供了简洁流畅的 API，支持流式操作，无需任何第三方依赖，并针对高性能场景进行了深度优化，完美支持 AOT 编译。 ### 核心特性 - **AOT 支持**：完美支持 AOT 编译，适用于原生应用场景 - **零依赖**：无需任何第三方 Excel 库依赖 - **高性能**：流式读写，低内存占用 - **多格式支持**：支持实体列表、字典、多列数据等多种数据格式 - **多 Sheet 支持**：支持读取和写入多个 Sheet - **异步支持**：完整的同步/异步 API ### 性能测试 TExcel 与 MiniExcel 的性能对比测试结果： ``` BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.8246/25H2/2025Update/HudsonValley2) Intel Core Ultra 9 285H 2.90GHz, 1 CPU, 16 logical and 16 physical cores .NET SDK 10.0.201 [Host] : .NET 8.0.25 (8.0.25, 8.0.2526.11203), X64 RyuJIT x86-64-v3 Job-YFEFPZ : .NET 8.0.25 (8.0.25, 8.0.2526.11203), X64 RyuJIT x86-64-v3 ShortRun : .NET 8.0.25 (8.0.25, 8.0.2526.11203), X64 RyuJIT x86-64-v3 WarmupCount=3 ``` | Method | Job | IterationCount | LaunchCount | Mean | Error | StdDev | Min | Max | Gen0 | Gen1 | Gen2 | Allocated | |------------------------------------------------------- |----------- |--------------- |------------ |-------------:|--------------:|-------------:|-------------:|-------------:|-----------:|----------:|---------:|-------------:| | 'TExcel - Write 100 rows' | Job-YFEFPZ | 10 | Default | 971.2 μs | 30.72 μs | 20.32 μs | 945.8 μs | 1,000.9 μs | 91.7969 | 84.9609 | 81.0547 | 1794.87 KB | | 'MiniExcel - Write 100 rows' | Job-YFEFPZ | 10 | Default | 3,801.9 μs | 108.07 μs | 71.48 μs | 3,679.4 μs | 3,889.1 μs | 488.2813 | 464.8438 | 460.9375 | 15687.84 KB | | 'TExcel - Write 10,000 rows' | Job-YFEFPZ | 10 | Default | 20,090.7 μs | 252.06 μs | 166.72 μs | 19,844.6 μs | 20,320.1 μs | 500.0000 | 312.5000 | 218.7500 | 6946.49 KB | | 'MiniExcel - Write 10,000 rows' | Job-YFEFPZ | 10 | Default | 33,360.0 μs | 2,214.50 μs | 1,464.76 μs | 31,381.8 μs | 35,491.9 μs | 2687.5000 | 1062.5000 | 968.7500 | 36439.35 KB | | 'TExcel - Write 100,000 rows' | Job-YFEFPZ | 10 | Default | 182,865.7 μs | 6,622.49 μs | 3,463.69 μs | 179,116.0 μs | 189,278.1 μs | 3000.0000 | 1000.0000 | 750.0000 | 41031.66 KB | | 'MiniExcel - Write 100,000 rows' | Job-YFEFPZ | 10 | Default | 237,299.2 μs | 14,094.96 μs | 9,322.95 μs | 216,521.8 μs | 244,466.2 μs | 18333.3333 | 666.6667 | 666.6667 | 232293.94 KB | | 'TExcel - Read 100 rows' | Job-YFEFPZ | 10 | Default | 193.8 μs | 6.92 μs | 4.58 μs | 186.9 μs | 202.4 μs | 11.7188 | 0.9766 | - | 151 KB | | 'MiniExcel - Read 100 rows' | Job-YFEFPZ | 10 | Default | 1,894.0 μs | 550.76 μs | 364.29 μs | 1,600.1 μs | 2,621.3 μs | 58.5938 | 27.3438 | - | 720.82 KB | | 'TExcel - Read 10,000 rows' | Job-YFEFPZ | 10 | Default | 22,787.3 μs | 1,580.78 μs | 1,045.59 μs | 19,837.1 μs | 23,317.1 μs | 687.5000 | 281.2500 | 62.5000 | 8571.34 KB | | 'MiniExcel - Read 10,000 rows' | Job-YFEFPZ | 10 | Default | 52,307.6 μs | 1,629.63 μs | 1,077.90 μs | 50,875.4 μs | 53,518.6 μs | 4400.0000 | 1200.0000 | - | 55438.66 KB | | 'TExcel - Read 100,000 rows' | Job-YFEFPZ | 10 | Default | 238,770.2 μs | 25,584.39 μs | 16,922.49 μs | 191,120.1 μs | 249,130.5 μs | 6000.0000 | 2000.0000 | - | 87858.84 KB | | 'MiniExcel - Read 100,000 rows' | Job-YFEFPZ | 10 | Default | 503,109.0 μs | 6,303.34 μs | 3,751.02 μs | 499,808.6 μs | 509,326.7 μs | 45000.0000 | 8000.0000 | - | 558096.67 KB | | 'TExcel - Read as Dictionary 10,000 rows' | Job-YFEFPZ | 10 | Default | 26,208.3 μs | 705.36 μs | 419.75 μs | 25,558.4 μs | 26,742.0 μs | 968.7500 | 937.5000 | 218.7500 | 10054.47 KB | | 'MiniExcel - Read as Dictionary 10,000 rows' | Job-YFEFPZ | 10 | Default | 63,052.7 μs | 3,268.95 μs | 1,945.30 μs | 60,449.1 μs | 66,596.5 μs | 4500.0000 | 1250.0000 | - | 56573.87 KB | | 'TExcel - Write Dictionary 10,000 rows' | Job-YFEFPZ | 10 | Default | 17,376.3 μs | 1,386.86 μs | 917.32 μs | 16,605.1 μs | 19,035.0 μs | 406.2500 | 312.5000 | 234.3750 | 5773.77 KB | | 'MiniExcel - Write Dictionary 10,000 rows' | Job-YFEFPZ | 10 | Default | 33,335.1 μs | 2,590.43 μs | 1,713.41 μs | 31,595.8 μs | 36,625.5 μs | 2538.4615 | 923.0769 | 923.0769 | 35241.51 KB | | 'TExcel - Streaming Read 100,000 rows (count only)' | Job-YFEFPZ | 10 | Default | 223,261.2 μs | 21,424.81 μs | 14,171.19 μs | 183,013.7 μs | 228,764.7 μs | 6000.0000 | 1000.0000 | - | 85822.9 KB | | 'MiniExcel - Streaming Read 100,000 rows (count only)' | Job-YFEFPZ | 10 | Default | 375,842.3 μs | 20,388.42 μs | 13,485.68 μs | 360,171.5 μs | 391,911.4 μs | 45000.0000 | - | - | 556055.82 KB | | 'TExcel - Write 100 rows' | ShortRun | 3 | 1 | 1,014.1 μs | 883.78 μs | 48.44 μs | 981.8 μs | 1,069.8 μs | 87.8906 | 82.0313 | 78.1250 | 1794.88 KB | | 'MiniExcel - Write 100 rows' | ShortRun | 3 | 1 | 4,467.9 μs | 327.49 μs | 17.95 μs | 4,447.5 μs | 4,481.4 μs | 507.8125 | 484.3750 | 484.3750 | 15705.71 KB | | 'TExcel - Write 10,000 rows' | ShortRun | 3 | 1 | 19,259.6 μs | 2,610.56 μs | 143.09 μs | 19,160.2 μs | 19,423.6 μs | 500.0000 | 312.5000 | 218.7500 | 6946.56 KB | | 'MiniExcel - Write 10,000 rows' | ShortRun | 3 | 1 | 31,256.7 μs | 1,170.84 μs | 64.18 μs | 31,184.2 μs | 31,306.3 μs | 2687.5000 | 1062.5000 | 968.7500 | 36509.27 KB | | 'TExcel - Write 100,000 rows' | ShortRun | 3 | 1 | 187,436.4 μs | 20,152.59 μs | 1,104.63 μs | 186,161.0 μs | 188,083.3 μs | 3000.0000 | 1000.0000 | 750.0000 | 40994.56 KB | | 'MiniExcel - Write 100,000 rows' | ShortRun | 3 | 1 | 241,877.4 μs | 35,593.83 μs | 1,951.02 μs | 239,882.3 μs | 243,781.2 μs | 18333.3333 | 666.6667 | 666.6667 | 232293.77 KB | | 'TExcel - Read 100 rows' | ShortRun | 3 | 1 | 191.2 μs | 111.42 μs | 6.11 μs | 184.1 μs | 195.0 μs | 11.7188 | 0.9766 | - | 151 KB | | 'MiniExcel - Read 100 rows' | ShortRun | 3 | 1 | 2,551.3 μs | 8,995.01 μs | 493.05 μs | 2,019.0 μs | 2,992.4 μs | 58.5938 | 27.3438 | - | 720.83 KB | | 'TExcel - Read 10,000 rows' | ShortRun | 3 | 1 | 22,862.5 μs | 831.35 μs | 45.57 μs | 22,819.1 μs | 22,910.0 μs | 687.5000 | 281.2500 | 62.5000 | 8572.03 KB | | 'MiniExcel - Read 10,000 rows' | ShortRun | 3 | 1 | 52,561.7 μs | 15,407.39 μs | 844.53 μs | 51,586.7 μs | 53,064.6 μs | 4400.0000 | 1200.0000 | - | 55544.43 KB | | 'TExcel - Read 100,000 rows' | ShortRun | 3 | 1 | 208,351.2 μs | 455,226.66 μs | 24,952.51 μs | 190,083.4 μs | 236,781.3 μs | 6000.0000 | 2000.0000 | - | 87873.95 KB | | 'MiniExcel - Read 100,000 rows' | ShortRun | 3 | 1 | 437,025.1 μs | 181,166.13 μs | 9,930.33 μs | 426,880.5 μs | 446,726.3 μs | 45000.0000 | 8000.0000 | - | 558134.32 KB | | 'TExcel - Read as Dictionary 10,000 rows' | ShortRun | 3 | 1 | 26,069.1 μs | 9,933.84 μs | 544.51 μs | 25,626.1 μs | 26,677.0 μs | 968.7500 | 937.5000 | 218.7500 | 10056.21 KB | | 'MiniExcel - Read as Dictionary 10,000 rows' | ShortRun | 3 | 1 | 60,103.5 μs | 10,449.48 μs | 572.77 μs | 59,737.2 μs | 60,763.6 μs | 4500.0000 | 1250.0000 | - | 56483.33 KB | | 'TExcel - Write Dictionary 10,000 rows' | ShortRun | 3 | 1 | 19,684.5 μs | 60,452.62 μs | 3,313.61 μs | 15,869.7 μs | 21,847.4 μs | 375.0000 | 281.2500 | 218.7500 | 5733.06 KB | | 'MiniExcel - Write Dictionary 10,000 rows' | ShortRun | 3 | 1 | 32,546.5 μs | 44,142.91 μs | 2,419.62 μs | 30,728.2 μs | 35,292.7 μs | 2500.0000 | 937.5000 | 937.5000 | 35241.41 KB | | 'TExcel - Streaming Read 100,000 rows (count only)' | ShortRun | 3 | 1 | 202,586.2 μs | 490,380.75 μs | 26,879.42 μs | 180,069.0 μs | 232,344.4 μs | 6000.0000 | 1000.0000 | - | 85795.63 KB | | 'MiniExcel - Streaming Read 100,000 rows (count only)' | ShortRun | 3 | 1 | 477,040.6 μs | 171,858.41 μs | 9,420.14 μs | 466,183.3 μs | 483,041.8 μs | 45000.0000 | - | - | 556047.02 KB | TExcel 在读写速度和内存占用方面均表现优异，内存占用仅为 MiniExcel 的 1/5 到 1/3。 ### 快速开始 #### 安装 NuGet 包 ```bash dotnet add package TExcel ``` #### 写入 Excel **实体列表写入：** ```csharp using TExcel; public class User { public int Id { get; set; } public string Name { get; set; } public int Age { get; set; } } var users = new List { new User { Id = 1, Name = "张三", Age = 25 }, new User { Id = 2, Name = "李四", Age = 30 } }; Excel.SaveAs("output.xlsx", users); ``` **字典列表写入：** ```csharp var data = new List> { new Dictionary { ["Id"] = 1, ["Name"] = "张三" }, new Dictionary { ["Id"] = 2, ["Name"] = "李四" } }; Excel.SaveAs("output.xlsx", data); ``` **多 Sheet 写入：** ```csharp using var writer = Excel.CreateWriter("output.xlsx"); writer.WriteSheet(users, "Users"); writer.WriteSheet(orders, "Orders"); writer.Complete(); ``` #### 读取 Excel **实体列表读取：** ```csharp var users = Excel.Query("input.xlsx").ToList(); ``` **字典列表读取：** ```csharp var data = Excel.QueryAsDictionary("input.xlsx").ToList(); ``` **流式读取（大数据量场景）：** ```csharp foreach (var user in Excel.Query("large_file.xlsx")) { // 逐行处理，低内存占用 } ``` **异步读取：** ```csharp await foreach (var user in Excel.QueryAsync("input.xlsx")) { // 异步逐行处理 } ``` #### 获取 Sheet 信息 ```csharp var sheets = Excel.GetSheets("input.xlsx"); foreach (var sheet in sheets) { Console.WriteLine($"Sheet[{sheet.Index}]: {sheet.Name}"); } ``` ### 列特性配置 使用 `ExcelColumnAttribute` 自定义列名和顺序： ```csharp public class User { [ExcelColumn("用户ID", Order = 0)] public int Id { get; set; } [ExcelColumn("用户名", Order = 1)] public string Name { get; set; } [ExcelColumn("创建时间", Format = "yyyy-MM-dd HH:mm:ss")] public DateTime CreateTime { get; set; } [ExcelColumn(Ignore = true)] public string? Password { get; set; } } ``` ### API 概览 | 方法 | 说明 | |------|------| | `Excel.SaveAs(path, data)` | 保存数据到 Excel 文件 | | `Excel.Query(path)` | 从 Excel 读取实体列表 | | `Excel.QueryAsDictionary(path)` | 从 Excel 读取字典列表 | | `Excel.GetSheets(path)` | 获取所有 Sheet 信息 | | `Excel.CreateWriter(path)` | 创建写入器（支持多 Sheet） | | `Excel.CreateReader(path)` | 创建读取器 | 所有方法均支持异步版本和 Stream 参数。 ### 项目结构 ``` TExcel/ ├── src/TExcel/ │ ├── Core/ │ │ ├── Excel.cs # 静态便捷方法 │ │ ├── ExcelReader.cs # 读取器实现 │ │ ├── ExcelWriter.cs # 写入器实现 │ │ ├── IExcelReader.cs # 读取器接口 │ │ ├── IExcelWriter.cs # 写入器接口 │ │ ├── SheetInfo.cs # Sheet 信息 │ │ └── ExcelColumnAttribute.cs # 列特性 │ └── Internal/ │ ├── CellReferenceHelper.cs │ ├── OpenXmlConstants.cs │ └── SharedStringsTable.cs ├── benchmark/TExcel.Benchmark/ # 性能测试 └── test/TExcel.Test/ # 单元测试 ``` ### 运行性能测试 ```bash cd benchmark/TExcel.Benchmark dotnet run -c Release ``` ### 许可证 [Apache License 2.0](LICENSE) ### 相关链接 - Gitee: https://gitee.com/diego2098/ThingsGateway - GitHub: https://github.com/kimdiego2098/ThingsGateway - 文档: https://thingsgateway.cn/ - QQ群: 605534569