Method ToChannelAsync

Namespace

Open.Database.Extensions

Assembly

Open.Database.Extensions.Channel.dll

ToChannelAsync(DbDataReader, bool, CancellationToken)

Starts asynchronously reading a DbDataReader 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[]> ToChannelAsync(this DbDataReader reader, bool singleReader, CancellationToken cancellationToken = default)

Parameters

reader DbDataReader

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.

ToChannelAsync(DbDataReader, bool, ArrayPool<object>, CancellationToken)

Starts asynchronously reading a DbDataReader 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[]> ToChannelAsync(this DbDataReader reader, bool singleReader, ArrayPool<object> arrayPool, CancellationToken cancellationToken = default)

Parameters

reader DbDataReader

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

ToChannelAsync<T>(DbDataReader, bool, Func<IDataRecord, T>, CancellationToken)

Starts asynchronously reading a DbDataReader 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> ToChannelAsync<T>(this DbDataReader reader, bool singleReader, Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)

Parameters

reader DbDataReader

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.

ToChannelAsync<T>(DbDataReader, bool, CancellationToken)

Starts asynchronously reading a DbDataReader 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> ToChannelAsync<T>(this DbDataReader reader, bool singleReader, CancellationToken cancellationToken = default) where T : new()

Parameters

reader DbDataReader

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.

