Class ParallelSheetWriterExtensions

Namespace

ExcelReader.Core.Writer

Assembly

ExcelReader.Core.dll

Record writes that format and compress batches of rows on several threads and write them in order. Memory is bounded by DegreeOfParallelism batches of BatchRows rows.

public static class ParallelSheetWriterExtensions

Inheritance

object

ParallelSheetWriterExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The source is enumerated by one flow at a time, never concurrently. A writeRow delegate runs on pool threads, several at once, so whatever it captures must be safe to use concurrently; the layouts from ExcelRecordLayout are. Rows may be written through the normal API before and after a call, but not while one is running. A call that throws, a cancelled one included, ends the sheet and its workbook. With shared strings on, string indexes depend on thread timing, so two runs give the same content in files that differ byte for byte.

Methods

WriteRecordsParallelAsync<T>(XlsbSheetWriter, IAsyncEnumerable<T>, ExcelRecordLayout<T>, ParallelWriteOptions?, CancellationToken)

Writes a header row from layout, then one row per record, in parallel batches.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsbSheetWriter sheet, IAsyncEnumerable<T> records, ExcelRecordLayout<T> layout, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsbSheetWriter

The sheet to write rows to.

records IAsyncEnumerable<T>

The records to write, one row each, in enumeration order.

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteRecordsParallelAsync<T>(XlsbSheetWriter, IAsyncEnumerable<T>, Action<XlsbRowWriter, T>, ParallelWriteOptions?, CancellationToken)

Writes one row per record in parallel batches, calling writeRow to populate each row. No header is written.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsbSheetWriter sheet, IAsyncEnumerable<T> records, Action<XlsbRowWriter, T> writeRow, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsbSheetWriter

The sheet to write rows to.

records IAsyncEnumerable<T>

The records to write, one row each, in enumeration order.

writeRow Action<XlsbRowWriter, T>

Populates a row's cells from a single record. It runs on pool threads, several at once.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or writeRow is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteRecordsParallelAsync<T>(XlsbSheetWriter, IEnumerable<T>, ExcelRecordLayout<T>, ParallelWriteOptions?, CancellationToken)

Writes a header row from layout, then one row per record, in parallel batches.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsbSheetWriter sheet, IEnumerable<T> records, ExcelRecordLayout<T> layout, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsbSheetWriter

The sheet to write rows to.

records IEnumerable<T>

The records to write, one row each, in enumeration order.

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteRecordsParallelAsync<T>(XlsbSheetWriter, IEnumerable<T>, Action<XlsbRowWriter, T>, ParallelWriteOptions?, CancellationToken)

Writes one row per record in parallel batches, calling writeRow to populate each row. No header is written.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsbSheetWriter sheet, IEnumerable<T> records, Action<XlsbRowWriter, T> writeRow, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsbSheetWriter

The sheet to write rows to.

records IEnumerable<T>

The records to write, one row each, in enumeration order.

writeRow Action<XlsbRowWriter, T>

Populates a row's cells from a single record. It runs on pool threads, several at once.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or writeRow is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteRecordsParallelAsync<T>(XlsxSheetWriter, IAsyncEnumerable<T>, ExcelRecordLayout<T>, ParallelWriteOptions?, CancellationToken)

Writes a header row from layout, then one row per record, in parallel batches.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsxSheetWriter sheet, IAsyncEnumerable<T> records, ExcelRecordLayout<T> layout, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsxSheetWriter

The sheet to write rows to.

records IAsyncEnumerable<T>

The records to write, one row each, in enumeration order.

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteRecordsParallelAsync<T>(XlsxSheetWriter, IAsyncEnumerable<T>, Action<XlsxRowWriter, T>, ParallelWriteOptions?, CancellationToken)

Writes one row per record in parallel batches, calling writeRow to populate each row. No header is written.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsxSheetWriter sheet, IAsyncEnumerable<T> records, Action<XlsxRowWriter, T> writeRow, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsxSheetWriter

The sheet to write rows to.

records IAsyncEnumerable<T>

The records to write, one row each, in enumeration order.

writeRow Action<XlsxRowWriter, T>

Populates a row's cells from a single record. It runs on pool threads, several at once.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or writeRow is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteRecordsParallelAsync<T>(XlsxSheetWriter, IEnumerable<T>, ExcelRecordLayout<T>, ParallelWriteOptions?, CancellationToken)

Writes a header row from layout, then one row per record, in parallel batches.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsxSheetWriter sheet, IEnumerable<T> records, ExcelRecordLayout<T> layout, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsxSheetWriter

The sheet to write rows to.

records IEnumerable<T>

The records to write, one row each, in enumeration order.

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteRecordsParallelAsync<T>(XlsxSheetWriter, IEnumerable<T>, Action<XlsxRowWriter, T>, ParallelWriteOptions?, CancellationToken)

