Method ToChannel

Namespace

Open.Database.Extensions

Assembly

Open.Database.Extensions.Channel.dll

ToChannel(IDataReader, bool, CancellationToken)

Starts reading an IDataReader in the background and returns the reader of a new unbounded channel that receives each record as an array of values.

public static ChannelReader<object[]> ToChannel(this IDataReader reader, bool singleReader, CancellationToken cancellationToken = default)

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<object[]>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

reader is null.

ToChannel(IDataReader, bool, ArrayPool<object>?, CancellationToken)

Starts reading an IDataReader in the background and returns the reader of a new unbounded channel that receives each record as an array of values rented from an array pool.

public static ChannelReader<object[]> ToChannel(this IDataReader reader, bool singleReader, ArrayPool<object>? arrayPool, CancellationToken cancellationToken = default)

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

arrayPool ArrayPool<object>

The array pool to rent each record's array from, or null to allocate new arrays. The consumer of the channel is responsible for returning each array to the pool.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<object[]>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

reader is null.

ToChannel<T>(IDataReader, bool, Func<IDataRecord, T>, CancellationToken)

Starts reading an IDataReader in the background and returns the reader of a new unbounded channel that receives each record after it has been transformed by transform.

public static ChannelReader<T> ToChannel<T>(this IDataReader reader, bool singleReader, Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item written to the channel.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type of the items written to the channel: the return type of the transform function.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

reader is null.

ToChannel<T>(IDataReader, bool, CancellationToken)

Starts reading an IDataReader in the background and returns the reader of a new unbounded channel that receives each record mapped to a new instance of T.

public static ChannelReader<T> ToChannel<T>(this IDataReader reader, bool singleReader, CancellationToken cancellationToken = default) where T : new()

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type each record is mapped to.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

reader is null.

ToChannel<T>(IDataReader, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Starts reading an IDataReader in the background and returns the reader of a new unbounded channel that receives each record mapped to a new instance of T, using the field-to-column overrides.

public static ChannelReader<T> ToChannel<T>(this IDataReader reader, bool singleReader, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

fieldMappingOverrides IEnumerable<(string Field, string Column)>

An override map of field names to column names, applied on top of the default name-based mapping.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type each record is mapped to.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

reader is null.

ToChannel(IDbCommand, bool, CancellationToken)

Starts reading the results of an IDbCommand in the background and returns the reader of a new unbounded channel that receives each record as an array of values.

public static ChannelReader<object[]> ToChannel(this IDbCommand command, bool singleReader, CancellationToken cancellationToken = default)

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<object[]>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel(IDbCommand, bool, ArrayPool<object>, CancellationToken)

Starts reading the results of an IDbCommand in the background and returns the reader of a new unbounded channel that receives each record as an array of values rented from an array pool.

public static ChannelReader<object[]> ToChannel(this IDbCommand command, bool singleReader, ArrayPool<object> arrayPool, CancellationToken cancellationToken = default)

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

arrayPool ArrayPool<object>

The array pool to rent each record's array from. The consumer of the channel is responsible for returning each array to the pool.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<object[]>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel<T>(IDbCommand, bool, Func<IDataRecord, T>, CancellationToken)

Starts reading the results of an IDbCommand in the background and returns the reader of a new unbounded channel that receives each record after it has been transformed by transform.

public static ChannelReader<T> ToChannel<T>(this IDbCommand command, bool singleReader, Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item written to the channel.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type of the items written to the channel: the return type of the transform function.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel<T>(IDbCommand, bool, CancellationToken)

Starts reading the results of an IDbCommand in the background and returns the reader of a new unbounded channel that receives each record mapped to a new instance of T.

public static ChannelReader<T> ToChannel<T>(this IDbCommand command, bool singleReader, CancellationToken cancellationToken = default) where T : new()

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type each record is mapped to.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel<T>(IDbCommand, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Starts reading the results of an IDbCommand in the background and returns the reader of a new unbounded channel that receives each record mapped to a new instance of T, using the field-to-column overrides.

public static ChannelReader<T> ToChannel<T>(this IDbCommand command, bool singleReader, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

fieldMappingOverrides IEnumerable<(string Field, string Column)>

An override map of field names to column names, applied on top of the default name-based mapping.

cancellationToken CancellationToken

A token that can cancel the reading. The channel is then completed with the resulting exception.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type each record is mapped to.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel(IExecuteReader, bool)

Starts reading the results of an IExecuteReader in the background and returns the reader of a new unbounded channel that receives each record as an array of values.

public static ChannelReader<object[]> ToChannel(this IExecuteReader command, bool singleReader)

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

Returns

ChannelReader<object[]>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel(IExecuteReader, bool, ArrayPool<object>)

Starts reading the results of an IExecuteReader in the background and returns the reader of a new unbounded channel that receives each record as an array of values rented from an array pool.

public static ChannelReader<object[]> ToChannel(this IExecuteReader command, bool singleReader, ArrayPool<object> arrayPool)

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

arrayPool ArrayPool<object>

The array pool to rent each record's array from. The consumer of the channel is responsible for returning each array to the pool.

Returns

ChannelReader<object[]>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel<T>(IExecuteReader, bool, Func<IDataRecord, T>)

Starts reading the results of an IExecuteReader in the background and returns the reader of a new unbounded channel that receives each record after it has been transformed by transform.

public static ChannelReader<T> ToChannel<T>(this IExecuteReader command, bool singleReader, Func<IDataRecord, T> transform)

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item written to the channel.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type of the items written to the channel: the return type of the transform function.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel<T>(IExecuteReader, bool)

Starts reading the results of an IExecuteReader in the background and returns the reader of a new unbounded channel that receives each record mapped to a new instance of T.

public static ChannelReader<T> ToChannel<T>(this IExecuteReader command, bool singleReader) where T : new()

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type each record is mapped to.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel<T>(IExecuteReader, bool, IEnumerable<(string Field, string? Column)>)

Starts reading the results of an IExecuteReader in the background and returns the reader of a new unbounded channel that receives each record mapped to a new instance of T, using the field-to-column overrides.

public static ChannelReader<T> ToChannel<T>(this IExecuteReader command, bool singleReader, IEnumerable<(string Field, string? Column)> fieldMappingOverrides) where T : new()

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

singleReader bool

true if at most one consumer reads from the returned channel at a time, which lets the channel optimize for that; otherwise false.

fieldMappingOverrides IEnumerable<(string Field, string Column)>

An override map of field names to column names, applied on top of the default name-based mapping.

Returns

ChannelReader<T>

The reader of the channel that receives the records. Its Completion completes after the last record has been written, or faults with the exception that ended the reading.

Type Parameters

T

The type each record is mapped to.

Remarks

The call returns immediately without waiting for rows: reading begins at once and continues on a background task, and its failures are reported only through the returned reader's Completion. Await it, or read the channel until it is completed, to know when the work has finished.

The channel is unbounded, so a consumer that is slower than the database lets records accumulate in memory. Use the overloads that take a ChannelWriter<T> target, for example one of a bounded channel, when back-pressure is needed.

Exceptions

ArgumentNullException

command is null.

ToChannel(IDataReader, ChannelWriter<object[]>, bool, CancellationToken)

Iterates an IDataReader and writes each record as an array of values to the target channel.

public static ValueTask<long> ToChannel(this IDataReader reader, ChannelWriter<object[]> target, bool complete, CancellationToken cancellationToken = default)

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

target ChannelWriter<object[]>

The channel writer that receives the records.

complete bool

If true, the target is completed once all the records have been written to it (or the source is empty).

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records written to the target.

Exceptions

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel(IDataReader, ChannelWriter<object[]>, bool, ArrayPool<object>?, CancellationToken)

Iterates an IDataReader and writes each record as an array of values rented from an array pool to the target channel.

public static ValueTask<long> ToChannel(this IDataReader reader, ChannelWriter<object[]> target, bool complete, ArrayPool<object>? arrayPool, CancellationToken cancellationToken = default)

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

target ChannelWriter<object[]>

The channel writer that receives the records.

complete bool

If true, the target is completed once all the records have been written to it (or the source is empty).

arrayPool ArrayPool<object>

The array pool to rent each record's array from, or null to allocate new arrays. The consumer of the channel is responsible for returning each array to the pool.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records written to the target.

Exceptions

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel<T>(IDataReader, ChannelWriter<T>, bool, Func<IDataRecord, T>, CancellationToken)

Iterates an IDataReader and writes each record after it has been transformed by transform to the target channel.

public static ValueTask<long> ToChannel<T>(this IDataReader reader, ChannelWriter<T> target, bool complete, Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed once all the records have been written to it (or the source is empty).

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item written to the channel.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records written to the target.

Type Parameters

T

The type of the items written to the channel: the return type of the transform function.

Exceptions

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel<T>(IDataReader, ChannelWriter<T>, bool, CancellationToken)

Iterates an IDataReader and writes each record mapped to a new instance of T to the target channel.

public static ValueTask<long> ToChannel<T>(this IDataReader reader, ChannelWriter<T> target, bool complete, CancellationToken cancellationToken = default) where T : new()

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed after the last record has been delivered to it, or with the error that ended the operation.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records read. The task completes once all the records have been read; the records are delivered to the target by a second task, which may still be running.

Type Parameters

T

The type each record is mapped to.

Exceptions

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel<T>(IDataReader, ChannelWriter<T>, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Iterates an IDataReader and writes each record mapped to a new instance of T, using the field-to-column overrides to the target channel.

public static ValueTask<long> ToChannel<T>(this IDataReader reader, ChannelWriter<T> target, bool complete, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

reader IDataReader

The data reader to iterate. The caller owns it: it is not closed or disposed here, and it must stay open until the operation completes.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed after the last record has been delivered to it, or with the error that ended the operation.

fieldMappingOverrides IEnumerable<(string Field, string Column)>

An override map of field names to column names, applied on top of the default name-based mapping.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records read. The task completes once all the records have been read; the records are delivered to the target by a second task, which may still be running.

Type Parameters

T

The type each record is mapped to.

Exceptions

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel(IDbCommand, ChannelWriter<object[]>, bool, CancellationToken)

Iterates the results of an IDbCommand and writes each record as an array of values to the target channel.

public static ValueTask<long> ToChannel(this IDbCommand command, ChannelWriter<object[]> target, bool complete, CancellationToken cancellationToken = default)

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

target ChannelWriter<object[]>

The channel writer that receives the records.

complete bool

If true, the target is completed once the last record has been written to it and the database reader has been released, or with the error that ended the operation.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records written to the target.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

InvalidOperationException

The command has no connection.

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel(IDbCommand, ChannelWriter<object[]>, bool, ArrayPool<object>, CancellationToken)

Iterates the results of an IDbCommand and writes each record as an array of values rented from an array pool to the target channel.

public static ValueTask<long> ToChannel(this IDbCommand command, ChannelWriter<object[]> target, bool complete, ArrayPool<object> arrayPool, CancellationToken cancellationToken = default)

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

target ChannelWriter<object[]>

The channel writer that receives the records.

complete bool

If true, the target is completed once the last record has been written to it and the database reader has been released, or with the error that ended the operation.

arrayPool ArrayPool<object>

The array pool to rent each record's array from. The consumer of the channel is responsible for returning each array to the pool.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records written to the target.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

InvalidOperationException

The command has no connection.

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel<T>(IDbCommand, ChannelWriter<T>, bool, Func<IDataRecord, T>, CancellationToken)

Iterates the results of an IDbCommand and writes each record after it has been transformed by transform to the target channel.

public static ValueTask<long> ToChannel<T>(this IDbCommand command, ChannelWriter<T> target, bool complete, Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed once the last record has been written to it and the database reader has been released, or with the error that ended the operation.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item written to the channel.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records written to the target.

Type Parameters

T

The type of the items written to the channel: the return type of the transform function.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

InvalidOperationException

The command has no connection.

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel<T>(IDbCommand, ChannelWriter<T>, bool, CancellationToken)

Iterates the results of an IDbCommand and writes each record mapped to a new instance of T to the target channel.

public static ValueTask<long> ToChannel<T>(this IDbCommand command, ChannelWriter<T> target, bool complete, CancellationToken cancellationToken = default) where T : new()

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed after the last record has been delivered to it (or with the error that ended the operation), and only once the database reader has been released.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records read. The task completes once all the records have been read and the reader has been released; the records are delivered to the target by a second task, which may still be running.

Type Parameters

T

The type each record is mapped to.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

InvalidOperationException

The command has no connection.

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel<T>(IDbCommand, ChannelWriter<T>, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Iterates the results of an IDbCommand and writes each record mapped to a new instance of T, using the field-to-column overrides to the target channel.

public static ValueTask<long> ToChannel<T>(this IDbCommand command, ChannelWriter<T> target, bool complete, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

command IDbCommand

The command to execute. Its connection is opened if needed and closed again if it was opened here; neither the command nor the connection is disposed.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed after the last record has been delivered to it (or with the error that ended the operation), and only once the database reader has been released.

fieldMappingOverrides IEnumerable<(string Field, string Column)>

An override map of field names to column names, applied on top of the default name-based mapping.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records read. The task completes once all the records have been read and the reader has been released; the records are delivered to the target by a second task, which may still be running.

Type Parameters

T

The type each record is mapped to.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

InvalidOperationException

The command has no connection.

ChannelClosedException

The target has already been completed.

OperationCanceledException

The operation was canceled.

ToChannel(IExecuteReader, ChannelWriter<object[]>, bool)

Iterates the results of an IExecuteReader and writes each record as an array of values to the target channel.

public static ValueTask<long> ToChannel(this IExecuteReader command, ChannelWriter<object[]> target, bool complete)

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

target ChannelWriter<object[]>

The channel writer that receives the records.

complete bool

If true, the target is completed once the last record has been written to it and the database reader has been released, or with the error that ended the operation.

Returns

ValueTask<long>

The number of records written to the target.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

ChannelClosedException

The target has already been completed.

ToChannel(IExecuteReader, ChannelWriter<object[]>, bool, ArrayPool<object>)

Iterates the results of an IExecuteReader and writes each record as an array of values rented from an array pool to the target channel.

public static ValueTask<long> ToChannel(this IExecuteReader command, ChannelWriter<object[]> target, bool complete, ArrayPool<object> arrayPool)

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

target ChannelWriter<object[]>

The channel writer that receives the records.

complete bool

If true, the target is completed once the last record has been written to it and the database reader has been released, or with the error that ended the operation.

arrayPool ArrayPool<object>

The array pool to rent each record's array from. The consumer of the channel is responsible for returning each array to the pool.

Returns

ValueTask<long>

The number of records written to the target.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

ChannelClosedException

The target has already been completed.

ToChannel<T>(IExecuteReader, ChannelWriter<T>, bool, Func<IDataRecord, T>)

Iterates the results of an IExecuteReader and writes each record after it has been transformed by transform to the target channel.

public static ValueTask<long> ToChannel<T>(this IExecuteReader command, ChannelWriter<T> target, bool complete, Func<IDataRecord, T> transform)

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed once the last record has been written to it and the database reader has been released, or with the error that ended the operation.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item written to the channel.

Returns

ValueTask<long>

The number of records written to the target.

Type Parameters

T

The type of the items written to the channel: the return type of the transform function.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

ChannelClosedException

The target has already been completed.

ToChannel<T>(IExecuteReader, ChannelWriter<T>, bool)

Iterates the results of an IExecuteReader and writes each record mapped to a new instance of T to the target channel.

public static ValueTask<long> ToChannel<T>(this IExecuteReader command, ChannelWriter<T> target, bool complete) where T : new()

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed after the last record has been delivered to it (or with the error that ended the operation), and only once the database reader has been released.

Returns

ValueTask<long>

The number of records read. The task completes once all the records have been read and the reader has been released; the records are delivered to the target by a second task, which may still be running.

Type Parameters

T

The type each record is mapped to.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

ChannelClosedException

The target has already been completed.

ToChannel<T>(IExecuteReader, ChannelWriter<T>, bool, IEnumerable<(string Field, string? Column)>)

Iterates the results of an IExecuteReader and writes each record mapped to a new instance of T, using the field-to-column overrides to the target channel.

public static ValueTask<long> ToChannel<T>(this IExecuteReader command, ChannelWriter<T> target, bool complete, IEnumerable<(string Field, string? Column)> fieldMappingOverrides) where T : new()

Parameters

command IExecuteReader

The expressive command to execute. The connection follows the command's ownership rules: it is opened only if needed and released when reading finishes. The command's own cancellation token applies.

target ChannelWriter<T>

The channel writer that receives the records.

complete bool

If true, the target is completed after the last record has been delivered to it (or with the error that ended the operation), and only once the database reader has been released.

fieldMappingOverrides IEnumerable<(string Field, string Column)>

An override map of field names to column names, applied on top of the default name-based mapping.

Returns

ValueTask<long>

The number of records read. The task completes once all the records have been read and the reader has been released; the records are delivered to the target by a second task, which may still be running.

Type Parameters

T

The type each record is mapped to.

Remarks

If the connection is not already open, the operation first waits until the target can accept a write, then opens the connection; reading therefore starts immediately only when the connection is already open. To keep a connection open after the operation, open it before calling this method.

Exceptions

ArgumentNullException

command or target is null.

ChannelClosedException

The target has already been completed.