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

AddChart(byte[], string, string, ChartType, ChartData, string, int, int)

Adds a chart to sheetName, anchored at cellRef, and returns the updated workbook.

byte[] AddChart(byte[] xlsx, string sheetName, string cellRef, ChartType type, ChartData data, string title = "", int widthPixels = 640, int heightPixels = 360)

Parameters

xlsx byte[]: The workbook to add the chart to. It is not modified.
sheetName string: The sheet to add the chart to.
cellRef string: An A1-style cell reference for the chart's top-left corner, e.g. "B2".
type ChartType: The chart's shape.
data ChartData: The chart's categories and value series.
title string: The chart's title. Empty for no title.
widthPixels int: The chart's width, in pixels.
heightPixels int: The chart's height, in pixels.

Returns

byte[]

Exceptions

ArgumentNullException: xlsx, data or another required argument is null.
ArgumentException: xlsx is empty, or sheetName/cellRef is blank.
DocumentConversionException: The workbook could not be opened, the sheet does not exist, or the reference is not valid.

AddChartAsync(Stream, string, string, ChartType, ChartData, Stream, string, int, int, CancellationToken)

Reads a workbook from source, adds a chart, and writes the result to destination — see AddChart(byte[], string, string, ChartType, ChartData, string, int, int) for the parameters.

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

