ExcelWorksheetReader Class
Definition
- Assembly
- Bodu.Formats.Excel.Binary.dll
- Package
- Bodu.Formats.Excel.Binary 1.3.0
- Source
- ExcelWorksheetReader.cs
Provides a forward-only, low-allocation reader over the populated cells of a single worksheet substream.
public sealed class ExcelWorksheetReader : IDisposable
- Inheritance
-
ExcelWorksheetReader
- Implements
- Inherited Members
- Extension Methods
Remarks
This is the high-throughput surface: the worksheet's substream is read once into a buffer, and cells are decoded on demand through TryReadCell(out ExcelCell) without building an intermediate record list or a position-keyed map. Only value-bearing records are surfaced (text, number, boolean, and error cells, including the cached result of a formula cell); blank cells and uninterpreted records are skipped, so the sequence is sparse and in record order.
Only a sheet whose Type is Worksheet yields cells. A
chart, macro sheet, Visual Basic module or sheet of unknown type yields none, as ExcelSheetType
states: the NUMBER and LABEL records of a chart substream are its data cache ([MS-XLS] 2.2.3.2), not
cells. For the same reason, a substream nested in the worksheet, such as a chart embedded after its OBJ
record ([MS-XLS] 2.1.7.20.6), is skipped from its BOF record to the EOF record that matches it, and
the worksheet's cells after it are read as usual. Only the EOF record that matches the worksheet's own
BOF record ends the worksheet; a worksheet without one ends where the next sheet's substream begins.
For random access by position, materialize the worksheet instead with ReadWorksheet(int).
using Bodu.Formats.Excel;
using var workbook = ExcelBinaryWorkbook.OpenRead("report.xls");
using ExcelWorksheetReader reader = workbook.OpenWorksheet(0);
while (reader.TryReadCell(out ExcelCell cell))
{
string value = cell.Kind switch
{
ExcelCellKind.String => cell.StringValue ?? string.Empty,
ExcelCellKind.Number => cell.NumberValue?.ToString() ?? string.Empty,
ExcelCellKind.Boolean => cell.BooleanValue?.ToString() ?? string.Empty,
ExcelCellKind.Error => cell.ErrorValue?.ToString() ?? string.Empty,
_ => string.Empty,
};
Console.WriteLine($"R{cell.RowIndex} C{cell.ColumnIndex}: {value}");
}
Properties
Worksheet
Gets the descriptor of the worksheet being read.
public ExcelWorksheetInfo Worksheet { get; }
Property Value
- ExcelWorksheetInfo
The worksheet's name, index, visibility, type, and declared used range.
Methods
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
ReadCells()
Enumerates the remaining populated cells of the worksheet, in record order.
public IEnumerable<ExcelCell> ReadCells()
Returns
- IEnumerable<ExcelCell>
A lazy sequence of the worksheet's populated cells.
Exceptions
- ExcelBinaryFormatException
Thrown when a cell record is malformed.
- ExcelBinaryUnsupportedException
Thrown when the worksheet's beginning-of-file record declares a BIFF version other than BIFF5 or BIFF8.
- ObjectDisposedException
Thrown when the reader has been disposed.
ReadRows()
Enumerates the remaining populated rows of the worksheet, grouping cells by row as they are read.
public IEnumerable<ExcelRow> ReadRows()
Returns
- IEnumerable<ExcelRow>
A lazy sequence of the worksheet's populated rows, in the order their cells appear.
Remarks
Cells are grouped into a row while their row index does not change; a new row is started when the row index advances. Excel writes cells in row-major order, so this groups a producer's rows without buffering the whole worksheet.
Exceptions
- ExcelBinaryFormatException
Thrown when a cell record is malformed.
- ExcelBinaryUnsupportedException
Thrown when the worksheet's beginning-of-file record declares a BIFF version other than BIFF5 or BIFF8.
- ObjectDisposedException
Thrown when the reader has been disposed.
TryReadCell(out ExcelCell)
Attempts to read the next populated cell of the worksheet.
public bool TryReadCell(out ExcelCell cell)
Parameters
cellExcelCellWhen this method returns, the next populated cell when one is available.
Returns
- bool
true when a cell was read; false at the end of the worksheet, and at once for a sheet that is not a worksheet.
Exceptions
- ExcelBinaryFormatException
Thrown when a cell record is malformed.
- ExcelBinaryUnsupportedException
Thrown when the worksheet's beginning-of-file record declares a BIFF version other than BIFF5 or BIFF8.
- ObjectDisposedException
Thrown when the reader has been disposed.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |