跳转至

24. 异常处理

本章介绍异常分层、常见异常场景与捕获建议。


24.1 异常分层

  • LiteExcelException:库所有异常的基类。
  • LiteXlsxException:旧异常名称的兼容别名([Obsolete],请改用 LiteExcelException)。
  • InvalidSheetNameException:当 Sheet 名不合法(为空、超过 31 字符、包含非法字符)时抛出,含 SheetName 属性。

非法 Sheet 名在写出时抛出(SheetName 携带原始名称):

var sheet = new SheetData { SheetName = "非法?名称" };
try
{
    Excel.Write("bad.xlsx", sheet);
}
catch (InvalidSheetNameException ex)
{
    Console.WriteLine($"非法 Sheet 名:{ex.SheetName}");
}

输出:

非法 Sheet 名:非法?名称

24.2 常见异常场景

场景 异常
文件不存在 FileNotFoundException
路径为空 ArgumentException
工作表名重复 / 找不到 LiteExcelException
Sheet 名非法 InvalidSheetNameException
保存路径扩展名与格式不匹配 LiteExcelException
新建簿未指定路径就 Save LiteExcelException
只读工作簿(有修改密码未授权)保存 LiteExcelException
带密码保存为 csv / xls LiteExcelException
含宏保存为 xlsx / xls LiteExcelException
流式读取 / 追加非 xlsx/xlsm LiteExcelException
CSV 多表写出 NotSupportedException
单元格类型不匹配强类型读取 InvalidCastException

典型捕获顺序(先具体异常后基类):

var wb = Excel.Create();
try
{
    wb.Save();   // 新建簿未指定路径就保存
}
catch (LiteExcelException ex)
{
    Console.WriteLine(ex.Message);
}

输出:

当前工作簿没有目标路径,请使用 SaveAs 指定保存位置

24.3 建议

try
{
    var wb = Excel.Open("report.xlsx", new ExcelReadOptions { OpenPassword = "secret" });
    wb.SaveAs("out.xlsx");
}
catch (LiteExcelException ex)
{
    Console.WriteLine($"LiteExcel: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"Other: {ex.Message}");
}