Interface IWorkbookEditor

Namespace

DocToolkit.Extensions.DependencyInjection

Assembly

DocToolkit.Extensions.DependencyInjection.dll

Creates, reads and edits Excel (.xlsx) workbooks. Registered by AddDocToolkit(IServiceCollection, Action<DocToolkitOptions>?).

public interface IWorkbookEditor

Methods

AppendRows(byte[], string, IEnumerable<IEnumerable<object?>>)

Appends rows to sheetName, after its last used row, leaving every other sheet and all existing formatting as it was.

"Last used" counts a cell comment or a merged range even where the cell has no value, so a stray comment far below the data pushes the append below it.

byte[] AppendRows(byte[] xlsx, string sheetName, IEnumerable<IEnumerable<object?>> rows)

Parameters

xlsx byte[]

sheetName string

rows IEnumerable<IEnumerable<object>>

Returns

byte[]

Exceptions

ArgumentNullException

xlsx or rows is null.

ArgumentException

xlsx is empty, sheetName is blank, longer than 31 characters or contains one of : \ / ? * [ ], or an element of rows is null.

DocumentConversionException

The sheet was not found, or the package could not be opened or edited.

AppendRowsAsync(Stream, string, IEnumerable<IEnumerable<object?>>, Stream, CancellationToken)

Reads a workbook from source, appends rows to sheetName, and writes the result to destination. See AppendRows(byte[], string, IEnumerable<IEnumerable<object?>>) for the semantics.

source is read to its end and destination is written; neither is disposed, closed nor sought.

Task AppendRowsAsync(Stream source, string sheetName, IEnumerable<IEnumerable<object?>> rows, Stream destination, CancellationToken ct = default)

Parameters

source Stream

sheetName string

rows IEnumerable<IEnumerable<object>>

destination Stream

ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException

rows is null.

ArgumentException

source is not readable or held no bytes, destination is not writable, sheetName is invalid as above, or an element of rows is null.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The sheet was not found, or the package could not be opened or edited.

Create(IEnumerable<XlsxSheet>)

Builds a workbook from sheets, one worksheet each, in sequence order. Content comes from data rather than a template, so there is no source file to edit.

A cell holding a XlsxFormula is written as a formula. No cached result is stored, so a reader that only reads cached values sees an empty cell until Excel has opened and saved the file; this package's own readers compute on read.

byte[] Create(IEnumerable<XlsxSheet> sheets)

Parameters

sheets IEnumerable<XlsxSheet>

Returns

byte[]

Exceptions

ArgumentNullException

sheets is null.

ArgumentException

sheets is empty, contains a null element, or names the same sheet twice.

DocumentConversionException

The workbook could not be built.

Create(string, IEnumerable<IEnumerable<object?>>)

Creates a workbook with one sheet populated from rows.

byte[] Create(string sheetName, IEnumerable<IEnumerable<object?>> rows)

Parameters

sheetName string

rows IEnumerable<IEnumerable<object>>

Returns

byte[]

Exceptions

ArgumentNullException

rows is null.

ArgumentException

sheetName is blank, or a row is null.

DocumentConversionException

The workbook could not be built.

CreateAsync(IEnumerable<XlsxSheet>, Stream, CancellationToken)

Builds a workbook from sheets and writes it to destination. See Create(IEnumerable<XlsxSheet>) for the semantics.

destination is written and is neither disposed, closed nor sought, so an HTTP response body is a valid destination.

Task CreateAsync(IEnumerable<XlsxSheet> sheets, Stream destination, CancellationToken ct = default)

Parameters

sheets IEnumerable<XlsxSheet>

destination Stream

ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException

Either argument is null.

ArgumentException

sheets is invalid as above, or destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The workbook could not be built or written.

CreateAsync(string, IEnumerable<IEnumerable<object?>>, Stream, CancellationToken)

Builds a workbook with one sheet populated from rows and writes it to destination. See Create(string, IEnumerable<IEnumerable<object?>>) for the exact typing and culture rules applied to each cell. destination is written and is not disposed, closed or sought.

Task CreateAsync(string sheetName, IEnumerable<IEnumerable<object?>> rows, Stream destination, CancellationToken ct = default)

Parameters

sheetName string

rows IEnumerable<IEnumerable<object>>

destination Stream

ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException

rows or destination is null.

ArgumentException

sheetName is blank, a row is null, or destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The workbook could not be built or written.

ReadCell(byte[], string, string)

Reads a cell as a string. cellRef is an A1-style reference.

string ReadCell(byte[] xlsx, string sheetName, string cellRef)

Parameters

xlsx byte[]

sheetName string

cellRef string

Returns

string

Exceptions

ArgumentNullException

Any argument is null.

ArgumentException

xlsx is empty, or a name is blank.

DocumentConversionException

The workbook could not be opened, the sheet does not exist, or the reference is not valid.

ReadCellAsync(Stream, string, string, CancellationToken)

Reads a workbook from source and returns a cell as a string. cellRef is an A1-style reference. source is read to its end and is neither disposed, closed nor sought.

Task<string> ReadCellAsync(Stream source, string sheetName, string cellRef, CancellationToken ct = default)

Parameters

source Stream

sheetName string

cellRef string

ct CancellationToken

Returns

Task<string>

Exceptions

ArgumentNullException

source is null.

ArgumentException

