简介面向C#开发者的EPPlus操作Excel实例基于Open XML的xlsx格式能读写Excel 2007/2010文件无需安装Office即可实现数据导入导出及图表输出适合桌面应用开发者快速集成电子表格功能。压缩包共40个文件约2.54MB包含EPPlus运行库dll、C#窗体与程序入口源码、项目配置、界面资源、可执行exe及pdb调试文件dll提供核心组件源码完整展示从创建Workbook到读取Sheet、操作单元格的调用过程工程文件可打开直接编译调试配套resx、config等文件便于还原完整开发环境。示例程序从界面布局到读写逻辑均有清晰呈现可对照学习单元格数据读取、批量填充、格式设置以及Excel自带图表的生成与导出打印等常见操作另附txt说明帮助快速了解项目结构。目前已有3316人学习适合刚接触EPPlus、希望快速上手的C#初学者。1. 为什么选了EPPlus一次后台导入功能重构后的结论上个月帮一个朋友排查上位机程序崩溃原因很老套——他用Microsoft.Office.Interop.Excel在工控机上读取配置表那台机器装了个精简版OfficeCOM组件注册不完整Excel进程起一个崩一个最后连设备的标定参数都没法加载。我让他直接换EPPlus他反问一句这玩意儿读Excel靠谱吗于是我觉得有必要把这件事写清楚。EPPlus是一个纯托管的.NET开源库不需要本机安装Office直接以程序集方式操作.xlsx文件。它不仅能读单元格还能附带处理公式、样式、图表、数据透视表这些复杂内容且对新手极其友好——你不需要了解OpenXML底层规范也不需要处理COM对象生命周期一个ExcelPackage就能把整个工作簿握在手里。这篇文章适合刚接上手C#导Excel需求的初学者也适合在上位机、桌面工具、Web后台中被Excel读写折磨过的同行我会把环境接入、类型处理、整表导入、合并单元格、公式缓存这些实际操作中必踩的细节一次讲完。先说一个版本上的关键背景EPPlus 4.x用的是LGPL协议而从5.0开始官方切换到了Polyform Noncommercial授权。理解这句话的含义很重要——如果你只是个人学习、内部工具、非商业项目免费使用完全没问题但如果你是把它嵌进商业软件尤其是上位机这种要卖给客户的产品需要去官方购买商业授权。很多人在这里栽过跟头项目写完了法务一看授权协议傻眼了。选型阶段就得把这个因素算进成本里。1.1 三种主流读取Excel方案的横向对比我是在同一个需求背景下把三种方案都实测过的直接给结论方案依赖环境读取xls读取xlsx综合体验Microsoft.Office.Interop.Excel必须安装Office环境不可控支持支持API顺手但坑极多内存泄漏高发NPOI无纯托管支持支持功能全但偏底层样式处理繁琐EPPlus无纯托管不支持支持高层API最接近Excel的习惯COM Interop最大的问题不是功能而是进程级的不稳定性。Excel.Application每次启动会拉起一个独立进程你用Marshal.ReleaseComObject释放得再勤快只要有一个句柄遗漏工控机上就会堆积好几个僵死的EXCEL.EXE进程。我甚至还见过因为服务器装了WPS导致COM ProgID映射错位代码调用的接口直接抛异常的情况。这类问题在开发机上复现不了一到客户现场就原形毕露。NPOI的优势在于Apache 2.0协议商用毫无顾虑且多一个.xls老格式的支持。但它把工作簿模型暴露得比较底层比如单元格的样式、字体、边框需要逐个对象设置读数据时判断单元格类型、读取公式缓存值的代码写起来明显更啰嗦。如果你的项目只需要处理.xlsx格式且希望代码维护成本低EPPlus的体验高一个档次。还有一点必须明确的边界EPPlus对.xls97-2003格式无能为力。遇到老系统导出的.xls文件还是老老实实转格式或走NPOI。1.2 EPPlus的授权与版本选择EPPlus的授权判定其实不复杂非商业用途用免费版就够了设置LicenseContext.NonCommercial即可商业用途需要购买Polyform Commercial授权价格按开发者席位计算。很多博文只说NuGet安装EPPlus就能用没人提LicenseContext这件事结果就是新手跑Demo直接撞上异常。版本选择上我建议新项目直接用NuGet上的最新稳定版当时写这篇文章时EPPlus已经出到7.xAPI层面保持了一贯风格5.x时代的代码迁移成本很低。需要注意EPPlus 7对目标框架有要求老旧的.NET Framework 4.5项目如果拉不动新版可以锁定5.x版本读取Excel的核心能力完全够用。2. 工程接入与第一个能跑的读取Demo很多教程上来就给你甩一段几百行代码然后说你照着写就行。我的习惯是先打通一条最小链路确认环境、依赖、网络都正常再逐步叠加功能。读Excel也一样先把一个文件跑通后面的各种复杂表格都是在这个基础上加判断。2.1 NuGet安装与LicenseContext配置安装没什么好说的Visual Studio的NuGet包管理器搜索EPPlus或者用命令行dotnet add package EPPlus装完包之后最容易忽略的第一件事就是设置LicenseContext。EPPlus 5.0之后如果你不显式设置任何new ExcelPackage()操作都会抛LicenseException。设置方式有两种任选其一// 方式一代码里设置全局静态属性推荐 ExcelPackage.LicenseContext LicenseContext.NonCommercial; // 方式二appsettings.json里配置 { EPPlus: { ExcelPackage: { LicenseContext: NonCommercial } } }如果你写的是程序入口简洁的控制台项目方式一最直接在Main方法第一行设置即可。如果你做的是Web服务或上位机框架方式二更优雅且不用每次启动都执行代码。注意这个设置是进程级的不是每个Excel对象独立的务必在操作任何工作簿之前完成。2.2 最小读取代码ExcelPackage的using沼泽下面这段代码就是读取Excel最核心的骨架也是我每次给新手演示的第一段using OfficeOpenXml; ExcelPackage.LicenseContext LicenseContext.NonCommercial; // 用FileInfo打开文件也可以用Stream比如前端上传的流 using (var package new ExcelPackage(new FileInfo(D:\demo\books.xlsx))) { // 第0个工作表索引从0开始 var ws package.Workbook.Worksheets[0]; // 按单元格地址读取 Console.WriteLine(ws.Cells[A1].Value); // 原始值 Console.WriteLine(ws.Cells[A1].Text); // 显示文本 // 按行列号读取行列索引从1开始 object v2 ws.Cells[2, 3].Value; // 第2行第3列即C2 }这里有两个新手必踩的坑我分别说一下第一using (var package ...)这个包裹是必须的。EPPlus读取文件时会把整个xlsx的XML结构解析到内存中package对象持有大量非托管资源比如文件流、字体、图片不主动释放的话连续读几十个大文件内存飙升肉眼可见。用using包起来作用域结束自动Dispose()这也是我见过的最普遍的卡顿代码病根。第二Excel的行列索引是1-based不是0-based。多个语言混用的开发者在这里特别容易翻车写循环时习惯从0开始结果第一行数据永远读不到或者最后一行越界。做for (int row 1; row ws.Dimension.End.Row; row)这类遍历时起点别写错。2.3 理解三层对象模型EPPlus的对象模型其实非常符合直觉一句话就能讲清楚ExcelPackage对应一个.xlsx文件Workbook是工作簿Workbook下有一堆WorksheetWorksheet上的Cells就是单元格集合。这张结构图在心里建立起来后所有API都能顺着猜出来。你要读某个单元格起点永远是package.Workbook.Worksheets然后通过索引或名字定位工作表最后用地址或行列号定位单元格。还有个高频工具是ws.Dimension它表示当前工作表实际使用过的矩形区域返回一个ExcelAddress对象Dimension.Address就是类似A1:E200的字符串。注意一张空表一格子数据都没写的Dimension是null直接访问会弹空引用异常所以后面写通用方法时都会先判断Dimension null。我遇到一个很实际的场景客户给的表格前几行是公司抬头和说明文字真正的表头在第4行数据从第5行开始。这种情况下Dimension包含的是整页的所有内容起点是A1如果程序直接把Dimension.Start.Row当作表头行读出来的字段名就是XX科技有限公司这种鬼东西。所以通用方法必须允许外部传入真正的起始行号或者通过遍历表头特征去自动探测。3. 读单元格数据时类型处理是第一道坎Excel里的单元格数据本质上都是XML元素EPPlus帮你解析成了各种CLR类型返回但这个帮你解析恰恰是很多bug的源头。我见过不下三次这种问题明明Excel里是数字10000代码里却把它当成字符串去拼接拼出一个10000.0或者日期单元格读出来变成一串43001这样的数字序列。这些全是Value和Text用混导致的。3.1 Value和Text一个给程序用一个给人看这是EPPlus里最基础、也最容易被忽略的一组属性Value返回单元格的原始值类型可能是string、double、DateTime、bool或null这是给程序逻辑用的。比如判断数值大小、参与计算、写入数据库都该用Value。Text返回单元格的显示文本也就是你在Excel界面里看到的样子。它是按照单元格的数字格式NumberFormat格式化之后的字符串这是给人看的。比如带千分位的10,000、保留两位小数的3.14、日期2024/3/15。看一组对比就秒懂var cell ws.Cells[B2]; // 假设B2单元格数字格式为 0.00%Excel里显示 12.50% Console.WriteLine(cell.Value); // 输出: 0.125 Console.WriteLine(cell.Text); // 输出: 12.50%用Value拿到的0.125可以直接参与计算用Text拿到的12.50%拿来拼报表字符串正合适。反过来就错了把Text拿去double.Parse会炸把Value直接拼字符串又可能拼出科学计数法。所以我的习惯是往数据库/业务逻辑里塞数据用Value构建界面展示、导出报告、写日志用Text。做到了这条类型问题少一半。3.2 日期、数字、字符串的类型判定Value返回的是object拿到手必须判断真实类型再处理最直接的方式是switch或模式匹配object v ws.Cells[3, 1].Value; switch (v) { case null: Console.WriteLine(空单元格); break; case DateTime dt: Console.WriteLine($日期: {dt:yyyy-MM-dd}); break; case double d: Console.WriteLine($数字: {d}); break; case string s: Console.WriteLine($字符串: {s}); break; case bool b: Console.WriteLine($布尔: {b}); break; }特别提醒一个EPPlus的行为所有数字读取出来都是double。也就是说Excel里的整数100读出来是double类型值100但v is int永远为false。如果你用Convert.ToInt32(v)转换没问题但如果用v as int?或int.Parse(v.ToString())这类写法就可能踩坑——100还好一旦遇到1E05这种科学计数法显示v.ToString()直接给你100000倒还好遇到0.00001这种ToString的字符串可能不是你想要的格式。所以数字型判断用double需要整数时用Convert.ToInt32并做好舍入策略。日期这块另有一个坑如果Excel单元格的日期是以纯数字输入的比如直接敲43001EPPlus读出来就是double的43001不会自动帮你转成DateTime。想识别这种伪日期可以检查单元格的Style.Numberformat.Format是否包含yyyy或date关键字命中则用DateTime.FromOADate(43001)转换。我处理过一批客户历史报表里面一半日期都是这种裸数字不处理的话直接进数据库就成了天书。3.3 空单元格的三种判定读Excel的人必然要面对空值但空在EPPlus里有好几种表现判断条件不一样cell.Value null绝大多数空单元格的情况。cell.Text 某些合并区域右下角的单元格Value可能是nullText也可能是。cell.Text 或包含换行/不可见字符看起来空实际有内容。这种最阴常见于模板表格里残留的全角空格、制表符或换行符。处理方式上我的通用判断条件一般写成public static bool IsCellBlank(ExcelWorksheet ws, int row, int col) { if (ws.Cells[row, col].Value null) return true; return string.IsNullOrWhiteSpace(ws.Cells[row, col].Text); }IsNullOrWhiteSpace会把空格、制表符、换行符全部视为空比直接判稳妥得多。在导入到DataTable或业务对象前先过一道空值清理能少接很多脏数据的锅。4. 从单格到整表写一个通用Excel转DataTable方法实际项目里很少只读一两个格子绝大多数需求是把整张表或某个区域读出来存到DataTable或List 里让上层逻辑去消费。这里我把最常用的通用方法直接贴出来你可以当工具函数收藏。4.1 先确定表格范围Dimension与表头判断通用方法的第一步一定是判断Dimension。前面说过空表的Dimension是null不判断直接访问就是空引用异常。第二步是确定表头行大多数情况表头是第一行但模板复杂的表比如上面提到的多行抬头需要允许调用者指定headerRow参数。4.2 完整的ReadExcelToDataTable实现using OfficeOpenXml; using System.Data; public static class ExcelHelper { /// summary /// 读取xlsx的第一个工作表到DataTable /// /summary /// param namefilePath文件路径/param /// param nameheaderRow表头所在行号默认1/param /// param namestartRow数据起始行号默认表头下一行/param public static DataTable ReadToDataTable(string filePath, int headerRow 1, int startRow 2) { ExcelPackage.LicenseContext LicenseContext.NonCommercial; var dt new DataTable(); using (var package new ExcelPackage(new FileInfo(filePath))) { var ws package.Workbook.Worksheets[0]; if (ws.Dimension null) { return dt; // 空表直接返回空DataTable } int startCol ws.Dimension.Start.Column; int endCol ws.Dimension.End.Column; int endRow ws.Dimension.End.Row; // 1. 读取表头生成DataColumn for (int col startCol; col endCol; col) { string colName ws.Cells[headerRow, col].Text.Trim(); if (string.IsNullOrWhiteSpace(colName)) { colName $Column{col}; } dt.Columns.Add(colName); } // 2. 从数据起始行逐行读取 for (int row startRow; row endRow; row) { var dr dt.NewRow(); bool hasContent false; for (int col startCol; col endCol; col) { object v ws.Cells[row, col].Value; if (v ! null !string.IsNullOrWhiteSpace(v.ToString())) { hasContent true; dr[col - startCol] v; } } // 整行都是空则跳过避免DataTable里塞一堆空行 if (hasContent) { dt.Rows.Add(dr); } } } return dt; } }调用方式就一行DataTable dt ExcelHelper.ReadToDataTable(D:\configs\device.xlsx);有些细节值得展开说。表头列重复是个很常见的问题——Excel里两列都叫名称dt.Columns.Add(名称)第二次会抛DuplicateNameException。我做导入功能时被这个坑折磨过后来直接在列名后面加序号名称_2。这段代码为简洁起见没放进去但你在生产环境里必须处理。另外为什么DataRow赋值用Value而不是Text因为DataTable后面多半要接数据库或业务映射Value保留原始类型DateTime、double、string数据库映射时能正确识别字段类型。如果你用Text所有列都变成展示型字符串日期列、数值列在SQL层面会付出大量的转换代价。4.3 性能优化整块取值比逐个单元格快得多上面这个逐格循环对几百行的小表完全没问题但要是数据量过了上万行、几十列且表格里还带样式逐个Cells[row, col].Value的访问就成了明显的性能瓶颈。每个单元格访问都是一次对象构建和方法调用几万次下来体感会很差。优化的办法是用EPPlus的整块取值能力一次性把整个区域的数据塞进一个二维数组然后在内存里遍历object[,] values (object[,])ws.Cells[startRow, startCol, endRow, endCol].Value; // 注意这个数组是1-based索引values[1,1]对应区域左上角 for (int r 1; r values.GetLength(0); r) { for (int c 1; c values.GetLength(1); c) { object v values[r, c]; // 处理v } }实测过一份5万行×20列的报表逐格读取耗时大约在8秒上下换整块取值后能压到1秒以内。代价是内存占用变高一次性载入但多数场景下完全值得。这个1-based索引是整块取值最隐蔽的坑。数组的行列下标和Excel的行列号是对应的第一行数据在数组里是values[1, 0]而不是values[0, 0]。我当时按C#习惯从0遍历结果第一行数据消失排查了半天才意识到。各位千万记住这个二维数组的上界是GetLength(0)和GetLength(1)下标从1开始到上界结束。4.4 避免长驻内存的using规范除了用using包裹ExcelPackage之外还有一个容易被忽视的内存点如果你把package或worksheet对象存在类字段里或者错误地让控件绑定到worksheet对象上Dispose时机就无法保证。我见过一个WinForm程序把ExcelPackage挂在窗口类字段上窗口开着就一直占着几百MB内存关窗口时又因为事件绑定没法及时释放。规范做法是读取方法内部完成打开-读取-返回数据方法返回后package就释放上层只持有DataTable或List 这些纯数据对象。这样既安全又不影响使用体验。5. 真实表格里躲不开的硬骨头模板化Excel是工业界和办公场景最常见的东西而模板几乎必然有合并单元格、公式、复杂数字格式这三样哪个都能让一个已经跑通的读取程序当场翻车。这一节我逐个讲清楚。5.1 合并单元格非左上角单元格读出来是nullExcel里把A1:C1合并成一个单元格后只有A1存着真正的值B1和C1在XML层面是空的。EPPlus的读取规则很直接你读ws.Cells[B1].Value拿到的是null。但这不代表B1没内容——它属于合并区域只是数据存储在左上角而已。所以处理合并单元格的核心就一句话判断当前单元格是否Merge是的话就去取它所属合并区域的左上角值。public static object SafeGetValue(ExcelWorksheet ws, int row, int col) { var cell ws.Cells[row, col]; if (cell.Merge) { // FullAddress对合并区域内的任意单元格都会返回完整区域地址比如 A1:C1 var mergedRange ws.Cells[cell.FullAddress]; return ws.Cells[mergedRange.Start.Row, mergedRange.Start.Column].Value; } return cell.Value; }这里的关键是FullAddress。对一个合并区域内非左上角的单元格cell.Address只是它自己的坐标比如B1但cell.FullAddress会返回整个合并区域的地址比如A1:C1。拿到地址再ws.Cells[...]定位用.Start.Row和.Start.Column取左上角这才是真正存值的地方。需要注意Merge这个判断属性在EPPlus里是bool类型直接if (cell.Merge)用即可。如果表格里的合并特别多建议在封装层统一处理好而不是每个业务方法里重复判断。5.2 公式单元格你读到的其实是缓存值Excel里B3 A1*A2这种公式EPPlus读取时默认不会真正去公式求值引擎跑一遍而是直接返回xlsx文件里保存的上次计算结果Excel保存文件时会把计算结果缓存进XML。这对绝大多数读取场景是好事——速度快、结果就是用户在Excel里看到的值。什么时候会出问题两个典型情况一是文件最近被Excel或WPS打开过但公式变了之后没有重新保存缓存值可能滞后。虽然Excel保存时都会重算但万一程序自动生成的xlsx里公式没算过缓存值就可能是空的。二是你想在程序里根据公式动态计算结果。这时需要调用EPPlus自带的公式解析引擎// 用之前先计算整张表之后读Value就是计算后的结果 ws.Calculate(); var result ws.Cells[B3].Value;Calculate()在大型表格上是有性能开销的而且它解析的公式复杂度有限复杂数组公式、外部链接基本无能为力。我的建议是默认读缓存值确实需要动态计算的场景再单独对特定单元格或区域调用Calculate()全表计算务必谨慎。至于公式本身EPPlus也提供了读取入口string formula ws.Cells[B3].Formula; // 拿到 A1*A2这在检查模板逻辑、做公式审计的时候挺好用。整体来看业务上要拿到用户看到的值用Value或Text即可不用去管Formula。5.3 校验数据时的异常类型ExcelErrorValue还有一种单元格内容易被忽略错误值。比如公式除数为0Excel里显示#DIV/0!VLOOKUP查不到显示#N/A。EPPlus对这类单元格的Value返回的不是字符串而是一个ExcelErrorValue对象。如果不加处理直接ToString()或写库轻则拿到奇怪字符串重则类型转换异常。我处理导入数据时会在读取环节统一做一个错误值检测if (v is ExcelErrorValue err) { // 记录日志第几行第几列是Excel错误值 Console.WriteLine($单元格({row},{col})出现Excel错误: {err.Type}); return null; // 按空值处理 }err.Type是ExcelErrorType枚举能区分#DIV/0!、#N/A、#VALUE!等具体情况日志里写得清清楚楚排查时一眼定位。这一步在Excel清洗类工具里价值极大因为脏数据才是这类工具真正的工作对象。6. 一个上位机场景的完整实例启动时读取配置参数前面讲了这么多零散知识点最后用一个我实际做过的上位机项目案例把它们串起来。这也是很多C#新手真正会遇到的场景设备标定参数、通信配置、工位表这些数据由工艺人员维护在Excel里上位机软件启动时读取并应用到系统中。6.1 需求是怎么提的现场的情况是工程师不想去改代码或配置文件只想拿Excel按模板填参数。表格格式大致是参数名值说明设备IP192.168.1.10相机通信地址端口号5000TCP端口标定系数0.985速度校正启停时间08:30班次开始需求核心就是启动时把这个Sheet读出来按参数名作为Key值列作为Value构建成Dictionarystring, object再映射到配置类里。如果Excel里有参数名拼写错误或重复日志里明确报警。6.2 核心代码从Excel到配置字典public static Dictionarystring, object LoadConfigFromExcel(string filePath, string sheetName) { ExcelPackage.LicenseContext LicenseContext.NonCommercial; var dict new Dictionarystring, object(StringComparer.OrdinalIgnoreCase); using (var package new ExcelPackage(new FileInfo(filePath))) { var ws package.Workbook.Worksheets[sheetName] ?? throw new Exception($找不到Sheet: {sheetName}); if (ws.Dimension null) return dict; int endRow ws.Dimension.End.Row; for (int row 1; row endRow; row) { string key ws.Cells[row, 1].Text?.Trim(); if (string.IsNullOrWhiteSpace(key)) continue; // 跳过空行和分隔行 object value SafeGetValue(ws, row, 2); // 第2列是值 if (value is ExcelErrorValue) // 错误值不进配置 { Console.WriteLine($[警告] 第{row}行存在Excel错误值已忽略); continue; } if (dict.ContainsKey(key)) { Console.WriteLine($[警告] 重复参数: {key}保留最后一个); } dict[key] value; } } return dict; }拿到字典之后具体怎么映射到配置类就灵活了。我会写一个专门的方法做类型转换比如端口号字段用Convert.ToInt32(dict[端口号])注意数字读出来是doubleConvert.ToInt32能正确舍入处理IP字段就用dict[设备IP].ToString()。这段代码里有两个小细节是实战总结出来的一是参数名比较用了StringComparer.OrdinalIgnoreCase避免设备ip和设备IP因为大小写不一致被当成两个key二是空行和分隔行用IsNullOrWhiteSpace(key)过滤因为工程师经常在参数间留空行做视觉分组处理不好字典里就会多出莫名其妙的空key。6.3 模板规范和异常处理的经验把这段逻辑放到生产环境跑了大半年我总结出几条看起来不起眼但救命的东西第一参数模板第一行绝不要留空。很多模板为了美观第一行是空行第二行才是表头。如果程序把空行当数据处理key就成了空字符串value全堆到一个名叫的键下面。我会在加载后主动校验if (!dict.ContainsKey(参数名))之类的强制检查模板格式不对直接抛异常而不是带着错误配置启动设备。第二读Excel这类外部输入永远不要假设数据完全合法。值列可能被填成中文、留空、或者写了个表情符号。我处理的方式是值类型转换统一走一个方法转换失败就记录日志并给默认值同时界面弹黄条提示第N行参数格式异常绝不让一个坏数据导致整个设备初始化失败。第三LicenseContext在正式环境里的处理。如果上位机是卖给客户的商业软件EPPlus的授权费要提前算进报价如果是内部自用记得把LicenseContext.NonCommercial写在程序入口处不然部署到工控机上第一天就会因为漏设置而崩溃。用EPPlus读Excel这件事本质上不是会调API就结束的真正的功夫全在数据边界、类型转换、异常兜底这些细节上。上面这些坑我基本都踩过一遍写出来就是希望后来的人能少走几步弯路。你上手时如果遇到EPPlus行为跟预期不一致的情况尤其是合并单元格、公式缓存值这两类先别怀疑库有问题翻回来看一下是不是处理思路的问题——绝大多数时候坑都在表格本身。本文还有配套的精品资源点击获取