Task AddChartAsync(Stream source, string sheetName, string cellRef, ChartType type, ChartData data, Stream destination, string title = "", int widthPixels = 640, int heightPixels = 360, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
sheetName string: The sheet to add the chart to.
cellRef string: An A1-style cell reference for the chart's top-left corner, e.g. "B2".
type ChartType: The chart's shape.
data ChartData: The chart's categories and value series.
destination Stream: The stream the updated workbook is written to.
title string: The chart's title. Empty for no title.
widthPixels int: The chart's width, in pixels.
heightPixels int: The chart's height, in pixels.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Exceptions

ArgumentNullException: source, destination or data 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.

AddDefinedName(byte[], string, string, string)

Adds a workbook-scoped defined name pointing at range on sheetName, and returns the updated workbook.

byte[] AddDefinedName(byte[] xlsx, string name, string sheetName, string range)

Parameters

xlsx byte[]: The workbook to add the defined name to. It is not modified.
name string: The defined name.
sheetName string: The sheet range is on.
range string: The cells the name refers to, such as A1:B2.

Returns

byte[]

Remarks

sheetName is always single-quoted in the reference this writes (e.g. 'Sales'!A1:B2), whether or not it needs to be. Measured directly: a sheet name containing a space and left unquoted does not raise an error at write time — the defined name simply is not present when the file is reopened, with nothing telling the caller why.

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: xlsx is empty, a name argument is blank, or range names a sheet.
DocumentConversionException: The workbook could not be opened, the sheet does not exist, or name is already in use.

AddDefinedNameAsync(Stream, string, string, string, Stream, CancellationToken)

Reads a workbook from source, adds a defined name, and writes the result to destination — see AddDefinedName(byte[], string, string, string) for the parameters.

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

Task AddDefinedNameAsync(Stream source, string name, string sheetName, string range, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
name string: The defined name.
sheetName string: The sheet range is on.
range string: The cells the name refers to, such as A1:B2.
destination Stream: The stream the updated workbook is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Exceptions

ArgumentNullException: source or destination is null.
ArgumentException: source is not readable or held no bytes, a name argument is blank, range names a sheet, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be opened, the sheet does not exist, or name is already in use.

AddImage(byte[], string, string, byte[], int?, int?)

Adds an image to sheetName, anchored at cellRef, and returns the updated workbook.

byte[] AddImage(byte[] xlsx, string sheetName, string cellRef, byte[] image, int? widthPixels = null, int? heightPixels = null)

Parameters

xlsx byte[]: The workbook to add the image to. It is not modified.
sheetName string: The sheet to add the image to.
cellRef string: An A1-style cell reference for the image's top-left corner, e.g. "B2".
image byte[]: The image bytes. PNG and JPEG only, decided by magic bytes.
widthPixels int?: The image's width, in pixels. null uses the image's own intrinsic width, scaled to match heightPixels if that is given.
heightPixels int?: The image's height, in pixels. null uses the image's own intrinsic height, scaled to match widthPixels if that is given.

Returns

byte[]

Remarks

Sizes are in pixels, matching AddChart(byte[], string, string, ChartType, ChartData, string, int, int) rather than the points/EMU the DOCX and PPTX drawing model uses. The format is decided by magic bytes, never a filename.

Exceptions

ArgumentNullException: xlsx, image or another required argument is null.
ArgumentException: xlsx or image is empty, or sheetName/cellRef is blank.
ArgumentOutOfRangeException: A supplied size is zero or negative.
DocumentConversionException: The workbook could not be opened, the sheet does not exist, the reference is not valid, or the image is neither PNG nor JPEG.

AddImageAsync(Stream, string, string, byte[], Stream, int?, int?, CancellationToken)

Reads a workbook from source, adds an image, and writes the result to destination — see AddImage(byte[], string, string, byte[], int?, int?) for the parameters.

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

Task AddImageAsync(Stream source, string sheetName, string cellRef, byte[] image, Stream destination, int? widthPixels = null, int? heightPixels = null, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
sheetName string: The sheet to add the image to.
cellRef string: An A1-style cell reference for the image's top-left corner, e.g. "B2".
image byte[]: The image bytes. PNG and JPEG only, decided by magic bytes.
destination Stream: The stream the updated workbook is written to.
widthPixels int?: The image's width, in pixels. See AddImage(byte[], string, string, byte[], int?, int?).
heightPixels int?: The image's height, in pixels. See AddImage(byte[], string, string, byte[], int?, int?).
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Exceptions

ArgumentNullException: source, destination or image is null.
ArgumentException: source is not readable or held no bytes, image is empty, a name is blank, or destination is not writable.
ArgumentOutOfRangeException: A supplied size is zero or negative.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be opened, the sheet does not exist, the reference is not valid, or the image is neither PNG nor JPEG.

AddPivotTable(byte[], string, string, string, string, IEnumerable<string>, IEnumerable<PivotDataField>, IEnumerable<string>?, IEnumerable<string>?, bool, bool)

Adds a pivot table to sheetName and returns the updated workbook.

byte[] AddPivotTable(byte[] xlsx, string sheetName, string sourceRange, string destinationCell, string name, IEnumerable<string> rowFields, IEnumerable<PivotDataField> dataFields, IEnumerable<string>? columnFields = null, IEnumerable<string>? pageFields = null, bool showRowGrandTotals = true, bool showColumnGrandTotals = true)

Parameters

xlsx byte[]: The workbook to add the pivot table to. It is not modified.
sheetName string: The sheet to add the pivot table to.
sourceRange string: An A1-style range naming the source data, e.g. "A1:C10".
destinationCell string: An A1-style cell reference for the pivot table's top-left corner, e.g. "E1".
name string: The pivot table's name.
rowFields IEnumerable<string>: Source column headers to group by, down the rows. At least one.
dataFields IEnumerable<PivotDataField>: The aggregated value columns. At least one.
columnFields IEnumerable<string>: Source column headers to group by, across the columns. Optional.
pageFields IEnumerable<string>: Source column headers used as report filters. Optional.
showRowGrandTotals bool: Whether to show a grand total row.
showColumnGrandTotals bool: Whether to show a grand total column.

Returns

byte[]

Remarks

The result grid is empty until Excel opens and recalculates it. A pivot table's aggregated values are computed by whichever application opens the file — nothing that writes it (this method included) populates the grid. Open the result in Excel (or an equivalent) to see it populated.

Exceptions

ArgumentNullException: xlsx, rowFields, dataFields or another required argument is null.
ArgumentException: xlsx is empty, a name argument is blank, or rowFields/dataFields is empty.
DocumentConversionException: The workbook could not be opened, the sheet does not exist, or destinationCell is not a valid cell reference.

AddPivotTableAsync(Stream, string, string, string, string, IEnumerable<string>, IEnumerable<PivotDataField>, Stream, IEnumerable<string>?, IEnumerable<string>?, bool, bool, CancellationToken)

Reads a workbook from source, adds a pivot table, and writes the result to destination — see AddPivotTable(byte[], string, string, string, string, IEnumerable<string>, IEnumerable<PivotDataField>, IEnumerable<string>?, IEnumerable<string>?, bool, bool) for the parameters.

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

Task AddPivotTableAsync(Stream source, string sheetName, string sourceRange, string destinationCell, string name, IEnumerable<string> rowFields, IEnumerable<PivotDataField> dataFields, Stream destination, IEnumerable<string>? columnFields = null, IEnumerable<string>? pageFields = null, bool showRowGrandTotals = true, bool showColumnGrandTotals = true, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
sheetName string: The sheet to add the pivot table to.
sourceRange string: An A1-style range naming the source data, e.g. "A1:C10".
destinationCell string: An A1-style cell reference for the pivot table's top-left corner, e.g. "E1".
name string: The pivot table's name.
rowFields IEnumerable<string>: Source column headers to group by, down the rows. At least one.
dataFields IEnumerable<PivotDataField>: The aggregated value columns. At least one.
destination Stream: The stream the updated workbook is written to.
columnFields IEnumerable<string>: Source column headers to group by, across the columns. Optional.
pageFields IEnumerable<string>: Source column headers used as report filters. Optional.
showRowGrandTotals bool: Whether to show a grand total row.
showColumnGrandTotals bool: Whether to show a grand total column.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Exceptions

ArgumentNullException: source, destination, rowFields or dataFields is null.
ArgumentException: source is not readable or held no bytes, a name is blank, or rowFields/dataFields is empty.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be opened, the sheet does not exist, or destinationCell is not a valid cell reference.

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.

EvaluateFormulas(byte[])

A copy of xlsx with every formula's computed value written into the file, not just held in memory.

byte[] EvaluateFormulas(byte[] xlsx)

Parameters

xlsx byte[]

Returns

byte[]

Remarks

A formula XlsxFormulaInspection would report as unsupported is left exactly as it was — no plausible-looking value is invented for it. Call InspectFormulas(byte[]) first if that distinction matters to the caller.

Exceptions

ArgumentNullException: xlsx is null.
ArgumentException: xlsx is empty.
DocumentConversionException: The workbook could not be read or written.

EvaluateFormulasAsync(Stream, Stream, CancellationToken)

A copy of xlsx with every formula's computed value written into the file, not just held in memory.

Task EvaluateFormulasAsync(Stream source, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
destination Stream: The stream the evaluated workbook is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Remarks

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

Exceptions

ArgumentNullException: An argument is null.
ArgumentException: source is not readable or held no bytes, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be read or written.

Format(byte[], string, XlsxFormat)

Applies format to sheetName and returns the workbook.

byte[] Format(byte[] xlsx, string sheetName, XlsxFormat format)

Parameters

xlsx byte[]
sheetName string
format XlsxFormat

Returns

byte[]

Remarks

Formatting is applied to an existing workbook rather than being an argument to Create, so it composes with every way a workbook can arrive - built here, appended to, or handed in by a caller who never used this library. See XlsxFormat for the boundary: a CLOSED vocabulary rather than a small one, and what is still deliberately outside it.

Exceptions

ArgumentNullException: xlsx or format is null.
ArgumentException: xlsx is empty, or the sheet name is blank.
DocumentConversionException: The workbook could not be opened, or the sheet does not exist.

FormatAsync(Stream, string, XlsxFormat, Stream, CancellationToken)

Reads a workbook from source, applies format, and writes the result to destination. Neither stream is disposed, closed or sought.

Task FormatAsync(Stream source, string sheetName, XlsxFormat format, Stream destination, CancellationToken ct = default)

Parameters

source Stream
sheetName string
format XlsxFormat
destination Stream
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: format is null, or a stream is null.
ArgumentException: A stream is unusable, source held no bytes, or the sheet name is blank.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be opened, or the sheet does not exist.

InspectFormulas(byte[])

Every formula xlsx carries, and whether each one is understood well enough to trust its value. See XlsxFormulaInspection for why this asks rather than assumes.

XlsxFormulaInspection InspectFormulas(byte[] xlsx)

Parameters

xlsx byte[]

Returns

XlsxFormulaInspection

Exceptions

ArgumentNullException: xlsx is null.
ArgumentException: xlsx is empty.
DocumentConversionException: The workbook could not be read.

InspectFormulasAsync(Stream, CancellationToken)

Every formula xlsx carries, and whether each one is understood well enough to trust its value. See XlsxFormulaInspection for why this asks rather than assumes.

Task<XlsxFormulaInspection> InspectFormulasAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
ct CancellationToken: Cancels the read.

Returns

Task<XlsxFormulaInspection>

Remarks

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

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be read.

InspectSignatures(byte[])

Inspects xlsx for digital signatures — whether it carries one, how many, and who claims to have signed it. Does not validate anything cryptographically; see ValidateSignatures(byte[], DocumentSignatureValidationOptions?).

DocumentSignatureInfo InspectSignatures(byte[] xlsx)

Parameters

xlsx byte[]

Returns

DocumentSignatureInfo

Exceptions

ArgumentNullException: xlsx is null.
ArgumentException: xlsx is empty.
DocumentConversionException: The workbook could not be inspected.

InspectSignaturesAsync(Stream, CancellationToken)

Reads an .xlsx from source and inspects it for digital signatures — see InspectSignatures(byte[]). source is read to its end and is neither disposed, closed nor sought.

Task<DocumentSignatureInfo> InspectSignaturesAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream
ct CancellationToken

Returns

Task<DocumentSignatureInfo>

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be inspected.

IsProtected(byte[])

Whether xlsx is encrypted - that is, whether the other members here will refuse it. Reads the file signature; needs no password.

bool IsProtected(byte[] xlsx)

Parameters

xlsx byte[]

Returns

bool

Exceptions

ArgumentNullException: xlsx is null.

IsProtectedAsync(Stream, CancellationToken)

Whether xlsx is encrypted - that is, whether the other members here will refuse it. Reads the file signature; needs no password.

Task<bool> IsProtectedAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
ct CancellationToken: Cancels the read.

Returns

Task<bool>

Remarks

source is read to its end and is neither disposed, closed nor sought. Unlike IsProtected(byte[]), which answers false for an empty array, an empty source is rejected - every Stream overload in this package treats a source that held no bytes as a caller error rather than as content.

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.

Protect(byte[], string)

A copy of xlsx encrypted with password.

byte[] Protect(byte[] xlsx, string password)

Parameters

xlsx byte[]
password string

Returns

byte[]

Remarks

File encryption, not the "restrict editing" flag. The result is a compound file rather than a XLSX package, so every other member here refuses it - call Unprotect(byte[], string) first.

Exceptions

ArgumentNullException: xlsx or password is null.
ArgumentException: xlsx is empty, or password is empty.
DocumentConversionException: It could not be read or encrypted.

ProtectAsync(Stream, Stream, string, CancellationToken)

Reads a workbook from source and writes the encrypted copy to destination. Neither stream is disposed, closed or sought.

Task ProtectAsync(Stream source, Stream destination, string password, CancellationToken ct = default)

Parameters

source Stream
destination Stream
password string
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Either stream is null, or password is null.
ArgumentException: A stream is unusable, or password is empty.
OperationCanceledException: ct was cancelled.
DocumentConversionException: It could not be encrypted.

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.

ReadMetadata(byte[])

The document properties xlsx carries.

DocumentMetadata ReadMetadata(byte[] xlsx)

Parameters

xlsx byte[]

Returns

DocumentMetadata

Exceptions

ArgumentNullException: xlsx is null.
ArgumentException: xlsx is empty.
DocumentConversionException: The workbook could not be read.

ReadMetadataAsync(Stream, CancellationToken)

The document properties xlsx carries.

Task<DocumentMetadata> ReadMetadataAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
ct CancellationToken: Cancels the read.

Returns

Task<DocumentMetadata>

Remarks

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

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be read.

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.

Unprotect(byte[], string)

A copy of xlsx with its encryption removed.

byte[] Unprotect(byte[] xlsx, string password)

Parameters

xlsx byte[]
password string

Returns

byte[]

Exceptions

ArgumentNullException: xlsx or password is null.
ArgumentException: xlsx is empty, or password is empty.
DocumentConversionException: The password was wrong, the workbook was not encrypted, or it could not be read.

UnprotectAsync(Stream, Stream, string, CancellationToken)

Reads an encrypted workbook from source and writes the unprotected copy to destination. Neither stream is disposed, closed or sought.

Task UnprotectAsync(Stream source, Stream destination, string password, CancellationToken ct = default)

Parameters

source Stream
destination Stream
password string
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Either stream is null, or password is null.
ArgumentException: A stream is unusable, or password is empty.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The password was wrong, or it could not be read.

ValidateSignatures(byte[], DocumentSignatureValidationOptions?)

Validates every digital signature xlsx carries, returning the report-level tamper-detection verdict alongside each signature's own certificate chain trust and revocation status. Never performs revocation checking or certificate downloads over the network, regardless of options — see DocumentSignatureValidationOptions's own remarks.

DocumentSignatureValidationReport ValidateSignatures(byte[] xlsx, DocumentSignatureValidationOptions? options = null)

Parameters

xlsx byte[]
options DocumentSignatureValidationOptions

Returns

DocumentSignatureValidationReport

Exceptions

ArgumentNullException: xlsx is null.
ArgumentException: xlsx is empty.
DocumentConversionException: The workbook could not be validated.

ValidateSignaturesAsync(Stream, DocumentSignatureValidationOptions?, CancellationToken)

Reads an .xlsx from source and validates its digital signatures — see ValidateSignatures(byte[], DocumentSignatureValidationOptions?). source is read to its end and is neither disposed, closed nor sought.

Task<DocumentSignatureValidationReport> ValidateSignaturesAsync(Stream source, DocumentSignatureValidationOptions? options = null, CancellationToken ct = default)

Parameters

source Stream
options DocumentSignatureValidationOptions
ct CancellationToken

Returns

Task<DocumentSignatureValidationReport>

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be validated.

WithMetadata(byte[], DocumentMetadata)

A copy of xlsx carrying metadata.

byte[] WithMetadata(byte[] xlsx, DocumentMetadata metadata)

Parameters

xlsx byte[]
metadata DocumentMetadata

Returns

byte[]

Remarks

A null property leaves what the workbook already had in place, so stamping a title does not silently erase an author. Pass an empty string to clear one.

Exceptions

ArgumentNullException: xlsx or metadata is null.
ArgumentException: xlsx is empty.
DocumentConversionException: The workbook could not be read or written.

WithMetadataAsync(Stream, DocumentMetadata, Stream, CancellationToken)

A copy of xlsx carrying metadata.

Task WithMetadataAsync(Stream source, DocumentMetadata metadata, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the workbook is read from.
metadata DocumentMetadata: The properties to stamp.
destination Stream: The stream the updated workbook is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Remarks

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

Exceptions

ArgumentNullException: An argument is null.
ArgumentException: source is not readable or held no bytes, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The workbook could not be read or written.

Table of Contents

Interface IWorkbookEditor

Methods

AddChart(byte[], string, string, ChartType, ChartData, string, int, int)

Parameters

Returns

Exceptions

AddChartAsync(Stream, string, string, ChartType, ChartData, Stream, string, int, int, CancellationToken)

Parameters

Returns

Exceptions

AddDefinedName(byte[], string, string, string)

Parameters

Returns

Remarks

Exceptions

AddDefinedNameAsync(Stream, string, string, string, Stream, CancellationToken)

Parameters

Returns

Exceptions

AddImage(byte[], string, string, byte[], int?, int?)

Parameters

Returns

Remarks

Exceptions

AddImageAsync(Stream, string, string, byte[], Stream, int?, int?, CancellationToken)

Parameters

Returns

Exceptions

AddPivotTable(byte[], string, string, string, string, IEnumerable<string>, IEnumerable<PivotDataField>, IEnumerable<string>?, IEnumerable<string>?, bool, bool)

Parameters

Returns

Remarks

Exceptions

AddPivotTableAsync(Stream, string, string, string, string, IEnumerable<string>, IEnumerable<PivotDataField>, Stream, IEnumerable<string>?, IEnumerable<string>?, bool, bool, CancellationToken)

Parameters

Returns

Exceptions

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

Parameters

Returns

Exceptions

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

Parameters

Returns

Exceptions

Create(IEnumerable<XlsxSheet>)

Parameters

Returns

Exceptions

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

Parameters

Returns

Exceptions

CreateAsync(IEnumerable<XlsxSheet>, Stream, CancellationToken)

Parameters

Returns

Exceptions

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

Parameters

Returns

Exceptions

EvaluateFormulas(byte[])

Parameters

Returns

Remarks

Exceptions

EvaluateFormulasAsync(Stream, Stream, CancellationToken)

Parameters

Returns

Remarks

Exceptions

Format(byte[], string, XlsxFormat)

Parameters

Returns

Remarks

Exceptions

FormatAsync(Stream, string, XlsxFormat, Stream, CancellationToken)

Parameters

Returns