Bodu.Formats.Excel.Binary 1.3.0

Bodu.Formats.Excel.Binary

API stability - Stable. The public API surface is committed: breaking changes are reserved for a major-version bump per SemVer, except a deliberate break that is recorded in the release notes and in the package's CompatibilitySuppressions.xml. See versioning and support.

A narrow, read-only reader for the Excel binary workbook format (.xls): BIFF8, as written by Excel 97-2003, and BIFF5, the Excel 5.0/95 format. BIFF5 is read from the format's documented record layouts and tested against synthesized workbooks; no workbook written by Excel 5.0/95 itself is among the test fixtures. The reader exposes the raw cell values of each worksheet - strings, numbers, booleans, and errors - and nothing more. There is no formula evaluation, styling, charting, or date inference; turning a numeric cell into a date or a column into a record is the caller's job.

Built on Bodu.IO.Compound for the underlying container and on Bodu.IO.Biff for the record stream inside it.

A workbook is opened as a disposable, read-only session that keeps the container open and reads each sheet on demand by seeking to the stream offset its bound-sheet record records, so a single sheet can be read without parsing the others and the whole workbook is never materialized. The primary surface is the forward-only ExcelWorksheetReader; a materialized, randomly addressable ExcelWorksheet is offered as a convenience.

using Bodu.Formats.Excel;

using ExcelBinaryWorkbook workbook = ExcelBinaryWorkbook.OpenRead(path);

foreach (ExcelWorksheetInfo sheet in workbook.Worksheets)
    Console.WriteLine($"{sheet.Index}: {sheet.Name} ({sheet.Visibility}, {sheet.Type})");

// Primary, low-allocation forward scan.
using ExcelWorksheetReader reader = workbook.OpenWorksheet("Data");
while (reader.TryReadCell(out ExcelCell cell))
{
    switch (cell.Kind)
    {
        case ExcelCellKind.String: /* cell.StringValue */ break;
        case ExcelCellKind.Number: /* cell.NumberValue */ break;
        case ExcelCellKind.Boolean: /* cell.BooleanValue */ break;
    }
}

// Convenience, materialized random access.
ExcelWorksheet data = workbook.ReadWorksheet("Data");
if (data.TryGetCell(11, 0, out ExcelCell rate)) { /* ... */ }

// A caller that knows a column holds dates can convert a numeric cell:
DateOnly date = ExcelSerialDate.FromSerialDate(rate.NumberValue!.Value);

For a numeric, time-series workload, ExcelBinaryReaderOptions can skip optional metadata work:

using ExcelBinaryWorkbook workbook = ExcelBinaryWorkbook.Open(stream, new ExcelBinaryReaderOptions
{
    ReadDocumentProperties = false,
    DetectDateFormats = false,
});

Records handled

BOF / EOF (substream boundaries, counted in pairs: a sheet ends at the EOF that matches its own BOF, or, without one, where the next sheet's substream begins, and a chart substream nested in a worksheet is skipped, so its data cache is never read as cells), BOUNDSHEET8 (sheet directory, with lbPlyPos offset, sheet type, and hidden state), SST (+ CONTINUE for split strings), LABELSST, LABEL, RSTRING (rich text, read as a text cell), NUMBER, RK, MULRK, BOOLERR, FORMULA (cached result, with a trailing STRING record, and the CONTINUE records of a long text, for a string result), XF / FORMAT (number formats), DATEMODE, and DIMENSIONS. BLANK / MULBLANK and unrecognized records are skipped. Malformed records fail with ExcelBinaryFormatException: in the workbook globals when the workbook is opened, in a sheet when that sheet is opened or read.

Runnable samples

The repository ships an offline, dotnet run-able sample for this package - the workbook session and sheet directory, forward-only streaming, the materialized worksheet surface, and format-classified serial-date decoding against a workbook the sample generates - under samples/Formats.Excel/.

Out of scope

Formulas, styles, charts, pivot tables, macros, named ranges, and writing .xls files.

Part of the Bodu utility library.