Class Excel

Namespace

ExcelReader.Core.Reader

Assembly

ExcelReader.Core.dll

Entry point for opening Excel and CSV workbooks. Open(string, ExcelReaderOptions?)/ Open(Stream, bool, ExcelReaderOptions?) and their async counterparts auto-detect XLSX/XLSB/XLS from the file's signature and return a format-agnostic IExcelWorkbook; the From*/FromXls*/FromXlsb*/FromCsv* methods open a specific, known format directly.

public static class Excel

Inheritance

object

Excel

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

DetectFileFormat(Stream)

Detects a workbook's file format (XLSX/XLSB/XLS/unknown) from a seekable stream's signature, without consuming it.

public static ExcelFileFormat DetectFileFormat(Stream stream)

Parameters

stream Stream

A seekable stream containing the workbook data. The stream's position is restored after detection.

Returns

ExcelFileFormat

The detected ExcelFileFormat, or Unknown if the signature matches no supported format.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream does not support seeking.

DetectFileFormat(ReadOnlyMemory<byte>)

Detects a workbook's file format (XLSX/XLSB/XLS/unknown) from an in-memory buffer's signature, without consuming it.

public static ExcelFileFormat DetectFileFormat(ReadOnlyMemory<byte> data)

Parameters

data ReadOnlyMemory<byte>

A buffer containing the workbook data.

Returns

ExcelFileFormat

The detected ExcelFileFormat, or Unknown if the signature matches no supported format.

DetectFileFormatAsync(Stream, CancellationToken)

Asynchronously detects a workbook's file format (XLSX/XLSB/XLS/unknown) from a seekable stream's signature, without consuming it.

public static ValueTask<ExcelFileFormat> DetectFileFormatAsync(Stream stream, CancellationToken ct = default)

Parameters

stream Stream

A seekable stream containing the workbook data. The stream's position is restored after detection.

ct CancellationToken

A token to cancel the detection operation.

Returns

ValueTask<ExcelFileFormat>

The detected ExcelFileFormat, or Unknown if the signature matches no supported format.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream does not support seeking.

EncryptPackage(Stream, Stream, ExcelPassword)

Wraps a finished plaintext OOXML package (XLSX or XLSB) in a password-encrypted CFB container, using agile encryption (ECMA-376 4.4): AES-256-CBC, SHA-512, 100,000 spin iterations, with a dataIntegrity HMAC.

public static void EncryptPackage(Stream package, Stream destination, ExcelPassword password)

Parameters

package Stream

The plaintext package, positioned at its first byte. Must be readable and seekable — it is read twice. Not disposed by this method.

destination Stream

Where the encrypted container is written. Need not be seekable. Not disposed by this method.

password ExcelPassword

The password required to open the result.

Exceptions

ArgumentNullException

Any argument is null.

ArgumentException

package is unreadable, not seekable, empty, or does not begin with the PK\x03\x04 package signature; or password is empty.

EncryptPackage(string, string, ExcelPassword)

Reads the plaintext package at packagePath and writes its encrypted counterpart to destinationPath, overwriting an existing file.

public static void EncryptPackage(string packagePath, string destinationPath, ExcelPassword password)

Parameters

packagePath string

Path to the plaintext XLSX/XLSB package.

destinationPath string

Path to write the encrypted workbook to.

password ExcelPassword

The password required to open the result.

Exceptions

ArgumentException

packagePath or destinationPath is null or empty; or the package at packagePath is unreadable, empty, or does not begin with the PK\x03\x04 package signature; or password is empty.

EncryptPackageAsync(Stream, Stream, ExcelPassword, CancellationToken)

Asynchronous counterpart to EncryptPackage(Stream, Stream, ExcelPassword).

public static ValueTask EncryptPackageAsync(Stream package, Stream destination, ExcelPassword password, CancellationToken ct = default)

Parameters

package Stream

The plaintext package. Must be readable and seekable; not disposed here.

destination Stream

Where the encrypted container is written; not disposed here.

password ExcelPassword

The password required to open the result.

ct CancellationToken

A token to cancel the operation.

Returns

ValueTask

Exceptions

ArgumentNullException

Any argument is null.

ArgumentException