Writes one row per record in parallel batches, calling writeRow to populate each row. No header is written.

public static ValueTask WriteRecordsParallelAsync<T>(this XlsxSheetWriter sheet, IEnumerable<T> records, Action<XlsxRowWriter, T> writeRow, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsxSheetWriter

The sheet to write rows to.

records IEnumerable<T>

The records to write, one row each, in enumeration order.

writeRow Action<XlsxRowWriter, T>

Populates a row's cells from a single record. It runs on pool threads, several at once.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records or writeRow is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

ObjectDisposedException

The sheet has already been ended.

InvalidOperationException

A row is still active on the sheet.

ExcelLimitExceededException

The records do not fit in the sheet's 1,048,576 rows.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteTableParallelAsync<T>(XlsbSheetWriter, IAsyncEnumerable<T>, string, ExcelRecordLayout<T>, ExcelTableOptions?, ParallelWriteOptions?, CancellationToken)

Writes records as an Excel table named name: a header row from layout, one row per record in parallel batches, then closes the table.

public static ValueTask WriteTableParallelAsync<T>(this XlsbSheetWriter sheet, IAsyncEnumerable<T> records, string name, ExcelRecordLayout<T> layout, ExcelTableOptions? tableOptions = null, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsbSheetWriter

The sheet to write to.

records IAsyncEnumerable<T>

The records to write, one row each, in enumeration order.

name string

The table name; see BeginTable(string, IReadOnlyList<string>, ExcelTableOptions?).

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

tableOptions ExcelTableOptions

Position and style. Defaults to Default.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records, name or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteTableParallelAsync<T>(XlsbSheetWriter, IEnumerable<T>, string, ExcelRecordLayout<T>, ExcelTableOptions?, ParallelWriteOptions?, CancellationToken)

Writes records as an Excel table named name: a header row from layout, one row per record in parallel batches, then closes the table.

public static ValueTask WriteTableParallelAsync<T>(this XlsbSheetWriter sheet, IEnumerable<T> records, string name, ExcelRecordLayout<T> layout, ExcelTableOptions? tableOptions = null, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsbSheetWriter

The sheet to write to.

records IEnumerable<T>

The records to write, one row each, in enumeration order.

name string

The table name; see BeginTable(string, IReadOnlyList<string>, ExcelTableOptions?).

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

tableOptions ExcelTableOptions

Position and style. Defaults to Default.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records, name or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteTableParallelAsync<T>(XlsxSheetWriter, IAsyncEnumerable<T>, string, ExcelRecordLayout<T>, ExcelTableOptions?, ParallelWriteOptions?, CancellationToken)

Writes records as an Excel table named name: a header row from layout, one row per record in parallel batches, then closes the table.

public static ValueTask WriteTableParallelAsync<T>(this XlsxSheetWriter sheet, IAsyncEnumerable<T> records, string name, ExcelRecordLayout<T> layout, ExcelTableOptions? tableOptions = null, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsxSheetWriter

The sheet to write to.

records IAsyncEnumerable<T>

The records to write, one row each, in enumeration order.

name string

The table name; see BeginTable(string, IReadOnlyList<string>, ExcelTableOptions?).

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

tableOptions ExcelTableOptions

Position and style. Defaults to Default.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records, name or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.

WriteTableParallelAsync<T>(XlsxSheetWriter, IEnumerable<T>, string, ExcelRecordLayout<T>, ExcelTableOptions?, ParallelWriteOptions?, CancellationToken)

Writes records as an Excel table named name: a header row from layout, one row per record in parallel batches, then closes the table.

public static ValueTask WriteTableParallelAsync<T>(this XlsxSheetWriter sheet, IEnumerable<T> records, string name, ExcelRecordLayout<T> layout, ExcelTableOptions? tableOptions = null, ParallelWriteOptions? options = null, CancellationToken ct = default)

Parameters

sheet XlsxSheetWriter

The sheet to write to.

records IEnumerable<T>

The records to write, one row each, in enumeration order.

name string

The table name; see BeginTable(string, IReadOnlyList<string>, ExcelTableOptions?).

layout ExcelRecordLayout<T>

The columns to write, from ExcelRecordLayout.

tableOptions ExcelTableOptions

Position and style. Defaults to Default.

options ParallelWriteOptions

Degree of parallelism and batch size. Defaults to Default.

ct CancellationToken

A token to cancel the operation between batches.

Returns

ValueTask

Type Parameters

T

The record type being written.

Exceptions

ArgumentNullException

sheet, records, name or layout is null.

ArgumentOutOfRangeException

options holds a negative degree or a batch size below 1.

OperationCanceledException

ct was cancelled. Unlike a serial write cancelled between rows, this ends the sheet and its workbook.