ToChannelAsync<T>(DbDataReader, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Starts asynchronously reading a DbDataReader 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> ToChannelAsync<T>(this DbDataReader reader, bool singleReader, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

reader DbDataReader

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.

ToChannelAsync(DbCommand, bool, CancellationToken)

Starts asynchronously reading the results of a DbCommand 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[]> ToChannelAsync(this DbCommand command, bool singleReader, CancellationToken cancellationToken = default)

Parameters

command DbCommand

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.

ToChannelAsync(DbCommand, bool, ArrayPool<object>, CancellationToken)

Starts asynchronously reading the results of a DbCommand 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[]> ToChannelAsync(this DbCommand command, bool singleReader, ArrayPool<object> arrayPool, CancellationToken cancellationToken = default)

Parameters

command DbCommand

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.

ToChannelAsync<T>(DbCommand, bool, Func<IDataRecord, T>, CancellationToken)

Starts asynchronously reading the results of a DbCommand 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> ToChannelAsync<T>(this DbCommand command, bool singleReader, Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)

Parameters

command DbCommand

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.

ToChannelAsync<T>(DbCommand, bool, CancellationToken)

Starts asynchronously reading the results of a DbCommand 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> ToChannelAsync<T>(this DbCommand command, bool singleReader, CancellationToken cancellationToken = default) where T : new()

Parameters

command DbCommand

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.

ToChannelAsync<T>(DbCommand, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Starts asynchronously reading the results of a DbCommand 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> ToChannelAsync<T>(this DbCommand command, bool singleReader, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

command DbCommand

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.

ToChannelAsync(IExecuteReaderAsync, bool)

Starts asynchronously reading the results of an IExecuteReaderAsync 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[]> ToChannelAsync(this IExecuteReaderAsync command, bool singleReader)

Parameters

command IExecuteReaderAsync

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.

ToChannelAsync(IExecuteReaderAsync, bool, ArrayPool<object>?)

Starts asynchronously reading the results of an IExecuteReaderAsync 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[]> ToChannelAsync(this IExecuteReaderAsync command, bool singleReader, ArrayPool<object>? arrayPool)

Parameters

command IExecuteReaderAsync

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, or null to allocate new arrays. 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.

ToChannelAsync<T>(IExecuteReaderAsync, bool, Func<IDataRecord, T>)

Starts asynchronously reading the results of an IExecuteReaderAsync 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> ToChannelAsync<T>(this IExecuteReaderAsync command, bool singleReader, Func<IDataRecord, T> transform)

Parameters

command IExecuteReaderAsync

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.

ToChannelAsync<T>(IExecuteReaderAsync, bool)

Starts asynchronously reading the results of an IExecuteReaderAsync 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> ToChannelAsync<T>(this IExecuteReaderAsync command, bool singleReader) where T : new()

Parameters

command IExecuteReaderAsync

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.

ToChannelAsync<T>(IExecuteReaderAsync, bool, IEnumerable<(string Field, string? Column)>)

Starts asynchronously reading the results of an IExecuteReaderAsync 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> ToChannelAsync<T>(this IExecuteReaderAsync command, bool singleReader, IEnumerable<(string Field, string? Column)> fieldMappingOverrides) where T : new()

Parameters

command IExecuteReaderAsync

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.

ToChannelAsync(DbDataReader, ChannelWriter<object[]>, bool, CancellationToken)

Asynchronously iterates a DbDataReader and writes each record as an array of values to the target channel.

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

Parameters

reader DbDataReader

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.

ToChannelAsync(DbDataReader, ChannelWriter<object[]>, bool, ArrayPool<object>?, CancellationToken)

Asynchronously iterates a DbDataReader and writes each record as an array of values rented from an array pool to the target channel.

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

Parameters

reader DbDataReader

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.

ToChannelAsync<T>(DbDataReader, ChannelWriter<T>, bool, Func<IDataRecord, T>, CancellationToken)

Asynchronously iterates a DbDataReader and writes each record after it has been transformed by transform to the target channel.

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

Parameters

reader DbDataReader

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.

ToChannelAsync<T>(DbDataReader, ChannelWriter<T>, bool, CancellationToken)

Asynchronously iterates a DbDataReader and writes each record mapped to a new instance of T to the target channel.

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

Parameters

reader DbDataReader

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.

ToChannelAsync<T>(DbDataReader, ChannelWriter<T>, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Asynchronously iterates a DbDataReader 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> ToChannelAsync<T>(this DbDataReader reader, ChannelWriter<T> target, bool complete, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

reader DbDataReader

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.

ToChannelAsync(DbCommand, ChannelWriter<object[]>, bool, CancellationToken)

Asynchronously iterates the results of a DbCommand and writes each record as an array of values to the target channel.

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

Parameters

command DbCommand

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.

ToChannelAsync(DbCommand, ChannelWriter<object[]>, bool, ArrayPool<object>, CancellationToken)

Asynchronously iterates the results of a DbCommand and writes each record as an array of values rented from an array pool to the target channel.

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

Parameters

command DbCommand

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.

ToChannelAsync<T>(DbCommand, ChannelWriter<T>, bool, Func<IDataRecord, T>, CancellationToken)

Asynchronously iterates the results of a DbCommand and writes each record after it has been transformed by transform to the target channel.

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

Parameters

command DbCommand

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.

ToChannelAsync<T>(DbCommand, ChannelWriter<T>, bool, CancellationToken)

Asynchronously iterates the results of a DbCommand and writes each record mapped to a new instance of T to the target channel.

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

Parameters

command DbCommand

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.

ToChannelAsync<T>(DbCommand, ChannelWriter<T>, bool, IEnumerable<(string Field, string? Column)>, CancellationToken)

Asynchronously iterates the results of a DbCommand 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> ToChannelAsync<T>(this DbCommand command, ChannelWriter<T> target, bool complete, IEnumerable<(string Field, string? Column)> fieldMappingOverrides, CancellationToken cancellationToken = default) where T : new()

Parameters

command DbCommand

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.

ToChannelAsync(IExecuteReaderAsync, ChannelWriter<object[]>, bool)

Asynchronously iterates the results of an IExecuteReaderAsync and writes each record as an array of values to the target channel.

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

Parameters

command IExecuteReaderAsync

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.

ToChannelAsync(IExecuteReaderAsync, ChannelWriter<object[]>, bool, ArrayPool<object>?)

Asynchronously iterates the results of an IExecuteReaderAsync and writes each record as an array of values rented from an array pool to the target channel.

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

Parameters

command IExecuteReaderAsync

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, or null to allocate new arrays. 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.

ToChannelAsync<T>(IExecuteReaderAsync, ChannelWriter<T>, bool, Func<IDataRecord, T>)

Asynchronously iterates the results of an IExecuteReaderAsync and writes each record after it has been transformed by transform to the target channel.

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

Parameters

command IExecuteReaderAsync

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.

ToChannelAsync<T>(IExecuteReaderAsync, ChannelWriter<T>, bool)

Asynchronously iterates the results of an IExecuteReaderAsync and writes each record mapped to a new instance of T to the target channel.

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

Parameters

command IExecuteReaderAsync

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.

ToChannelAsync<T>(IExecuteReaderAsync, ChannelWriter<T>, bool, IEnumerable<(string Field, string? Column)>)

Asynchronously iterates the results of an IExecuteReaderAsync 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> ToChannelAsync<T>(this IExecuteReaderAsync command, ChannelWriter<T> target, bool complete, IEnumerable<(string Field, string? Column)> fieldMappingOverrides) where T : new()

Parameters

command IExecuteReaderAsync

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.