package is unreadable, not seekable, empty, or does not begin with the PK\x03\x04 package signature; or password is empty.

EncryptPackageAsync(string, string, ExcelPassword, CancellationToken)

Asynchronous counterpart to EncryptPackage(string, string, ExcelPassword).

public static ValueTask EncryptPackageAsync(string packagePath, string destinationPath, ExcelPassword password, CancellationToken ct = default)

Parameters

packagePath string

Path to the plaintext XLSX/XLSB package.

destinationPath string

Path to write the encrypted workbook to.

password ExcelPassword

The password required to open the result.

ct CancellationToken

A token to cancel the operation.

Returns

ValueTask

Exceptions

ArgumentException

packagePath or destinationPath is null or empty; or the package at packagePath is unreadable, empty, or does not begin with the PK\x03\x04 package signature; or password is empty.

FromCsv(Stream, bool, ExcelReaderOptions?)

Opens a CSV (or other delimited-text) source from an existing stream.

public static CsvReader FromCsv(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null)

Parameters

stream Stream

The stream containing the CSV data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Size limits and interning, plus the delimiter, quote and encoding in Csv; Default when null.

Returns

CsvReader

FromCsv(ReadOnlyMemory<byte>, ExcelReaderOptions?)

Opens a CSV (or other delimited-text) source directly from an in-memory buffer.

