ExcelDataReader快速上手指南：高效读取Excel文件的完整教程
项目地址: https://gitcode.com/gh_mirrors/ex/ExcelDataReader ExcelDataReader是一个轻量级且高效的C#库，专门用于读取Microsoft Excel文件（包括XLS、XLSX、XLSB格式）。本指南将帮助您快速掌握这个强大的工具，让数据处理变得简单高效。
项目结构解析
深入了解ExcelDataReader的目录布局，快速找到您需要的核心组件：
- src/ExcelDataReader - 核心库，提供低级别的Excel文件读取功能
- src/ExcelDataReader.DataSet - 扩展库，支持将读取的数据填充到DataSet中
- src/ExcelDataReader.Tests - 完整的测试套件确保稳定性
- src/ExcelDataReader.Sample - 实用示例代码库
- src/TestData - 丰富的测试数据文件集合
快速启动与初始化
依赖管理
通过NuGet包管理器轻松添加引用：
<PackageReference Include="ExcelDataReader" Version="3.6.0" />
如果需要使用DataSet扩展功能，还需要添加：
<PackageReference Include="ExcelDataReader.DataSet" Version="3.6.0" />
基础读取示例
核心读取流程简单直观，只需几行代码即可开始处理Excel数据：
using (var stream = File.Open(filePath, FileMode.Open, FileAccess.Read))
{
// 自动检测格式，支持：
// - 二进制Excel文件（2.0-2003格式；*.xls）
// - OpenXml Excel文件（2007格式；*.xlsx、*.xlsb）
using (var reader = ExcelReaderFactory.CreateReader(stream))
{
// 选择以下两种方式之一：
// 1. 使用读取器方法
do
{
while (reader.Read())
{
// 读取数据，例如：reader.GetDouble(0);
}
} while (reader.NextResult());
// 2. 使用AsDataSet扩展方法
var result = reader.AsDataSet();
// 每个工作表的结果都在result.Tables中
}
}
支持的Excel文件格式
ExcelDataReader支持广泛的Excel文件格式和版本：
- .xlsx - OpenXml格式，Excel 2007及更新版本
- .xlsb - OpenXml格式，Excel 2007及更新版本
- .xls - BIFF8格式，Excel 97、2000、XP、2003
- .xls - BIFF5格式，Excel 5.0、95
- .xls - BIFF4格式，Excel 4.0
- .xls - BIFF2格式，Excel 2.0、2.2
- .csv - 逗号分隔值文件
灵活配置选项
CreateReader配置选项
ExcelReaderFactory.CreateReader()方法接受可选配置对象来修改读取器行为：
var reader = ExcelReaderFactory.CreateReader(stream, new ExcelReaderConfiguration()
{
// 当输入XLS缺少CodePage记录，或CSV缺少BOM且不能解析为UTF8时使用的编码
FallbackEncoding = Encoding.GetEncoding(1252),
// 用于打开受密码保护的工作簿的密码
Password = "password",
// CSV分隔符候选数组，读取器会自动检测最适合输入数据的分隔符
AutodetectSeparators = new char[] { ',', ';', '\t', '|', '#' },
// 是否修剪CSV值的空白（默认为true）
TrimWhiteSpace = true,
// 在IExcelDataReader对象被释放后是否保持流打开
LeaveOpen = false,
});
AsDataSet配置选项
AsDataSet()方法接受可选配置对象来修改DataSet转换行为：
var result = reader.AsDataSet(new ExcelDataSetConfiguration()
{
// 是否在第二遍中设置DataColumn.DataType属性
UseColumnDataType = true,
// 回调函数确定是否在当前DataSet中包含当前工作表
FilterSheet = (tableReader, sheetIndex) => true,
// 获取DataTable配置选项的回调
ConfigureDataTable = (tableReader) => new ExcelDataTableConfiguration()
{
// 生成的列名称的前缀
EmptyColumnNamePrefix = "Column",
// 是否使用数据中的行作为列名
UseHeaderRow = false,
// 确定哪一行是标题行的回调
ReadHeaderRow = (rowReader) => {
// 例如跳过第一行并使用第二行作为列标题：
rowReader.Read();
},
// 确定是否在当前DataTable中包含当前行的回调
FilterRow = (rowReader) => {
return true;
},
// 确定是否在DataTable中包含特定列的回调
FilterColumn = (rowReader, columnIndex) => {
return true;
}
}
});
读取CSV文件
使用ExcelReaderFactory.CreateCsvReader而不是CreateReader来解析纯文本逗号分隔值流：
using (var reader = ExcelReaderFactory.CreateCsvReader(stream))
{
// 处理CSV数据
}
核心读取器方法
AsDataSet()扩展方法是一个方便的助手，可以快速获取数据，但并不总是可用或理想使用。IExcelDataReader扩展了System.Data.IDataReader和IDataRecord接口，以在较低级别导航和检索数据。最重要的读取器方法和属性：
| 方法/属性 | 描述 |
|---|---|
Read() | 从当前工作表中读取一行 |
NextResult() | 将游标前进到下一个工作表 |
ResultsCount | 返回当前工作簿中的工作表数量 |
Name | 返回当前工作表的名称 |
CodeName | 返回当前工作表的VBA代码名称标识符 |
FieldCount | 返回当前工作表中的列数 |
RowCount | 返回当前工作表中的行数 |
重要升级说明
从ExcelDataReader 2.x升级到3.x时，需要注意以下重要变更：
修复方法
-
确保将代码中的任何
Excel命名空间引用重命名为新命名空间ExcelDataReader -
确保项目具有对
ExcelDataReader.DataSet包的引用才能使用AsDataSet() -
删除带有
IsFirstRowAsColumnNames的代码行，并将AsDataSet()调用更改为：
var result = reader.AsDataSet(new ExcelDataSetConfiguration()
{
ConfigureDataTable = (_) => new ExcelDataTableConfiguration()
{
UseHeaderRow = true
}
});
.NET Core重要说明
默认情况下，ExcelDataReader在.NET Core和.NET 5.0或更高版本上会抛出"没有可用于编码1252的数据"的NotSupportedException。
要修复此问题，请添加对System.Text.Encoding.CodePages包的依赖，然后在应用程序初始化期间添加代码注册代码页提供程序：
System.Text.Encoding.RegisterProvider(System.Text.CodePagesEncodingProvider.Instance);
实用示例代码
以下是项目中提供的实际使用示例：
private void Button2Click(object sender, EventArgs e)
{
try
{
using var stream = new FileStream(textBox1.Text, FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
using IExcelDataReader reader = string.Equals(Path.GetExtension(textBox1.Text), ".csv", StringComparison.OrdinalIgnoreCase) ?
ExcelReaderFactory.CreateCsvReader(stream) : ExcelReaderFactory.CreateReader(stream);
var ds = reader.AsDataSet(new ExcelDataSetConfiguration()
{
UseColumnDataType = false,
ConfigureDataTable = (tableReader) => new ExcelDataTableConfiguration()
{
UseHeaderRow = firstRowNamesCheckBox.Checked
}
});
}
catch (Exception ex)
{
MessageBox.Show(ex.ToString(), ex.Message, MessageBoxButtons.OK, MessageBoxIcon.Error);
}
}
总结
ExcelDataReader提供了简单而强大的方式来读取Excel文件，支持多种格式和灵活的配置选项。通过本指南，您可以快速开始使用这个库来处理各种Excel数据需求。
关键优势：
- 轻量级且高效
- 无需安装Microsoft Office
- 支持广泛的Excel版本和格式
- 提供DataSet和DataReader两种数据访问方式
- 丰富的配置选项满足不同场景需求
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
