Table of Contents

ExcelWorksheetReader Class

Definition

Namespace
Bodu.Formats.Excel
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

cell ExcelCell

When 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

ProductVersions
.NET8, 10