C# EPPlus 8+ 使用教程

2026-07-30 17:25sg

EPPlus 是.NET生态最常用的读写xlsx组件。升级到 EPPlus 8.0 及以上版本后，原有 v5~v7 的授权代码直接失效，运行程序抛出异常：LicenseNotSetException。

EPPlus8 彻底废弃 LicenseContext，改用全新的 ExcelPackage.License.SetXXX() 授权方式。很多开发者因为授权位置、写法错误持续报错。

本文提供标准授权写法，附带完整Excel导入工具类，支持WinForm、控制台、ASP.NET项目直接复用。
⚠️ EPPlus 仅支持 .xlsx 文件，不兼容老式 .xls。

新旧版本授权对比

EPPlus版本	授权代码	状态
v5 ~ v7	`ExcelPackage.LicenseContext = LicenseContext.NonCommercial;`	已过时，EPPlus8失效
v8.0 +	`ExcelPackage.License.SetNonCommercialPersonal("名称");`	推荐新标准写法

✅ 强制规则：授权代码必须在 new ExcelPackage() 实例化之前执行，全局仅初始化一次！先创建实例再设置授权依然会抛异常。

1. NuGet 安装依赖

包管理器控制台命令：

Package Manager 安装EPPlus

Install-Package EPPlus

.NET CLI 命令：

bash .NET CLI

dotnet add package EPPlus

2. 三种授权方法说明

csharp 授权代码

// 个人非商用（学习、个人工具、免费软件）
ExcelPackage.License.SetNonCommercialPersonal("Excel导入");

// 非营利组织使用
// ExcelPackage.License.SetNonCommercialOrganization("组织名称");

// 企业商用，需要官网购买License密钥
// ExcelPackage.License.SetCommercial("你的授权密钥");

⚠️ 合规提醒：企业业务系统、收费项目禁止使用 SetNonCommercialPersonal，必须购买EPPlus商业授权。

3. Excel导入帮助类完整代码

封装通用读取xlsx方法，自动读取表格所有行文本：

csharp ExcelHelper.cs

using OfficeOpenXml;
using System;
using System.Collections.Generic;
using System.IO;

/// 
/// EPPlus8 Excel导入帮助类
/// 
public static class ExcelHelper
{
    /// 
    /// 初始化EPPlus授权【程序启动执行一次】
    /// 
    public static void InitEpplusLicense()
    {
        ExcelPackage.License.SetNonCommercialPersonal("Excel导入");
    }

    /// 
    /// 读取Excel返回文本数组集合
    /// 
    /// xlsx文件路径
    /// 是否存在表头（第一行跳过）
    /// 
    public static List<string[]> ReadExcel(string filePath, bool hasHeader = true)
    {
        List<string[]> resultList = new List<string[]>();
        if (!File.Exists(filePath))
        {
            throw new Exception("Excel文件不存在！");
        }

        FileInfo fileInfo = new FileInfo(filePath);
        using (ExcelPackage package = new ExcelPackage(fileInfo))
        {
            var worksheet = package.Workbook.Worksheets[0];
            if (worksheet.Dimension == null)
                return resultList;

            int startRow = hasHeader ? 2 : 1;
            int maxRow = worksheet.Dimension.Rows;
            int maxCol = worksheet.Dimension.Columns;

            for (int row = startRow; row <= maxRow; row++)
            {
                string[] rowData = new string[maxCol];
                for (int col = 1; col <= maxCol; col++)
                {
                    rowData[col - 1] = worksheet.Cells[row, col].Value?.ToString()?.Trim();
                }
                resultList.Add(rowData);
            }
        }
        return resultList;
    }
}

4. WinForm 项目调用示例

推荐在Program.cs入口初始化授权，保证最先执行：

csharp Program.cs

static class Program
{
    [STAThread]
    static void Main()
    {
        // 程序入口最先初始化授权！
        ExcelHelper.InitEpplusLicense();

        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.Run(new MainForm());
    }
}

窗体按钮点击触发导入：

csharp 按钮事件

private void btnImport_Click(object sender, EventArgs e)
{
    using (OpenFileDialog openDialog = new OpenFileDialog())
    {
        openDialog.Filter = "Excel文件(*.xlsx)|*.xlsx";
        if (openDialog.ShowDialog() != DialogResult.OK) return;

        try
        {
            var data = ExcelHelper.ReadExcel(openDialog.FileName);
            MessageBox.Show($"读取完成，共{data.Count}行数据");
        }
        catch (Exception ex)
        {
            MessageBox.Show("导入失败：" + ex.Message);
        }
    }
}

5. 常见问题排查

持续抛出 LicenseNotSetException
确认授权初始化代码在 new ExcelPackage() 之前运行；不要写在导入方法内部循环调用。
能否继续使用 LicenseContext？
EPPlus8标记为过时，新项目建议全部迁移到 SetXXX 系列方法。
能不能读取xls文件？
不能。xls为旧版二进制格式，EPPlus只支持OOXML标准xlsx。读取xls建议选用NPOI。
大文件内存占用高
EPPlus默认全量加载表格，超大Excel可考虑分页读取或切换其他流式组件。

小结

EPPlus8 的授权改动坑非常多，核心要点整理：

1 授权前置执行，实例化ExcelPackage之前初始化

2 区分商用/非商用，遵守Polyform协议避免合规风险

3 仅支持xlsx，旧xls文件需要更换组件

4 帮助类可直接复用，快速实现Excel导入功能

该工具类不仅适用于WinForm，控制台、ASP.NET WebAPI项目只需要在程序入口执行授权初始化即可直接使用。

曝光561浏览37