Interface IWorkbookWriter<TSheet>
Writes a whole workbook (XLSX, XLSB, XLS or CSV) to a destination stream, one sheet at a time. Implementations open the underlying stream/archive on construction, so a caller only needs to add sheets with AddSheet(string) and dispose the workbook (or call EndAsync(CancellationToken) then dispose) when finished.
public interface IWorkbookWriter<out TSheet> : IDisposable, IAsyncDisposableType Parameters
TSheetThe concrete ISheetWriter<TRow> this workbook produces.
- Inherited Members
Remarks
Thread safety: no implementation is thread-safe, nor are the ISheetWriter<TRow>/ IRowWriter instances it hands out. All of them carry mutable state (current sheet/row, buffered output) with no synchronization. Use one workbook writer per thread; do not call into a writer, its current sheet, or its current row from more than one thread at a time.
Only ExcelReader implements this interface, and a minor version can add members to it. See versioning and compatibility.
Methods
AddSheet(string)
Begins a new sheet named name and returns its writer. Only one sheet may be
open (started and not yet ended) at a time; the previous sheet's writer must be ended and
disposed before starting the next one.
TSheet AddSheet(string name)Parameters
namestringThe sheet's name, shown to Excel; must be unique (ignoring case) within the workbook and meet Excel's sheet-name restrictions (1-31 characters, no
: \ / ? * [ ]).
Returns
- TSheet
The writer for the new sheet.
AddSheet(string, ExcelSheetVisibility)
Begins a new sheet named name with the given tab-bar visibility, and returns
its writer. Same contract as AddSheet(string) otherwise.
TSheet AddSheet(string name, ExcelSheetVisibility visibility)Parameters
namestringThe sheet's name, shown to Excel; must be unique (ignoring case) within the workbook and meet Excel's sheet-name restrictions (1-31 characters, no
: \ / ? * [ ]).visibilityExcelSheetVisibilityWhether the sheet is shown in the workbook's tab bar. A workbook whose sheets are all hidden is rejected when it is ended, since Excel reports such a file as damaged.
Returns
- TSheet
The writer for the new sheet.
Exceptions
- ArgumentOutOfRangeException
visibilityis not a defined value.
AddStyle(CellStyle)
Registers style and returns its index, reusing the index of an
already-registered style with the same value. Index 0 is always the general/default
style; index 1 is always the builtin date style every date cell already uses.
int AddStyle(CellStyle style)Parameters
styleCellStyleThe number format/bold/italic combination to register.
Returns
- int
The style's index, for use with SetColumnStyle(int, int) and StartRowAsync(int, CancellationToken).
Exceptions
- ArgumentException
The style's number format is longer than 255 characters.
- ExcelLimitExceededException
The workbook already has 200 distinct number formats, the most Excel opens.
End()
Synchronous counterpart to EndAsync(CancellationToken): finalizes the workbook without the async/await machinery, for native/unmanaged callers whose ABI is synchronous.
[SuppressMessage("Naming", "CA1716:Identifiers should not match keywords", Justification = "'End' is not reserved in C#, this project's primary language; matches the sync/async naming pair (End/EndAsync) already used throughout this codebase (e.g. XlsSheetWriter.End).")]
void End()EndAsync(CancellationToken)
Finalizes the workbook, writing any trailing structure (e.g. the workbook manifest/index) so the destination stream contains a complete, readable file. No further sheets may be added afterward. Idempotent with disposal: disposing an already-ended workbook is a no-op beyond releasing resources. A call that fails part-way still ends the workbook: it cannot be retried, and disposing it only releases the stream. A token already canceled on entry leaves the workbook untouched.
ValueTask EndAsync(CancellationToken ct = default)Parameters
ctCancellationTokenA token to cancel the operation.
Returns
Flush()
Synchronous counterpart to FlushAsync(CancellationToken): flushes any buffered output for the workbook and its current sheet to the destination stream, without the async/await machinery.
void Flush()FlushAsync(CancellationToken)
Flushes any buffered output for the workbook and its current sheet to the destination stream.
ValueTask FlushAsync(CancellationToken ct = default)Parameters
ctCancellationTokenA token to cancel the operation.