public static CsvReader FromCsv(ReadOnlyMemory<byte> data, ExcelReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The whole CSV source's bytes. Must stay valid and unmodified until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Size limits and interning, plus the delimiter, quote and encoding in Csv; Default when null.

Returns

CsvReader

FromCsvAsync(Stream, bool, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a CSV (or other delimited-text) source from an existing stream.

public static ValueTask<CsvReader> FromCsvAsync(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

stream Stream

The stream containing the CSV data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Size limits and interning, plus the delimiter, quote and encoding in Csv; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<CsvReader>

FromCsvFile(string, ExcelReaderOptions?)

Opens a CSV (or other delimited-text) source from a file path, taking ownership of the file stream.

public static CsvReader FromCsvFile(string path, ExcelReaderOptions? options = null)

Parameters

path string

The path to the CSV file.

options ExcelReaderOptions

Size limits and interning, plus the delimiter, quote and encoding in Csv; Default when null.

Returns

CsvReader

FromCsvFileAsync(string, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a CSV (or other delimited-text) source from a file path, taking ownership of the file stream.

public static ValueTask<CsvReader> FromCsvFileAsync(string path, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

path string

The path to the CSV file.

options ExcelReaderOptions

Size limits and interning, plus the delimiter, quote and encoding in Csv; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<CsvReader>

FromXls(Stream, bool, ExcelReaderOptions?)

Opens a legacy binary (XLS) workbook from an existing stream.

public static XlsWorkbook FromXls(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null)

Parameters

stream Stream

The stream containing the XLS data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

XlsWorkbook

FromXls(ReadOnlyMemory<byte>, ExcelReaderOptions?)

Opens a legacy binary (XLS) workbook directly from an in-memory buffer.

public static XlsWorkbook FromXls(ReadOnlyMemory<byte> data, ExcelReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The whole XLS file's bytes. Must stay valid and unmodified until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

XlsWorkbook

FromXlsAsync(Stream, bool, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a legacy binary (XLS) workbook from an existing stream.

public static ValueTask<XlsWorkbook> FromXlsAsync(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

stream Stream

The stream containing the XLS data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<XlsWorkbook>

FromXlsFile(string, ExcelReaderOptions?)

Opens a legacy binary (XLS) workbook from a file path, taking ownership of the file stream.

public static XlsWorkbook FromXlsFile(string path, ExcelReaderOptions? options = null)

Parameters

path string

The path to the XLS file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

XlsWorkbook

FromXlsFileAsync(string, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a legacy binary (XLS) workbook from a file path, taking ownership of the file stream.

public static ValueTask<XlsWorkbook> FromXlsFileAsync(string path, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

path string

The path to the XLS file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<XlsWorkbook>

FromXlsb(Stream, bool, ExcelReaderOptions?)

Opens an XLSB (Excel binary) workbook from an existing stream.

public static XlsbWorkbook FromXlsb(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null)

Parameters

stream Stream

The stream containing the XLSB data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

XlsbWorkbook

FromXlsb(ReadOnlyMemory<byte>, ExcelReaderOptions?)

Opens an XLSB workbook directly from an in-memory buffer. Reads the ZIP central directory without a ZipArchive. Small parts (workbook, styles, shared strings) are decompressed whole; each sheet is decompressed as it is enumerated. Nothing waits on I/O, so without PrefetchDecompression enumeration never suspends, even under await foreach.

public static XlsbWorkbook FromXlsb(ReadOnlyMemory<byte> data, ExcelReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The whole XLSB file's bytes. Must stay valid and unmodified until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null. PrefetchDecompression applies here too: a background thread inflates each sheet ahead of the parser, and async enumeration may then wait for it.

Returns

XlsbWorkbook

FromXlsbAsync(Stream, bool, ExcelReaderOptions?, CancellationToken)

Asynchronously opens an XLSB (Excel binary) workbook from an existing stream.

public static ValueTask<XlsbWorkbook> FromXlsbAsync(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

stream Stream

The stream containing the XLSB data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<XlsbWorkbook>

FromXlsbFile(string, ExcelReaderOptions?)

Opens an XLSB (Excel binary) workbook from a file path, taking ownership of the file stream.

public static XlsbWorkbook FromXlsbFile(string path, ExcelReaderOptions? options = null)

Parameters

path string

The path to the XLSB file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

XlsbWorkbook

FromXlsbFileAsync(string, ExcelReaderOptions?, CancellationToken)

Asynchronously opens an XLSB (Excel binary) workbook from a file path, taking ownership of the file stream.

public static ValueTask<XlsbWorkbook> FromXlsbFileAsync(string path, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

path string

The path to the XLSB file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<XlsbWorkbook>

FromXlsx(Stream, bool, ExcelReaderOptions?)

Opens an XLSX workbook from an existing stream.

public static XlsxWorkbook FromXlsx(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null)

Parameters

stream Stream

The stream containing the XLSX data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

XlsxWorkbook

FromXlsx(ReadOnlyMemory<byte>, ExcelReaderOptions?)

Opens an XLSX workbook directly from an in-memory buffer. Reads the ZIP central directory without a ZipArchive. Small parts (workbook, styles, shared strings) are decompressed whole; each sheet is decompressed as it is enumerated. Nothing waits on I/O, so without PrefetchDecompression enumeration never suspends, even under await foreach.

public static XlsxWorkbook FromXlsx(ReadOnlyMemory<byte> data, ExcelReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The whole XLSX file's bytes. Must stay valid and unmodified until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null. PrefetchDecompression applies here too: a background thread inflates each sheet ahead of the parser, and async enumeration may then wait for it.

Returns

XlsxWorkbook

FromXlsxAsync(Stream, bool, ExcelReaderOptions?, CancellationToken)

Asynchronously opens an XLSX workbook from an existing stream.

public static ValueTask<XlsxWorkbook> FromXlsxAsync(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

stream Stream

The stream containing the XLSX data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<XlsxWorkbook>

FromXlsxFile(string, ExcelReaderOptions?)

Opens an XLSX workbook from a file path, taking ownership of the file stream.

public static XlsxWorkbook FromXlsxFile(string path, ExcelReaderOptions? options = null)

Parameters

path string

The path to the XLSX file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

XlsxWorkbook

FromXlsxFileAsync(string, ExcelReaderOptions?, CancellationToken)

Asynchronously opens an XLSX workbook from a file path, taking ownership of the file stream.

public static ValueTask<XlsxWorkbook> FromXlsxFileAsync(string path, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

path string

The path to the XLSX file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<XlsxWorkbook>

InferSchema(IExcelSheet, SchemaInferenceOptions?)

Guesses a column schema for sheet by sampling it from the first row.

public static IReadOnlyList<ExcelColumnSchema> InferSchema(IExcelSheet sheet, SchemaInferenceOptions? options = null)

Parameters

sheet IExcelSheet

The sheet to sample. A new enumerator is opened and disposed; no other read of the sheet is disturbed.

options SchemaInferenceOptions

Header row, sample size and text parsing; Default when null.

Returns

IReadOnlyList<ExcelColumnSchema>

One ExcelColumnSchema per column, in column order.

Remarks

This is a guess over a bounded sample, not a guarantee about the whole sheet — a column whose first SampleSize rows are all integers is reported as Int64Column even if row 10,000 holds text. Verify it fits before trusting it, and feed the result into Build<T>(Action<ExcelRowMapBuilder<T>>, ExcelParserOptions?) to build a real map.

Exceptions

ArgumentNullException

sheet is null.

ArgumentOutOfRangeException

HeaderRow is negative, or SampleSize is not positive.

ArgumentException

The sheet has fewer rows than HeaderRow.

InvalidOperationException

HeaderRow is positive and sheet is a table view (AsSheet()) of a table without a header row.

Open(Stream, ExcelFileFormat, bool, ExcelReaderOptions?)

Opens a workbook of a known format from an existing stream.

public static IExcelWorkbook Open(Stream stream, ExcelFileFormat format, bool leaveOpen = true, ExcelReaderOptions? options = null)

Parameters

stream Stream

The stream containing the workbook data. Must be seekable when format is Unknown.

format ExcelFileFormat

The format to read stream as. Unknown auto-detects XLSX/XLSB/XLS from the signature.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null. Csv supplies the dialect when format is Csv.

Returns

IExcelWorkbook

A format-agnostic IExcelWorkbook.

Exceptions

ArgumentNullException

stream is null.

ArgumentOutOfRangeException

format is EncryptedOoxml or not a defined value.

ArgumentException

format is Unknown and stream does not support seeking.

InvalidDataException

format is Unknown and the stream's signature matches no supported format.

Open(Stream, bool, ExcelReaderOptions?)

Opens a workbook from an existing seekable stream, auto-detecting its format (XLSX/XLSB/XLS) from the stream's signature.

public static IExcelWorkbook Open(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null)

Parameters

stream Stream

A seekable stream containing the workbook data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

IExcelWorkbook

A format-agnostic IExcelWorkbook backed by the concrete workbook that matches the detected format.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream does not support seeking.

InvalidDataException

The stream's signature does not match a supported format.

Open(ReadOnlyMemory<byte>, ExcelFileFormat, ExcelReaderOptions?)

Opens a workbook of a known format from an in-memory buffer.

public static IExcelWorkbook Open(ReadOnlyMemory<byte> data, ExcelFileFormat format, ExcelReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The whole source's bytes. Must stay valid and unmodified until the workbook and every enumerator obtained from it are disposed.

format ExcelFileFormat

The format to read data as. Unknown auto-detects XLSX/XLSB/XLS from the signature.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null. Csv supplies the dialect when format is Csv.

Returns

IExcelWorkbook

A format-agnostic IExcelWorkbook.

Exceptions

ArgumentOutOfRangeException

format is EncryptedOoxml or not a defined value.

InvalidDataException

format is Unknown and the buffer's signature matches no supported format.

Open(ReadOnlyMemory<byte>, ExcelReaderOptions?)

Opens a workbook from an in-memory buffer, auto-detecting its format (XLSX/XLSB/XLS) from its signature. XLSX/XLSB route through ExcelReader.Core.Reader.Zip.ZipIndex instead of a ZipArchive/Stream, so the returned workbook never suspends, even under await foreach.

public static IExcelWorkbook Open(ReadOnlyMemory<byte> data, ExcelReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The whole workbook file's bytes. Must stay valid and unmodified until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

IExcelWorkbook

A format-agnostic IExcelWorkbook backed by the concrete workbook that matches the detected format.

Exceptions

InvalidDataException

The buffer's signature does not match a supported format.

Open(string, ExcelFileFormat, ExcelReaderOptions?)

Opens a workbook of a known format from a file path, taking ownership of the file stream.

public static IExcelWorkbook Open(string path, ExcelFileFormat format, ExcelReaderOptions? options = null)

Parameters

path string

The path to the workbook file.

format ExcelFileFormat

The format to open path as. Unknown auto-detects XLSX/XLSB/XLS from the signature, exactly as Open(string, ExcelReaderOptions?) does.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null. Csv supplies the dialect when format is Csv.

Returns

IExcelWorkbook

A format-agnostic IExcelWorkbook.

Remarks

CSV carries no signature, so auto-detection never reports it; opening delimited text means naming Csv here.

Exceptions

ArgumentNullException

path is null.

ArgumentOutOfRangeException

format is EncryptedOoxml or not a defined value.

InvalidDataException

format is Unknown and the file's signature matches no supported format.

Open(string, ExcelReaderOptions?)

Opens a workbook from a file path, auto-detecting its format (XLSX/XLSB/XLS) from the file's signature and taking ownership of the file stream.

public static IExcelWorkbook Open(string path, ExcelReaderOptions? options = null)

Parameters

path string

The path to the workbook file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

Returns

IExcelWorkbook

A format-agnostic IExcelWorkbook backed by the concrete workbook that matches the detected format.

Remarks

Pattern-match on the returned workbook against its concrete type (XlsxWorkbook / XlsWorkbook / XlsbWorkbook) to access format-specific members.

Exceptions

ArgumentNullException

path is null.

InvalidDataException

The file's signature does not match a supported format.

OpenAsync(Stream, ExcelFileFormat, bool, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a workbook of a known format from an existing stream.

public static ValueTask<IExcelWorkbook> OpenAsync(Stream stream, ExcelFileFormat format, bool leaveOpen = true, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

stream Stream

The stream containing the workbook data. Must be seekable when format is Unknown.

format ExcelFileFormat

The format to read stream as. Unknown auto-detects XLSX/XLSB/XLS from the signature.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null. Csv supplies the dialect when format is Csv.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<IExcelWorkbook>

A format-agnostic IExcelWorkbook.

Exceptions

ArgumentNullException

stream is null.

ArgumentOutOfRangeException

format is EncryptedOoxml or not a defined value.

ArgumentException

format is Unknown and stream does not support seeking.

InvalidDataException

format is Unknown and the stream's signature matches no supported format.

OpenAsync(Stream, bool, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a workbook from an existing seekable stream, auto-detecting its format (XLSX/XLSB/XLS) from the stream's signature.

public static ValueTask<IExcelWorkbook> OpenAsync(Stream stream, bool leaveOpen = true, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

stream Stream

A seekable stream containing the workbook data.

leaveOpen bool

When true (the default), stream is not disposed when the workbook is disposed, but the caller must not use, reposition or dispose it until the workbook and every enumerator obtained from it are disposed.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<IExcelWorkbook>

A format-agnostic IExcelWorkbook backed by the concrete workbook that matches the detected format.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream does not support seeking.

InvalidDataException

The stream's signature does not match a supported format.

OpenAsync(string, ExcelFileFormat, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a workbook of a known format from a file path, taking ownership of the file stream.

public static ValueTask<IExcelWorkbook> OpenAsync(string path, ExcelFileFormat format, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

path string

The path to the workbook file.

format ExcelFileFormat

The format to open path as. Unknown auto-detects XLSX/XLSB/XLS from the signature.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null. Csv supplies the dialect when format is Csv.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<IExcelWorkbook>

A format-agnostic IExcelWorkbook.

Exceptions

ArgumentNullException

path is null.

ArgumentOutOfRangeException

format is EncryptedOoxml or not a defined value.

InvalidDataException

format is Unknown and the file's signature matches no supported format.

OpenAsync(string, ExcelReaderOptions?, CancellationToken)

Asynchronously opens a workbook from a file path, auto-detecting its format (XLSX/XLSB/XLS) from the file's signature and taking ownership of the file stream.

public static ValueTask<IExcelWorkbook> OpenAsync(string path, ExcelReaderOptions? options = null, CancellationToken ct = default)

Parameters

path string

The path to the workbook file.

options ExcelReaderOptions

Resource limits and behavior toggles; Default when null.

ct CancellationToken

A token to cancel the open operation.

Returns

ValueTask<IExcelWorkbook>

A format-agnostic IExcelWorkbook backed by the concrete workbook that matches the detected format.

Exceptions

ArgumentNullException

path is null.

InvalidDataException

The file's signature does not match a supported format.