簡介C#結合Epplus庫操作Excelxlsx的封裝資源面向需要報表導出、數據分析及圖表展示的.NET開發(fā)者覆蓋讀取、寫入與折線圖/曲線圖生成等高頻場景。壓縮包共315個文件大小35.67MB以xml、dll、cs源文件為主另含xlsx示例文件、png示意圖與txt/說明文檔構成“源碼-依賴-樣例-文檔”的完整結構便于直接參考或集成。目前已有131人學習下載。資源重點封裝了Excel讀寫的通用方法可傳入文件路徑快速訪問工作表、行列與單元格也支持多類型數據精確寫入圖表部分針對趨勢展示做了專門封裝只需指定數據與圖表類型即可生成折線圖或曲線圖并插入工作表中。同時體現異常處理與擴展性設計遇到文件缺失或格式錯誤能給出友好提示開發(fā)者可在此基礎上按業(yè)務繼續(xù)擴展減少重復勞動。 做C#這塊時間長了尤其是寫過幾年上位機和數據管理系統的朋友應該都有一個共同的體會Excel導出、導入這個需求基本是躲不掉的。業(yè)務方說“給我導個報表”領導說“把這個數據整理成表格發(fā)我”客戶說“要把設備采集的數據能導出來分析”。一開始我用CSV糊弄可一旦遇到格式要求、圖表要求CSV就完全頂不住了。后來轉用EPPlus發(fā)現這東西確實好用但用久了又覺得煩——因為每次處理xlsx都要反復寫一堆讀取循環(huán)、樣式設置、圖表配置代碼越寫越臃腫而且每個人寫的風格還不一樣維護起來特別痛苦。這篇博文就是從我自己的項目實踐整理出來的我用C#對EPPlus做了一層封裝把xlsx的讀取、寫入以及折線圖和曲線圖生成統一封裝成一套簡潔的方法。這樣業(yè)務代碼只關心數據不用關心Excel細節(jié)。如果你也在做C#相關的數據導出、報表生成或者想在上位機項目里直接把實時數據畫成圖表這篇內容應該能給你一個可以直接抄作業(yè)的方案。1. 選型EPPlus之前的糾結很多新人拿到“操作Excel”這個需求第一反應是搜“C# Excel庫”然后會看到NPOI、Aspose.Cells、EPPlus還有一個老古董Microsoft.Office.Interop.Excel。這幾種方案各有各的坑我在踩過一圈之后才鎖定EPPlus先說結論再講理由。1.1 放棄COM組件和NPOI的真實原因先說Microsoft.Office.Interop.Excel。它的本質是調用本機安裝的Office軟件來操作Excel也就是說目標電腦和服務器必須裝著Office。這在開發(fā)機上挺方便但部署到客戶現場就麻煩了要不要裝Office裝哪個版本裝了之后DCOM權限怎么配服務端跑著跑著Excel進程崩潰卡死怎么辦我見過不少項目被這個com組件坑到懷疑人生它非常適合個人桌面電腦上用但放到需要穩(wěn)定運行的業(yè)務系統里基本就是定時炸彈。NPOI是Java POI項目的.NET移植優(yōu)點是完全免費而且不需要Office環(huán)境。但我實際用下來覺得它的API風格太“Java”了寫起來啰嗦尤其要生成圖表時NPOI的圖表支持非常弱基本上要靠手工拼XML那個操作真的是能把人逼瘋。如果你的需求只是簡單讀寫表格NPOI還湊合一旦涉及圖表、樣式、透視表這些高級特性開發(fā)效率會直線下降。1.2 EPPlus的核心優(yōu)勢與許可證提醒EPPlus是基于OpenXML協議的.NET庫不需要裝Excel跨平臺API設計得很符合C#開發(fā)者的直覺。它內置了圖表、數據透視表、樣式、公式計算等能力而且性能也不錯算是.NET生態(tài)里做Excel報表的“六邊形戰(zhàn)士”。不過必須提醒一句EPPlus從4.5版本開始變更了許可證使用的是Polyform Noncommercial License非商業(yè)場景免費商業(yè)使用需要購買授權。這是個非常容易踩的合規(guī)問題。很多同行早期用4.x版本習慣了升級到5.x/6.x之后突然遇到LicenseException一臉懵。解決方案一般有兩個要么在非商業(yè)項目里設置ExcelPackage.LicenseContext LicenseContext.NonCommercial要么公司有預算時直接購買商業(yè)授權要么繼續(xù)鎖在4.5以下的老版本但這樣會失去新特性。我自己的建議是不管項目性質如何開工前先把許可證這條確認清楚免得做到一半被法務或者技術排查找上門。2. 封裝設計的整體思路EPPlus本身功能很強大但直接用原生API寫業(yè)務代碼還是會有大量重復。比如讀取一個表格要處理空行、格式轉換、合并單元格寫入一個表格要處理表頭樣式、列寬、自動篩選生成圖表要配數據源、坐標軸、圖例。這些邏輯每個項目都要寫一遍于是我決定做一層封裝。2.1 先把調用方想清楚設計這個封裝時我反復問自己一個問題業(yè)務程序員拿到這個庫他最想寫怎樣的代碼順著這個思路我抽象出三個核心動作讀取給一個文件路徑和Sheet名返回DataTable或者List 。寫入給一個DataTable或者List 指定文件路徑自動建表并寫入。畫圖給一組數據和圖表參數在指定Sheet上生成折線圖或曲線圖。接口定了之后就好辦多了。內部實現無論怎么改調用方完全不用關心。比如未來我把底層從EPPlus換成別的庫對上層業(yè)務代碼幾乎是無感知的。這里有一個很關鍵的封裝決策所有文件操作都統一用FileInfo而不是字符串路徑。原因是EPPlus的ExcelPackage構造函數接受FileInfo它在解析路徑、處理相對路徑時更規(guī)整而且天然支持后續(xù)的文件流操作。如果你在封裝里到處傳字符串路徑后面還得自己處理Path.GetFullPath之類的邏輯不如一開始就統一。2.2 核心類與接口約定我定義了一個靜態(tài)類ExcelHelper主要方法大體是這樣public static class ExcelHelper { // 讀取返回DataTable public static DataTable ReadToDataTable(string filePath, string sheetName null); // 寫入DataTable寫入xlsx可指定Sheet名 public static void WriteDataTable(DataTable dt, string filePath, string sheetName Sheet1); // 寫入泛型集合寫入xlsx public static void WriteListT(ListT data, string filePath, string sheetName Sheet1); // 圖表折線圖/曲線圖 public static void AddLineChart(string filePath, string sheetName, Dictionarystring, Listdouble seriesData, Liststring categories, string chartTitle, bool smooth false, string chartSheetName null); }這只是一個外部形態(tài)真正的實現遠比這幾個方法復雜。比如在ReadToDataTable內部要處理空Sheet、找不到Sheet、單元格類型轉換在WriteListT內部要利用反射讀取泛型對象的屬性名作為表頭。這些細節(jié)我會在下面幾節(jié)展開。3. 讀取xlsx的細節(jié)實現讀取是相對基礎的一塊但越是基礎越容易出錯。最典型的場景是生產系統導出的Excel里有空行、有合并單元格、有各種日期格式直接按固定列索引讀很容易踩到坑。3.1 基礎讀取從ExcelWorksheet到DataTable用EPPlus讀取一個Sheet核心代碼如下using OfficeOpenXml; // 5.0及以上版本必須設置許可證上下文 ExcelPackage.LicenseContext LicenseContext.NonCommercial; using (var package new ExcelPackage(new FileInfo(filePath))) { var worksheet string.IsNullOrEmpty(sheetName) ? package.Workbook.Worksheets[1] : package.Workbook.Worksheets[sheetName]; if (worksheet null) throw new Exception($未找到Sheet: {sheetName}); var dt new DataTable(worksheet.Name); var dimension worksheet.Dimension; if (dimension null) return dt; // 第一行作為列名 foreach (var cell in worksheet.Cells[1, 1, 1, dimension.End.Column]) dt.Columns.Add(cell.Text); // 從第二行開始讀數據 for (int row 2; row dimension.End.Row; row) { if (IsRowEmpty(worksheet, row, dimension.End.Column)) continue; var dataRow dt.NewRow(); for (int col 1; col dimension.End.Column; col) dataRow[col - 1] worksheet.Cells[row, col].Text; dt.Rows.Add(dataRow); } return dt; }這段代碼看起來挺標準但有兩個細節(jié)要注意。第一worksheet.Dimension如果你不提前判斷當Sheet是空的時候直接訪問Dimension.End.Row會拋空引用異常。第二讀取單元格用了.Text而不是.Value因為.Text返回的是單元格格式化后的字符串比如日期列在Excel里顯示成“2024-01-15”.Text就直接拿到“2024-01-15”而.Value拿到的是Excel內部的OADate序列號比如“45221”這種數字對業(yè)務方來說完全不友好。3.2 三個最容易翻車的讀取場景第一個是空行判斷。我見過太多人直接判斷第一列是否為空結果數據剛好第一列有空值整行就被跳過了。我的做法是把整行所有列的文本拼起來判斷是否全為空private static bool IsRowEmpty(ExcelWorksheet worksheet, int row, int endCol) { for (int col 1; col endCol; col) { if (!string.IsNullOrWhiteSpace(worksheet.Cells[row, col].Text)) return false; } return true; }第二個是日期列。如果Excel里的日期列是真正的日期格式用.Text拿到的字符串格式是“2024/1/15”還是“2024-01-15”取決于單元格的數字格式。更穩(wěn)妥的做法是在讀取前明確約定業(yè)務方在Excel里把日期列設置成文本格式或者我們讀取后用DateTime.TryParse嘗試轉換確保拿到的是標準化的DateTime對象。如果你拿到的是OADate序列號記得用DateTime.FromOADate(Convert.ToDouble(rawValue))轉換。第三個是合并單元格。Excel的合并單元格值只存在區(qū)域左上角的那個單元格里其他區(qū)域如果直接按行列去讀拿到的都是空字符串。比如產品名稱列做了一個從第2行到第5行的合并單元格你遍歷到第3、4、5行時讀到的產品名稱全是空的。解決思路有兩種一是用worksheet.Cells[row, col].Merge屬性判斷是否在合并區(qū)域內一旦發(fā)現合并就向上找合并區(qū)域的起始單元格取值二是讀取前先對合并單元格做“向下填充”把值填滿整個合并區(qū)域。第一種更通用但實現復雜一點。3.3 讀取性能大數據量時的優(yōu)化如果你只是讀幾百行數據上面那個雙層循環(huán)完全沒有問題。但如果數據量到了幾萬行、幾十萬行逐單元格讀取就會變得非常慢。我有一次處理一個5萬行、30列的生產記錄表用逐單元格讀法跑了將近1分鐘后來做了兩層優(yōu)化使用worksheet.Cells.Value一次性取出整個二維數組在內存里循環(huán)避免反復訪問Excel對象的開銷。關閉事件和屏幕刷新雖然EPPlus不需要屏幕刷新但可以通過package.Workbook.Worksheets級別的操作減少內部開銷。優(yōu)化后同樣數據量基本能壓縮到2秒以內。所以如果你封裝讀取方法建議內部先探測數據規(guī)模超過某個閾值就切到數組批量讀取模式。4. 寫入xlsx的細節(jié)實現寫入比讀取更難的一點是你不僅要考慮數據還要考慮格式。因為業(yè)務方最討厭看見一坨沒排版的數據表頭不加粗、列寬不一致、數字不帶千分位這在展示層是災難。4.1 從DataTable到工作表的快速寫入EPPlus提供了一個很省事的擴展方法LoadFromDataTable。它能一次性把整個DataTable寫進工作表比逐單元格賦值高效很多?；敬a如下using (var package new ExcelPackage()) { var worksheet package.Workbook.Worksheets.Add(Sheet1); worksheet.Cells[A1].LoadFromDataTable(dt, true); // 設置表頭樣式 using (var range worksheet.Cells[1, 1, 1, dt.Columns.Count]) { range.Style.Font.Bold true; range.Style.Fill.PatternType ExcelFillStyle.Solid; range.Style.Fill.BackgroundColor.SetColor(Color.LightGray); range.Style.HorizontalAlignment ExcelHorizontalAlignment.Center; } // 自動列寬 worksheet.Cells[worksheet.Dimension.Address].AutoFitColumns(); package.SaveAs(new FileInfo(filePath)); }LoadFromDataTable的第二個布爾參數表示是否把列名寫為表頭。這里有個小坑如果DataTable的列名是英文比如ProductName而我們需要中文表頭“產品名稱”直接LoadFromDataTable就不合適了。我的方案是先手動寫一行中文表頭再從第二行開始逐列賦值或者干脆用反射把實體屬性上的[DisplayName]特性讀取出來做表頭。后者更工程化適合實體類已經定義好的項目。4.2 樣式與細節(jié)別讓報表顯得太業(yè)余樣式這塊體面的報表至少要處理三件事。第一表頭樣式。表頭加粗、加背景色、加邊框這些都能讓表格清晰很多。我習慣把表頭背景色設置成淺灰色或者淡藍色而不是純黑色因為純黑底白字打印起來太浪費墨。第二列寬。AutoFitColumns()在英文內容下效果不錯但中文場景下經常偏窄尤其是帶長文本的列。我在實際項目中很少完全依賴自動列寬而是先AutoFitColumns再對指定列做二次調整比如把“備注”這類列手動設成50把ID列設成8保證表格既不過分擁擠也不至于太松散。第三數字格式。寫金額、百分比、小數時如果直接寫double原始值Excel會顯示一長串比如1234.5678甚至1234.5678000001。正確做法是在寫入前用worksheet.Cells[D2:D100].Style.Numberformat.Format #,##0.00設置數字格式。這個事看似很小但對報表的專業(yè)度影響極大。尤其要注意浮點精度問題寫入前對數據做Math.Round(value, 2)既能保證顯示正確也能避免Excel計算時出現0.30000000000000004這種怪異結果。4.3 大數據量寫入從幾秒到幾百毫秒LoadFromDataTable在數據量上萬時性能還可以但到10萬行以上也會開始變慢。更高效的做法是直接用二維數組賦值給整個Rangevar dataArray new object[dt.Rows.Count, dt.Columns.Count]; for (int i 0; i dt.Rows.Count; i) for (int j 0; j dt.Columns.Count; j) dataArray[i, j] dt.Rows[i][j]; worksheet.Cells[2, 1].LoadFromArrays(dataArray);LoadFromArrays是EPPlus里專門用來批量寫二維數組的方法比逐單元格賦值要快一個量級。如果你的數據源不是DataTable而是ListT可以先反射轉換成object[,]再走同樣路徑。另外一個經驗是如果是一次性導出大數據量不要邊寫邊設置樣式先把所有數據寫進去最后統一設置Range的樣式否則性能會急劇惡化。5. 生成折線圖與曲線圖圖表部分是很多人的盲區(qū)。EPPlus支持很多圖表類型但API有點繞尤其在5.x和6.x之間還有差異。我在封裝的迭代過程中也被坑過幾次下面把核心邏輯說清楚。5.1 圖表必須掛在Drawing上EPPlus里的圖表不是獨立文件而是掛在工作表的Drawings集合里。你可以理解為Excel里的“浮動圖形圖層”圖表和數據可以放在同一個Sheet也可以放在單獨的一個Sheet。創(chuàng)建折線圖的典型代碼是var chart worksheet.Drawings.AddChart(chartSales, eChartType.Line); chart.Title.Text 月度銷售趨勢; chart.SetPosition(2, 0, 6, 0); // 左上角位置 chart.SetSize(800, 400); var series chart.Series.Add(worksheet.Cells[B2:B13], worksheet.Cells[A2:A13]); series.Header 銷售額;AddChart方法接受兩個參數圖表名稱Sheet內唯一和圖表類型。eChartType.Line是折線圖eChartType.LineMarkers是帶數據標記的折線圖。Series.Add的第一個參數是Y值區(qū)域第二個參數是X軸類別區(qū)域。這里有個反直覺的坑圖表系列的數據源必須指向工作表中實際存在的單元格區(qū)域不能直接傳一個List數組。也就是說你要畫圖數據必須先寫進工作表的某個區(qū)域然后再通過worksheet.Cells[B2:B13]這種方式告訴EPPlus“從哪塊區(qū)域取數”。所以封裝時我的邏輯是先把數據寫到一個隱藏Sheet或者數據區(qū)域再創(chuàng)建圖表引用它。畫完之后這個數據區(qū)域可以隱藏掉避免用戶看到一堆輔助數據。5.2 折線圖和曲線圖的真正區(qū)別很多人以為“折線圖”和“曲線圖”是兩種不同的圖表類型其實在EPPlus里它們都是LineChart。唯一的區(qū)別在于系列有沒有開啟平滑曲線。開啟smooth之后原本的折線會變成圓滑的貝塞爾曲線視覺上更柔和常用于趨勢類展示。具體代碼是在拿到ExcelLineChartSeries之后設置Series.Smooth truevar lineSeries (ExcelLineChartSeries)chart.Series.Add(rangeY, rangeX); lineSeries.Smooth true; // false就是普通折線圖換句話說我的封裝里加了一個bool smooth參數內部就是把LineChart系列的Smooth屬性設一下。這里有個細節(jié)AddChart返回的ExcelChart對象Series.Add返回的是ExcelChartSeries需要把它強制轉換成ExcelLineChartSeries才能訪問Smooth。如果類型不匹配說明你創(chuàng)建圖表時用的枚舉類型不對。5.3 圖表參數的可配置化實際業(yè)務場景中圖表的標題、X軸名稱、Y軸名稱、圖例位置每個項目要求都不一樣。我在封裝里把這些都作為可選參數暴露出來。例如chart.XAxis.Title.Text 月份; chart.YAxis.Title.Text 金額; chart.Legend.Position eLegendPosition.Right;還有個容易被忽略的地方是網格線。默認生成的圖表自帶橫向網格線做趨勢圖還好但如果客戶要求簡潔風記得把網格線關掉chart.YAxis.MajorGridlines.Fill.Color Color.Transparent;圖表位置和大小的設置也要注意。SetPosition和SetSize在EPPlus里是按像素算的SetPosition(row, rowOffsetPixels, col, colOffsetPixels)表示圖表左上角距離某行某列交點的偏移量。如果你希望圖表完全覆蓋在某幾個固定單元格區(qū)域還得按單元格的寬高估算偏移這個在封裝階段至少要做到“能放對位置、能被用戶拖動微調”不用追求像素級精確。6. 常見異常與掉坑實錄這一節(jié)是我最想寫的。很多坑網上文檔里根本不提只有實際做了才碰得到。整理成速查表方便你寫代碼的時候對照。6.1 LicenseExceptionEPPlus 5的許可證異常這是最常見的異?！，F象是代碼運行到new ExcelPackage()時直接拋LicenseException提示需要設置LicenseContext。網上很多老教程沒有這一行因為它們在寫4.x版本。解決辦法很簡單ExcelPackage.LicenseContext LicenseContext.NonCommercial;這行要在創(chuàng)建ExcelPackage實例前執(zhí)行。我建議在封裝類的靜態(tài)構造函數里設置一次而不是在每個方法里重復寫。如果你用的不是最新包還有一種做法是寫配置文件但靜態(tài)構造函數顯式賦值最直觀排查起來也最快。6.2 生成的文件Excel打開提示損壞這個問題我排查過很久最終發(fā)現原因多種多樣但最常見的有三類。一是文件路徑的擴展名和實際內容不一致比如保存的文件擴展名是.xls但內容實際是xlsx格式Excel打開時就會提示“文件格式與擴展名不匹配”。二是寫入圖表時chart.Series.Add指向的數據區(qū)域不存在或者引用錯誤導致生成的OpenXML內容異常。三是保存過程中有異常發(fā)生但沒有正常關閉文件流文件沒有完整寫入。這個問題的排查思路是用記事本或者解壓工具直接打開生成的xlsx文件看看[Content_Types].xml和xl/charts/目錄下的內容是否完整。如果對OpenXML不熟也可以寫一個自動校驗的小邏輯生成后用ExcelPackage重新打開一次文件能打開就說明結構基本沒問題。6.3 圖表不顯示或只有坐標軸沒有線出現這種情況九成都是數據區(qū)域引錯了。EPPlus的圖表引用單元格區(qū)域時字符串要傳絕對引用比如Sheet1!$B$2:$B$13或者直接用worksheet.Cells[B2:B13]。如果傳成相對引用B2:B13某些版本下不會生效圖表會顯示空白。另外如果數據源區(qū)域里包含空單元格折線圖會在空值處斷開。如果需要連續(xù)曲線要么把空值用#N/A代替Excel圖表默認忽略#N/A不畫線要么在寫入數據時對空值做填充。6.4 性能問題導出10萬行卡死EPPlus雖然性能不錯但如果你用逐單元格組合樣式10萬行能寫到你懷疑人生。我踩過最大的坑是在循環(huán)里給每個單元格設置邊框和字體結果導出10000行用了將近3分鐘。后來改成批量設置Range樣式整個操作縮短到3秒以內。所以性能優(yōu)化的核心原則就是能用Range批量操作絕不逐單元格操作。包括樣式、數字格式、列寬都要合并成一個Range統一設置。另外如果你的數據源是DataTable最好把DataTable中的ColumnName和實際Excel列對應關系先處理好避免寫入時做二次映射否則表格大了之后光是映射關系就夠你折騰的。6.5 跨平臺部署時的注意事項EPPlus是純托管庫部署到Linux和Docker容器里沒有問題不需要安裝Excel。但有兩點要注意第一在Linux環(huán)境操作高并發(fā)的Excel生成時要注意臨時目錄的權限EPPlus在寫入大文件時會用到臨時文件/tmp目錄沒權限就報錯。第二文件路徑分隔符不要硬編碼Windows的\用Path.Combine或/否則在Linux上會找不到文件。7. 封裝庫的后續(xù)擴展思路根據我這段時間的使用體驗這個封裝庫在實際項目中還可以繼續(xù)演進。目前我新增的一個能力是模板化導出先創(chuàng)建一個帶好樣式、圖表占位、公式的Excel模板文件然后EPPlus打開模板用真實數據填充指定位置。這種方式特別適合周報、月報這類固定格式的場景比代碼里寫死樣式要靈活得多前端做好Excel模板后扔給后端填數效率和美觀度都能兼顧。還有一個方向是支持多Sheet報表。比如一個數據分析報告里第一頁放運營匯總數據第二頁放明細第三頁放趨勢圖。目前的封裝單方法處理單Sheet后續(xù)可以考慮增加一個“報表描述對象”把頁面結構、數據源、圖表位置統一描述然后一鍵生成整個工作簿。這種改進對調用方來說幾乎是零學習成本。最后再分享一個小技巧因為EPPlus的核心操作都是圍繞ExcelPackage展開的封裝里一定要保證using或者Dispose正確否則文件流不釋放生成完文件還處于占用狀態(tài)后面再讀取就會報“文件被另一個進程使用”。我自己的做法是統一走using塊并且在寫文件之前先判斷目標文件是否存在存在則備份重命名避免覆蓋失敗把原文件搞壞。這一套封裝用下來最大的感受就是Excel操作并不難難的是把各種邊界情況都處理好。如果你們項目里也經常被Excel需求和圖表需求反復折騰建議早點做一層這樣的封裝把這篇文章里的幾個坑提前規(guī)避掉能省下不少排查和加班的時間。本文還有配套的精品資源點擊獲取