Class XlsWorkbookWriter

Namespace

ExcelReader.Core.Writer.Xls

Assembly

ExcelReader.Core.dll

Writes a workbook to the legacy BIFF8 (.xls) binary format.

public sealed class XlsWorkbookWriter : IWorkbookWriter<XlsSheetWriter>, IDisposable, IAsyncDisposable

Inheritance

object

XlsWorkbookWriter

Implements

IWorkbookWriter<XlsSheetWriter>

IDisposable

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ArrowWriteExtensions.WriteRecordBatch(XlsWorkbookWriter, RecordBatch, ArrowWriteOptions?)

ArrowWriteExtensions.WriteRecordBatchAsync(XlsWorkbookWriter, RecordBatch, ArrowWriteOptions?, CancellationToken)

Remarks

Structured the same way as XlsxWorkbookWriter (XLSX). Unlike the ZIP writer, records are buffered in memory and the OLE container is assembled in EndAsync(CancellationToken): the BoundSheet offsets in the globals and the OLE FAT both need stream sizes known only at the end. Rows beyond the BIFF8 per-sheet cap (65,536) overflow into auto-generated continuation sheets, so memory scales with total row count rather than being bounded per sheet.

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.

public XlsSheetWriter AddSheet(string name)

Parameters

name string

The 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

XlsSheetWriter

The writer for the new sheet.

Exceptions

InvalidOperationException

The previously added sheet has not been ended yet.

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.

public XlsSheetWriter AddSheet(string name, ExcelSheetVisibility visibility)

Parameters

name string

The 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 : \ / ? * [ ]).

visibility ExcelSheetVisibility

Whether 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

XlsSheetWriter

The writer for the new sheet.

Exceptions

ArgumentOutOfRangeException

visibility is not a defined value.

InvalidOperationException

The previously added sheet has not been ended yet.

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.

public int AddStyle(CellStyle style)

Parameters

style CellStyle

The 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.

Create(Stream, bool, XlsWriterOptions?)

Creates a writer that emits a BIFF8 (.xls) workbook to stream.

public static XlsWorkbookWriter Create(Stream stream, bool leaveOpen = false, XlsWriterOptions? options = null)

Parameters

stream Stream

The destination stream.

leaveOpen bool

If true, the stream is left open when the writer is disposed.

options XlsWriterOptions

The date system; Default when null.

Returns

XlsWorkbookWriter

Dispose()

Synchronous counterpart to DisposeAsync(), for native/unmanaged callers whose ABI is synchronous.

public void Dispose()

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

End()

Synchronous counterpart to EndAsync(CancellationToken), for native/unmanaged callers whose ABI is synchronous.

public void End()

Exceptions

InvalidOperationException

No sheet was ever added to the workbook.

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.

public ValueTask EndAsync(CancellationToken ct = default)

Parameters

ct CancellationToken

A token to cancel the operation.

Returns

ValueTask

Exceptions

InvalidOperationException

No sheet was ever added to the workbook.

Flush()

Synchronous counterpart to FlushAsync(CancellationToken), for native/unmanaged callers whose ABI is synchronous.

public void Flush()

FlushAsync(CancellationToken)

Flushes any buffered output for the workbook and its current sheet to the destination stream.

public ValueTask FlushAsync(CancellationToken ct = default)

Parameters

ct CancellationToken

A token to cancel the operation.

Returns

ValueTask