source is not readable or held no bytes, or a name is blank.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The workbook could not be opened, the sheet does not exist, or the reference is not valid.

ReadSheet(byte[], string)

Reads a whole sheet as strings, anchored at A1: if the data starts at C3, its first value is at rows[2][2]. Every row is padded to the last used column, so all rows have the same length; blank cells — and entirely blank rows inside the range — come back as empty strings rather than being dropped, which keeps rows[r][c] positionally meaningful.

Values are produced exactly as ReadCell(byte[], string, string) produces them, so the two can never disagree about what a cell says. A formula cell yields its cached value: nothing in this library evaluates formulas.

Text follows the calling thread's CurrentCulture — the same rule ReadCell(byte[], string, string) uses, and asymmetric with Create(string, IEnumerable<IEnumerable<object?>>), which deliberately writes with InvariantCulture so the same code produces the same file everywhere. A number such as 1234.5 reads back as "1234.5" under an invariant or en-US culture but "1234,5" under de-DE; callers who parse the returned text as a number should account for that, e.g. by parsing with an explicit CultureInfo rather than the default.

IReadOnlyList<IReadOnlyList<string>> ReadSheet(byte[] xlsx, string sheetName)

Parameters

xlsx byte[]

The workbook bytes.

sheetName string

The sheet to read.

Returns

IReadOnlyList<IReadOnlyList<string>>

The sheet's used range, anchored at A1 and padded rectangular. Empty only if the sheet holds no values and no cell comments: formatting alone never widens the range, but a comment on an otherwise-blank cell does, because ClosedXML's LastCellUsed() counts it as used.

Remarks

The whole range is materialised into memory at once, so its cost is proportional to rows × columns, not to how much of that rectangle actually holds data. To keep one far-flung stray value from exhausting memory, ReadSheet(byte[], string) throws DocumentConversionException rather than allocate when the used range exceeds 2,000,000 cells.

Exceptions

ArgumentNullException

Any argument is null.

ArgumentException

xlsx is empty, or sheetName is blank.

DocumentConversionException

The workbook could not be opened, the sheet does not exist, or the sheet's used range exceeds the 2,000,000-cell limit ReadSheet(byte[], string) will materialise.

ReadSheetAsync(Stream, string, CancellationToken)

Reads a workbook from source and returns a whole sheet as strings. See ReadSheet(byte[], string) for the anchoring, padding, culture and formula rules — this overload applies the identical logic. source is read to its end and is neither disposed, closed nor sought.

Task<IReadOnlyList<IReadOnlyList<string>>> ReadSheetAsync(Stream source, string sheetName, CancellationToken ct = default)

Parameters

source Stream

The stream the workbook is read from.

sheetName string

The sheet to read.

ct CancellationToken

Cancels the read.

Returns

Task<IReadOnlyList<IReadOnlyList<string>>>

The sheet's used range, anchored at A1 and padded rectangular. Empty only if the sheet holds no values and no cell comments — see ReadSheet(byte[], string).

Exceptions

ArgumentNullException

source is null.

ArgumentException

source is not readable or held no bytes, or sheetName is blank.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The workbook could not be opened, the sheet does not exist, or the sheet's used range exceeds the 2,000,000-cell limit ReadSheet(byte[], string) will materialise.

SetCell(byte[], string, string, object?)

Sets a cell and returns the updated workbook bytes.

byte[] SetCell(byte[] xlsx, string sheetName, string cellRef, object? value)

Parameters

xlsx byte[]

sheetName string

cellRef string

value object

Returns

byte[]

Exceptions

ArgumentNullException

Any argument other than value is null.

ArgumentException

xlsx is empty, or a name is blank.

DocumentConversionException

The workbook could not be opened, the sheet does not exist, or the reference is not valid.

SetCellAsync(Stream, string, string, object?, Stream, CancellationToken)

Reads a workbook from source, sets one cell, and writes the result to destination. cellRef is an A1-style reference. source is read to its end and destination is written; neither is disposed, closed or sought.

Task SetCellAsync(Stream source, string sheetName, string cellRef, object? value, Stream destination, CancellationToken ct = default)

Parameters

source Stream

sheetName string

cellRef string

value object

destination Stream

ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException

source or destination is null.

ArgumentException

source is not readable or held no bytes, a name is blank, or destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The workbook could not be opened, the sheet does not exist, or the reference is not valid.

SheetNames(byte[])

Lists every sheet in the workbook, in tab order, including hidden sheets — hiding a sheet is a presentation choice, not a privacy boundary, and a caller who cannot see a hidden sheet listed has no way to discover it exists.

IReadOnlyList<string> SheetNames(byte[] xlsx)

Parameters

xlsx byte[]

The workbook bytes.

Returns

IReadOnlyList<string>

The sheet names, in tab order.

Exceptions

ArgumentNullException

xlsx is null.

ArgumentException

xlsx is empty.

DocumentConversionException

The workbook could not be opened.

SheetNamesAsync(Stream, CancellationToken)

Reads a workbook from source and lists every sheet in tab order, including hidden sheets. source is read to its end and is neither disposed, closed nor sought.

Task<IReadOnlyList<string>> SheetNamesAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream

The stream the workbook is read from.

ct CancellationToken

Cancels the read.

Returns

Task<IReadOnlyList<string>>

The sheet names, in tab order.

Exceptions

ArgumentNullException

source is null.

ArgumentException

source is not readable or held no bytes.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The workbook could not be opened.