ExcelBinaryWorkbook Class

Definition

Namespace: Bodu.Formats.Excel

Assembly: Bodu.Formats.Excel.Binary.dll

Package: Bodu.Formats.Excel.Binary 1.0.0

Source: ExcelBinaryWorkbook.cs

Provides a disposable, read-only session over an Excel binary workbook (.xls, BIFF5 as written by Excel 5.0/95 or BIFF8 as written by Excel 97-2003), exposing its sheets and the raw cell values of each.

public sealed class ExcelBinaryWorkbook : IDisposable

Inheritance: object

ExcelBinaryWorkbook

Implements: IDisposable

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods: ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

Opening a workbook reads its globals once - the date system, the shared string table, the format tables, and the sheet directory - while keeping the compound-file container open. A sheet is read 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, high-throughput surface is the forward-only ExcelWorksheetReader returned by OpenWorksheet(int). A materialized, randomly addressable ExcelWorksheet is offered as a convenience through ReadWorksheet(int).

The session owns the underlying container and, unless the caller opts to leave it open, the source stream; dispose the workbook when reading is complete.

using Bodu.Formats.Excel;

using var workbook = ExcelBinaryWorkbook.OpenRead("report.xls");
foreach (ExcelWorksheetInfo info in workbook.Worksheets)
{
    Console.WriteLine($"Sheet '{info.Name}' (#{info.Index})");

    using ExcelWorksheetReader reader = workbook.OpenWorksheet(info.Index);
    while (reader.TryReadCell(out ExcelCell cell))
        Console.WriteLine($"  R{cell.RowIndex} C{cell.ColumnIndex}: {cell.Kind}");
}

Properties

BiffVersion

Gets the BIFF version the workbook stream is encoded in.

public BiffVersion BiffVersion { get; }

Property Value

BiffVersion: Biff5 for an Excel 5.0/95 workbook or Biff8 for an Excel 97-2003 workbook.

DateSystem

Gets the date system the workbook uses to interpret serial date numbers.

public ExcelDateSystem DateSystem { get; }

Property Value

ExcelDateSystem: The declared date system; Excel1900 when the workbook declares none.

Properties

Gets the document properties of the workbook.

public ExcelWorkbookProperties Properties { get; }

Property Value

ExcelWorkbookProperties: The workbook properties; members are null when the corresponding property set is absent or was not read.

Worksheets

Gets the sheets contained in the workbook, in workbook order.

public IReadOnlyList<ExcelWorksheetInfo> Worksheets { get; }

Property Value

IReadOnlyList<ExcelWorksheetInfo>: A read-only list of ExcelWorksheetInfo describing each sheet.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetDateTime(ExcelCell)

Converts a numeric cell to a DateTime using the workbook's date system.

public DateTime? GetDateTime(ExcelCell cell)

Parameters

cell ExcelCell: The cell to convert.

Returns

DateTime?: The date and time represented by the cell's value, or null when the cell is not numeric.

Remarks

The conversion is applied to any numeric cell; inspect IsDateFormatted first when only date-formatted cells should be treated as dates.

Exceptions

ArgumentException: Thrown when the cell's value is outside the range of representable OLE Automation dates.

GetNumberFormatCode(ushort)

Gets the format code for a number-format index, including the well-known built-in formats.

public string? GetNumberFormatCode(ushort formatIndex)

Parameters

formatIndex ushort: The number-format index, as carried by FormatIndex.

Returns

string: The format code, or null when none is known for the index.

Open(Stream, ExcelBinaryReaderOptions)

Opens a workbook over the supplied stream with the specified options.

public static ExcelBinaryWorkbook Open(Stream stream, ExcelBinaryReaderOptions options)

Parameters

stream Stream: The stream containing the .xls file; read from its current position.
options ExcelBinaryReaderOptions: The options governing how the workbook is read.

Returns

ExcelBinaryWorkbook: An open ExcelBinaryWorkbook.

Examples

using Bodu.Formats.Excel;

// Read from a stream that the caller continues to own.
using var source = File.OpenRead("report.xls");
var options = new ExcelBinaryReaderOptions { LeaveOpen = true };
using var workbook = ExcelBinaryWorkbook.Open(source, options);

Exceptions

ArgumentNullException: Thrown when stream or options is null.

OpenRead(FileInfo)

Opens a workbook from a file.

public static ExcelBinaryWorkbook OpenRead(FileInfo file)

Parameters

file FileInfo: The .xls file to open.

Returns

ExcelBinaryWorkbook: An open ExcelBinaryWorkbook.

Exceptions

ArgumentNullException: Thrown when file is null.

OpenRead(Stream, bool)

Opens a workbook over the supplied stream.

public static ExcelBinaryWorkbook OpenRead(Stream stream, bool leaveOpen = false)

Parameters

stream Stream: The stream containing the .xls file; read from its current position.
leaveOpen bool: true to leave stream open when the workbook is disposed; otherwise false.

Returns

ExcelBinaryWorkbook: An open ExcelBinaryWorkbook.

Exceptions

ArgumentNullException: Thrown when stream is null.
CompoundFileFormatException: Thrown when the stream is not a valid compound file.
ExcelBinaryWorkbookStreamNotFoundException: Thrown when the compound file has no workbook stream.
ExcelBinaryFormatException: Thrown when the workbook stream is not valid BIFF.
ExcelBinaryUnsupportedException: Thrown when the workbook is in a BIFF version before BIFF5.
ExcelBinaryEncryptedWorkbookException: Thrown when the workbook is encrypted.

OpenRead(string)

Opens a workbook from a file path.

public static ExcelBinaryWorkbook OpenRead(string path)

Parameters

path string: The path of the .xls file.

Returns

ExcelBinaryWorkbook: An open ExcelBinaryWorkbook.

