Method ToTargetBlockAsync

Namespace

Open.Database.Extensions

Assembly

Open.Database.Extensions.Dataflow.dll

ToTargetBlockAsync(IDataReader, ITargetBlock<object[]>, bool, CancellationToken)

Asynchronously reads an IDataReader, sending each record as an array of values to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync(this IDataReader reader, ITargetBlock<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 ITargetBlock<object[]>

The block that receives the records.

complete bool

If true, the target is completed when reading ends (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records accepted by the target.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

Exceptions

ArgumentNullException

reader or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync(IDataReader, ITargetBlock<object[]>, bool, ArrayPool<object>, CancellationToken)

Asynchronously reads an IDataReader, sending each record as an array of values rented from an array pool to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync(this IDataReader reader, ITargetBlock<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 ITargetBlock<object[]>

The block that receives the records.

complete bool

If true, the target is completed when reading ends (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

arrayPool ArrayPool<object>

The array pool to rent each record's array from. The consumer of the records 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 accepted by the target.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

Exceptions

ArgumentNullException

reader or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync<T>(IDataReader, ITargetBlock<T>, bool, Func<IDataRecord, T>, CancellationToken)

Asynchronously reads an IDataReader, sending each record after it has been transformed by transform to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IDataReader reader, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed when reading ends (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item delivered to the block.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records accepted by the target.

Type Parameters

T

The type of the items delivered to the block: the return type of the transform function.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

Exceptions

ArgumentNullException

reader or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync<T>(IDataReader, ITargetBlock<T>, bool, CancellationToken)

Asynchronously reads an IDataReader, sending each record mapped to a new instance of T to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IDataReader reader, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed once the reader has been released and every record has been delivered to it (which can be after this method has returned), or faulted with the exception that ended the operation.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records read and handed to the internal buffer. Delivery to the target continues in the background, so some of them may not have reached it yet when this returns.

Type Parameters

T

The type each record is mapped to.

Remarks

Reading stops, without an error, as soon as the internal pipeline declines a record. Asynchronous database calls are used when the reader or command derives from the Db* base types.

Exceptions

ArgumentNullException

reader or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

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

Asynchronously reads an IDataReader, sending each record mapped to a new instance of T, using the field-to-column overrides to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IDataReader reader, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed once the reader has been released and every record has been delivered to it (which can be after this method has returned), or faulted with the exception 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 and handed to the internal buffer. Delivery to the target continues in the background, so some of them may not have reached it yet when this returns.

Type Parameters

T

The type each record is mapped to.

Remarks

Reading stops, without an error, as soon as the internal pipeline declines a record. Asynchronous database calls are used when the reader or command derives from the Db* base types.

Exceptions

ArgumentNullException

reader or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync(IDbCommand, ITargetBlock<object[]>, bool, CancellationToken)

Asynchronously reads the results of an IDbCommand, sending each record as an array of values to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync(this IDbCommand command, ITargetBlock<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 ITargetBlock<object[]>

The block that receives the records.

complete bool

If true, the target is completed when reading ends and the reader has been released (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records accepted by the target.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync(IDbCommand, ITargetBlock<object[]>, bool, ArrayPool<object>, CancellationToken)

Asynchronously reads the results of an IDbCommand, sending each record as an array of values rented from an array pool to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync(this IDbCommand command, ITargetBlock<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 ITargetBlock<object[]>

The block that receives the records.

complete bool

If true, the target is completed when reading ends and the reader has been released (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

arrayPool ArrayPool<object>

The array pool to rent each record's array from. The consumer of the records 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 accepted by the target.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync<T>(IDbCommand, ITargetBlock<T>, bool, Func<IDataRecord, T>, CancellationToken)

Asynchronously reads the results of an IDbCommand, sending each record after it has been transformed by transform to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IDbCommand command, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed when reading ends and the reader has been released (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item delivered to the block.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records accepted by the target.

Type Parameters

T

The type of the items delivered to the block: the return type of the transform function.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync<T>(IDbCommand, ITargetBlock<T>, bool, CancellationToken)

Asynchronously reads the results of an IDbCommand, sending each record mapped to a new instance of T to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IDbCommand command, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed once the reader has been released and every record has been delivered to it (which can be after this method has returned), or faulted with the exception that ended the operation.

cancellationToken CancellationToken

A token that can cancel the operation.

Returns

ValueTask<long>

The number of records read and handed to the internal buffer. Delivery to the target continues in the background, so some of them may not have reached it yet when this returns.

Type Parameters

T

The type each record is mapped to.

Remarks

Reading stops, without an error, as soon as the internal pipeline declines a record. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

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

Asynchronously reads the results of an IDbCommand, sending each record mapped to a new instance of T, using the field-to-column overrides to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IDbCommand command, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed once the reader has been released and every record has been delivered to it (which can be after this method has returned), or faulted with the exception 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 and handed to the internal buffer. Delivery to the target continues in the background, so some of them may not have reached it yet when this returns.

Type Parameters

T

The type each record is mapped to.

Remarks

Reading stops, without an error, as soon as the internal pipeline declines a record. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

OperationCanceledException

The operation was canceled.

ToTargetBlockAsync(IExecuteReader, ITargetBlock<object[]>, bool)

Asynchronously reads the results of an IExecuteReader, sending each record as an array of values to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync(this IExecuteReader command, ITargetBlock<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 ITargetBlock<object[]>

The block that receives the records.

complete bool

If true, the target is completed when reading ends and the reader has been released (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

Returns

ValueTask<long>

The number of records accepted by the target.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

ToTargetBlockAsync(IExecuteReader, ITargetBlock<object[]>, bool, ArrayPool<object>)

Asynchronously reads the results of an IExecuteReader, sending each record as an array of values rented from an array pool to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync(this IExecuteReader command, ITargetBlock<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 ITargetBlock<object[]>

The block that receives the records.

complete bool

If true, the target is completed when reading ends and the reader has been released (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

arrayPool ArrayPool<object>

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

Returns

ValueTask<long>

The number of records accepted by the target.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

ToTargetBlockAsync<T>(IExecuteReader, ITargetBlock<T>, bool, Func<IDataRecord, T>)

Asynchronously reads the results of an IExecuteReader, sending each record after it has been transformed by transform to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IExecuteReader command, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed when reading ends and the reader has been released (including when reading stops because the target declined a record), or faulted with the exception that ended the operation.

transform Func<IDataRecord, T>

The function that transforms each IDataRecord into the item delivered to the block.

Returns

ValueTask<long>

The number of records accepted by the target.

Type Parameters

T

The type of the items delivered to the block: the return type of the transform function.

Remarks

Records are sent with SendAsync<TInput>(ITargetBlock<TInput>, TInput, CancellationToken), which waits for room in a bounded target. A target that declines a record, for example because it is complete, stops the reading; the declined record has already been read and is not delivered. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

ToTargetBlockAsync<T>(IExecuteReader, ITargetBlock<T>, bool)

Asynchronously reads the results of an IExecuteReader, sending each record mapped to a new instance of T to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IExecuteReader command, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed once the reader has been released and every record has been delivered to it (which can be after this method has returned), or faulted with the exception that ended the operation.

Returns

ValueTask<long>

The number of records read and handed to the internal buffer. Delivery to the target continues in the background, so some of them may not have reached it yet when this returns.

Type Parameters

T

The type each record is mapped to.

Remarks

Reading stops, without an error, as soon as the internal pipeline declines a record. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.

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

Asynchronously reads the results of an IExecuteReader, sending each record mapped to a new instance of T, using the field-to-column overrides to the target block, and stops when the target declines a record.

public static ValueTask<long> ToTargetBlockAsync<T>(this IExecuteReader command, ITargetBlock<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 ITargetBlock<T>

The block that receives the records.

complete bool

If true, the target is completed once the reader has been released and every record has been delivered to it (which can be after this method has returned), or faulted with the exception 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.

Returns

ValueTask<long>

The number of records read and handed to the internal buffer. Delivery to the target continues in the background, so some of them may not have reached it yet when this returns.

Type Parameters

T

The type each record is mapped to.

Remarks

Reading stops, without an error, as soon as the internal pipeline declines a record. Asynchronous database calls are used when the reader or command derives from the Db* base types.

If a connection should stay open after the operation, open it before calling this method; a connection that this method opens is closed again when reading ends.

Exceptions

ArgumentNullException

command or target is null. The exception is reported through the returned task.