Class ExcelReaderOptions
Resource limits and behavior toggles applied when opening and reading a workbook or a CSV source. Exceeding a byte or entry-count limit throws ExcelLimitExceededException.
public sealed record ExcelReaderOptions : IEquatable<ExcelReaderOptions>- Inheritance
-
ExcelReaderOptions
- Implements
- Inherited Members
Properties
Csv
Gets the delimited-text settings used when a source is opened as Csv. Defaults to null, meaning Default.
public CsvReaderOptions? Csv { get; init; }Property Value
Remarks
Ignored for the Excel formats. On the CSV path, MaxCellBytes and InternStrings still apply; the ZIP, shared-string, encryption and prefetch settings have nothing to act on.
Default
Gets the default options instance, used whenever a reader is opened without explicit options.
public static ExcelReaderOptions Default { get; }Property Value
InternStrings
Gets a value indicating whether text cells not served by a shared-string table (inline and
formula-string cells, and every CSV field) are deduplicated through a small content-keyed cache
when materialized via GetString(). Defaults to false.
Has no effect on shared-string cells, which already dedup through the shared-string table's
own index-keyed cache, nor on the zero-copy Value span path —
only GetString() consults this cache. Worth enabling only for genuinely categorical
(low-cardinality, repeated) text; for high-cardinality data every lookup is a cache miss, so the
per-call hashing cost is pure overhead — measured roughly doubling wall-clock time on a
real-world, mixed-cardinality CSV corpus.
public bool InternStrings { get; init; }Property Value
MaxCellBytes
Gets the maximum byte length allowed for a single cell's value, or a single buffered CSV record. Defaults to 32 MiB.
public int MaxCellBytes { get; init; }Property Value
MaxPasswordSpinCount
Gets the maximum password-derivation iteration count accepted from an encrypted workbook. Defaults to 100,000, which is what Excel writes.
public int MaxPasswordSpinCount { get; init; }Property Value
Remarks
An agile-encrypted file states its own iteration count, so a crafted workbook can ask for billions of iterations and stall the process for hours. Exceeding this throws ExcelLimitExceededException. ECMA-376 standard encryption is unaffected: its 50,000 iterations are fixed by the scheme rather than read from the file, so there is no file-supplied value to bound and this limit is not applied on that path.
MaxSharedStringBytes
Gets the maximum total byte size allowed for the shared string table. Defaults to 128 MiB.
public long MaxSharedStringBytes { get; init; }Property Value
MaxTotalDecompressedBytes
Gets the maximum total decompressed bytes allowed for one read of a sheet. Defaults to 512 MiB.
public long MaxTotalDecompressedBytes { get; init; }Property Value
Remarks
Applies to ZIP-backed formats (XLSX/XLSB) as their decompressed byte budget: what the workbook inflated when it opened and loaded its shared strings, plus the sheet being read. Each read of a sheet starts from that one-time total again, so reading a sheet twice does not count it twice. For the legacy CFB container (.xls) it caps the declared Workbook stream size — the CFB path has nothing to decompress, but this is still the caller's budget for what that phase may materialize.
MaxZipEntries
Gets the maximum number of ZIP entries allowed in an XLSX/XLSB archive. Defaults to 65,536.
public int MaxZipEntries { get; init; }Property Value
Password
Gets the password used to open an encrypted workbook. Defaults to null (no password), in which case opening an encrypted workbook throws ExcelEncryptionException with PasswordRequired.
public ExcelPassword? Password { get; init; }Property Value
Remarks
Applies to encrypted OOXML workbooks (.xlsx/.xlsb/.xlsm). Encrypted legacy .xls files are not supported at all, with or without a password.
PrefetchDecompression
Gets a value indicating whether ZIP-backed sheet data is decompressed on a background thread ahead of parsing. Defaults to false.
public bool PrefetchDecompression { get; init; }Property Value
Remarks
Applies only to ZIP-backed formats (XLSX/XLSB); XLS and CSV have nothing to decompress, so the option is silently ignored for them. Intended for single-file batch processing, where overlapping inflate with parsing shortens one read's wall-clock time — not for concurrent server workloads, where the extra background thread per read competes with work already saturating the CPU.
VerifyEncryptedIntegrity
Gets a value indicating whether an encrypted workbook's dataIntegrity HMAC is
verified when reading from a stream. Defaults to false.
public bool VerifyEncryptedIntegrity { get; init; }Property Value
Remarks
The HMAC covers the whole encrypted package, so verifying it on the streaming path requires a full pass over the file before the first row — making time-to-first-row proportional to file size, which defeats the point of a streaming reader. The in-memory path (FromXlsx(ReadOnlyMemory<byte>, ExcelReaderOptions?)) has already decrypted everything, so it always verifies regardless of this setting. With verification off, targeted ciphertext tampering is not detected, though corrupt ciphertext still fails loudly downstream when the decrypted bytes fail ZIP and XML parsing. Standard encryption has no HMAC field, so this setting does not apply to it.
VerifyZipChecksums
Gets a value indicating whether each ZIP entry read from an XLSX or XLSB package is checked against the CRC-32 its central directory records. Defaults to true.
public bool VerifyZipChecksums { get; init; }Property Value
Remarks
A mismatch throws InvalidDataException when the entry's last bytes are read, so rows before the damage may already have been returned. Turn it off to read a package whose producer wrote wrong checksums; damaged data then surfaces only if it also breaks parsing.