Examples

using Bodu.Formats.Excel;

using var workbook = ExcelBinaryWorkbook.OpenRead("report.xls");
Console.WriteLine($"{workbook.Worksheets.Count} sheet(s), date system: {workbook.DateSystem}");

Exceptions

ArgumentNullException: Thrown when path is null.
CompoundFileFormatException: Thrown when the file is not a valid compound file.
ExcelBinaryWorkbookStreamNotFoundException: Thrown when the compound file has no workbook stream.
ExcelBinaryFormatException: Thrown when the workbook stream is not valid BIFF.
ExcelBinaryUnsupportedException: Thrown when the workbook is in a BIFF version before BIFF5.
ExcelBinaryEncryptedWorkbookException: Thrown when the workbook is encrypted.

OpenRead(string, ExcelBinaryReaderOptions)

Opens a workbook from a file path with the specified options.

public static ExcelBinaryWorkbook OpenRead(string path, ExcelBinaryReaderOptions options)

Parameters

path string: The path of the .xls file.
options ExcelBinaryReaderOptions: The options governing how the workbook is read.

Returns

ExcelBinaryWorkbook: An open ExcelBinaryWorkbook.

Examples

using Bodu.Formats.Excel;

// Skip document properties and date-format detection for a fast, numeric-only read.
var options = new ExcelBinaryReaderOptions { ReadDocumentProperties = false, DetectDateFormats = false };
using var workbook = ExcelBinaryWorkbook.OpenRead("data.xls", options);

Exceptions

ArgumentNullException: Thrown when path or options is null.

OpenWorksheet(int)

Opens a forward-only reader over the sheet at the specified index.

public ExcelWorksheetReader OpenWorksheet(int worksheetIndex)

Parameters

worksheetIndex int: The zero-based sheet index.

Returns

ExcelWorksheetReader: A forward-only ExcelWorksheetReader over the sheet's value records.

Examples

using Bodu.Formats.Excel;

using var workbook = ExcelBinaryWorkbook.OpenRead("report.xls");
using ExcelWorksheetReader reader = workbook.OpenWorksheet(0);
while (reader.TryReadCell(out ExcelCell cell))
{
    if (cell.Kind == ExcelCellKind.Number)
        Console.WriteLine($"R{cell.RowIndex} C{cell.ColumnIndex} = {cell.NumberValue}");
}

Exceptions

ArgumentOutOfRangeException: Thrown when worksheetIndex is out of range.
ExcelBinaryFormatException: Thrown when the sheet substream is malformed.
ObjectDisposedException: Thrown when the workbook has been disposed.

OpenWorksheet(string)

Opens a forward-only reader over the sheet with the specified name.

public ExcelWorksheetReader OpenWorksheet(string worksheetName)

Parameters

worksheetName string: The sheet name, compared using ordinal equality.

Returns

ExcelWorksheetReader: A forward-only ExcelWorksheetReader over the sheet's value records.

Exceptions

ArgumentNullException: Thrown when worksheetName is null.
KeyNotFoundException: Thrown when no sheet with the given name exists.
ObjectDisposedException: Thrown when the workbook has been disposed.

ReadWorksheet(int)

Reads the sheet at the specified index into a materialized, randomly addressable view.

public ExcelWorksheet ReadWorksheet(int worksheetIndex)

Parameters

worksheetIndex int: The zero-based sheet index.

Returns

ExcelWorksheet: A materialized ExcelWorksheet buffering the sheet's populated cells.

Examples

using Bodu.Formats.Excel;

using var workbook = ExcelBinaryWorkbook.OpenRead("report.xls");
ExcelWorksheet sheet = workbook.ReadWorksheet(0);
if (sheet.TryGetCell(0, 0, out ExcelCell a1))
    Console.WriteLine($"A1 = {a1.StringValue ?? a1.NumberValue?.ToString()}");

Exceptions

ArgumentOutOfRangeException: Thrown when worksheetIndex is out of range.
ExcelBinaryFormatException: Thrown when the sheet substream is malformed.
ObjectDisposedException: Thrown when the workbook has been disposed.

ReadWorksheet(string)

Reads the sheet with the specified name into a materialized, randomly addressable view.

public ExcelWorksheet ReadWorksheet(string worksheetName)

Parameters

worksheetName string: The sheet name, compared using ordinal equality.

Returns

ExcelWorksheet: A materialized ExcelWorksheet buffering the sheet's populated cells.

Exceptions

ArgumentNullException: Thrown when worksheetName is null.
KeyNotFoundException: Thrown when no sheet with the given name exists.
ObjectDisposedException: Thrown when the workbook has been disposed.

Applies to

Product	Versions
.NET	8, 10

Table of Contents

ExcelBinaryWorkbook Class

Definition

Remarks

Properties

BiffVersion

Property Value

DateSystem

Property Value

Properties

Property Value

Worksheets

Property Value

Methods

Dispose()

GetDateTime(ExcelCell)

Parameters

Returns

Remarks

Exceptions

GetNumberFormatCode(ushort)

Parameters

Returns

Open(Stream, ExcelBinaryReaderOptions)

Parameters

Returns

Examples

Exceptions

OpenRead(FileInfo)

Parameters

Returns

Exceptions

OpenRead(Stream, bool)

Parameters

Returns

Exceptions

OpenRead(string)

Parameters

Returns

Examples

Exceptions

OpenRead(string, ExcelBinaryReaderOptions)

Parameters

Returns

Examples

Exceptions

OpenWorksheet(int)

Parameters

Returns

Examples

Exceptions

OpenWorksheet(string)

Parameters

Returns

Exceptions

ReadWorksheet(int)

Parameters

Returns

Examples

Exceptions

ReadWorksheet(string)

Parameters

Returns

Exceptions

Applies to