Class MultiReader

Namespace

Rinku

Assembly

Rinku.dll

Reads a command's several result sets in turn, mapping each to a type you pick as you go. Call Query<T>() once per set to take the whole set and move on, or Get<T>() and GetCurrentSetParser<T>() to walk a set row by row while keeping hold of the reader. It is itself a DbDataReader, so the raw reader methods stay available underneath.

public sealed class MultiReader : DbDataReader, IEnumerable, IDataReader, IDataRecord, IAsyncDisposable, IDisposable

Inheritance

object

MarshalByRefObject

DbDataReader

MultiReader

Implements

IEnumerable

IDataReader

IDataRecord

IAsyncDisposable

IDisposable

Inherited Members

DbDataReader.GetFieldValueAsync<T>(int)

DbDataReader.IsDBNullAsync(int)

DbDataReader.NextResultAsync()

DbDataReader.ReadAsync()

MarshalByRefObject.GetLifetimeService()

MarshalByRefObject.InitializeLifetimeService()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

Helper.GetColumns(DbDataReader)

Helper.GetColumnsFast(DbDataReader)

Caster.Parse<T>(object?)

Constructors

MultiReader(bool[], QueryCommand, DbDataReader, IDbCommand, bool, bool)

Reads a command's several result sets in turn, mapping each to a type you pick as you go. Call Query<T>() once per set to take the whole set and move on, or Get<T>() and GetCurrentSetParser<T>() to walk a set row by row while keeping hold of the reader. It is itself a DbDataReader, so the raw reader methods stay available underneath.

public MultiReader(bool[] usage, QueryCommand command, DbDataReader reader, IDbCommand cmd, bool disposeCmd, bool wasClosed)

Parameters

usage bool[]

command QueryCommand

reader DbDataReader

cmd IDbCommand

disposeCmd bool

wasClosed bool

Properties

Depth

Gets a value indicating the depth of nesting for the current row.

public override int Depth { get; }

Property Value

int

The depth of nesting for the current row.

FieldCount

When overridden in a derived class, gets the number of columns in the current row.

public override int FieldCount { get; }

Property Value

int

The number of columns in the current row.

Exceptions

NotSupportedException

There is no current connection to an instance of SQL Server.

HasRows

When overridden in a derived class, gets a value that indicates whether this DbDataReader contains one or more rows.

public override bool HasRows { get; }

Property Value

bool

true if the DbDataReader contains one or more rows; otherwise, false.

IsClosed

When overridden in a derived class, gets a value indicating whether the DbDataReader is closed.

public override bool IsClosed { get; }

Property Value

bool

true if the DbDataReader is closed; otherwise, false.

Exceptions

InvalidOperationException

The DbDataReader is closed.

this[int]

When overridden in a derived class, gets the value of the specified column as an instance of object.

public override object this[int ordinal] { get; }

Parameters

ordinal int

The zero-based column ordinal.

Property Value

object

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

this[string]

When overridden in a derived class, gets the value of the specified column as an instance of object.

public override object this[string name] { get; }

Parameters

name string

The name of the column.

Property Value

object

The value of the specified column.

Exceptions

IndexOutOfRangeException

No column with the specified name was found.

RecordsAffected

When overridden in a derived class, gets the number of rows changed, inserted, or deleted by execution of the SQL statement.

public override int RecordsAffected { get; }

Property Value

int

The number of rows changed, inserted, or deleted. -1 for SELECT statements; 0 if no rows were affected or the statement failed.

VisibleFieldCount

Gets the number of fields in the DbDataReader that are not hidden.

public override int VisibleFieldCount { get; }

Property Value

int

The number of fields that are not hidden.

Methods

Close()

Closes the DbDataReader object.

public override void Close()

CloseAsync()

Asynchronously closes the DbDataReader object.

public override Task CloseAsync()

Returns

Task

A task representing the asynchronous operation.

Dispose()

public void Dispose()

Dispose(bool)

Releases the unmanaged resources used by the DbDataReader and optionally releases the managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release managed and unmanaged resources; false to release only unmanaged resources.

DisposeAsync()

Asynchronously releases all resources used by the current instance of the DbDataReader class.

public override ValueTask DisposeAsync()

Returns

ValueTask

A ValueTask representing the asynchronous operation.

GetAsync<T>(CancellationToken)

Parses starting at the current row in the current result set, does not change result set. The parser advances the reader, and CanContinue reports its state on return, true when it is left on an untreated row

public ValueTask<(bool CanContinue, T Result)> GetAsync<T>(CancellationToken ct = default)

Parameters

ct CancellationToken

The forwarded cancellation token

Returns

ValueTask<(bool CanContinue, T Result)>

Type Parameters

T

GetBoolean(int)

When overridden in a derived class, gets the value of the specified column as a Boolean.

public override bool GetBoolean(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

bool

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetByte(int)

When overridden in a derived class, gets the value of the specified column as a byte.

public override byte GetByte(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

byte

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetBytes(int, long, byte[]?, int, int)

When overridden in a derived class, reads a specified number of bytes from the specified column starting at a specified index and writes them to a buffer starting at a specified position in the buffer.

public override long GetBytes(int ordinal, long dataOffset, byte[]? buffer, int bufferOffset, int length)

Parameters

ordinal int

The zero-based column ordinal.

dataOffset long

The index within the row from which to begin the read operation.

buffer byte[]

The buffer into which to copy the data.

bufferOffset int

The index with the buffer to which the data will be copied.

length int

The maximum number of bytes to read.

Returns

long

The actual number of bytes read.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetChar(int)

When overridden in a derived class, gets the value of the specified column as a single character.

public override char GetChar(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

char

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetChars(int, long, char[]?, int, int)

When overridden in a derived class, reads a specified number of characters from a specified column starting at a specified index, and writes them to a buffer starting at a specified position.

public override long GetChars(int ordinal, long dataOffset, char[]? buffer, int bufferOffset, int length)

Parameters

ordinal int

The zero-based column ordinal.

dataOffset long

The index within the row from which to begin the read operation.

buffer char[]

The buffer into which to copy the data.

bufferOffset int

The index with the buffer to which the data will be copied.

length int

The maximum number of characters to read.

Returns

long

The actual number of characters read.

GetColumnSchemaAsync(CancellationToken)

This is the asynchronous version of GetColumnSchema(DbDataReader). Providers should override with an appropriate implementation. The cancellationToken can optionally be honored. The default implementation invokes the synchronous GetColumnSchema(DbDataReader) call and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellationToken. Exceptions thrown by GetColumnSchema(DbDataReader) will be communicated via the returned Task Exception property.

public override Task<ReadOnlyCollection<DbColumn>> GetColumnSchemaAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation instruction.

Returns

Task<ReadOnlyCollection<DbColumn>>

A task representing the asynchronous operation.

Exceptions

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

GetCurrentSetParser(Type)

Returns the current result set parser for a runtime result type.

public ITypeParser GetCurrentSetParser(Type resultType)

Parameters

resultType Type

Returns

ITypeParser

GetCurrentSetParser<T>()

The current set's parser, to parse rows yourself while keeping control of the reader.

public ITypeParser<T> GetCurrentSetParser<T>()

Returns

ITypeParser<T>

Type Parameters

T

GetDataTypeName(int)

When overridden in a derived class, gets name of the data type of the specified column.

public override string GetDataTypeName(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

string

The name of the data type.

Exceptions

IndexOutOfRangeException

The column index is out of range.

GetDateTime(int)

When overridden in a derived class, gets the value of the specified column as a DateTime object.

public override DateTime GetDateTime(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

DateTime

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetDecimal(int)

When overridden in a derived class, gets the value of the specified column as a decimal.

public override decimal GetDecimal(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

decimal

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetDouble(int)

When overridden in a derived class, gets the value of the specified column as a double-precision floating point number.

public override double GetDouble(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

double

The value of the specified column.

Exceptions

InvalidCastException

The specified cast is not valid.

GetEnumerator()

When overridden in a derived class, returns an enumerator that can be used to iterate through the rows in the data reader.

public override IEnumerator GetEnumerator()

Returns

IEnumerator

An enumerator that can be used to iterate through the rows in the data reader.

GetFieldType(int)

When overridden in a derived class, gets the data type of the specified column.

public override Type GetFieldType(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

Type

The data type of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetFieldValueAsync<T>(int, CancellationToken)

Asynchronously gets the value of the specified column as the requested type.

public override Task<T> GetFieldValueAsync<T>(int ordinal, CancellationToken cancellationToken)

Parameters

ordinal int

The zero-based column ordinal.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<T>

A task whose Result contains the value of the specified column.

Type Parameters

T

The type of the value to be returned.

Exceptions

InvalidOperationException

The connection was dropped or closed during data retrieval.

-or-

The data reader was closed during the data retrieval.

-or-

There is no data ready to be read (for example, the first Read() hasn't been called, or it returned false).

-or-

Tried to read a previously-read column in sequential mode.

-or-

There was an asynchronous operation in progress. This applies to all Get_*_ methods when running in sequential mode, as they could be called while reading a stream.

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The value returned by the database doesn't match or cannot be cast to T.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

GetFieldValue<T>(int)

Gets the value of the specified column as the requested type.

public override T GetFieldValue<T>(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

T

The value of the specified column.

Type Parameters

T

The type of the value to be returned.

Exceptions

InvalidOperationException

The connection was dropped or closed during data retrieval.

-or-

The data reader was closed during data retrieval.

-or-

There is no data ready to be read (for example, the first Read() hasn't been called, or it returned false).

-or-

The reader tried to read a previously-read column in sequential mode.

-or-

There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The value returned by the database doesn't match or cannot be cast to T.

GetFloat(int)

When overridden in a derived class, gets the value of the specified column as a single-precision floating point number.

public override float GetFloat(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

float

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetGuid(int)

When overridden in a derived class, gets the value of the specified column as a globally unique identifier (GUID).

public override Guid GetGuid(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

Guid

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetInt16(int)

When overridden in a derived class, gets the value of the specified column as a 16-bit signed integer.

public override short GetInt16(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

short

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetInt32(int)

When overridden in a derived class, gets the value of the specified column as a 32-bit signed integer.

public override int GetInt32(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

int

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetInt64(int)

When overridden in a derived class, gets the value of the specified column as a 64-bit signed integer.

public override long GetInt64(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

long

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetName(int)

When overridden in a derived class, gets the name of the column, given the zero-based column ordinal.

public override string GetName(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

string

The name of the specified column.

GetOrdinal(string)

When overridden in a derived class, gets the column ordinal given the name of the column.

public override int GetOrdinal(string name)

Parameters

name string

The name of the column.

Returns

int

The zero-based column ordinal.

Exceptions

IndexOutOfRangeException

The name specified is not a valid column name.

GetProviderSpecificFieldType(int)

Gets the provider-specific type of the specified column.

public override Type GetProviderSpecificFieldType(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

Type

A provider-specific .NET type.

Exceptions

IndexOutOfRangeException

The column index is out of range.

GetProviderSpecificValue(int)

Gets the value of the specified column as an instance of a provider-specific type.

public override object GetProviderSpecificValue(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

object

The value of the specified column.

GetProviderSpecificValues(object[])

Gets all provider-specific attribute columns in the collection for the current row.

public override int GetProviderSpecificValues(object[] values)

Parameters

values object[]

An array of object into which to copy the attribute columns.

Returns

int

The number of instances of elements in the array.

GetSchemaTable()

Returns a DataTable that describes the column metadata of the DbDataReader. Returns null if the executed command returned no resultset, or after NextResult() returns false.

public override DataTable? GetSchemaTable()

Returns

DataTable

A DataTable that describes the column metadata.

Exceptions

InvalidOperationException

The DbDataReader is closed.

IndexOutOfRangeException

The column index is out of range.

NotSupportedException

.NET Core and .NET 5+ only: In all cases.

GetSchemaTableAsync(CancellationToken)

This is the asynchronous version of GetSchemaTable(). Providers should override with an appropriate implementation. The cancellationToken can optionally be honored. The default implementation invokes the synchronous GetSchemaTable() call and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellationToken. Exceptions thrown by GetSchemaTable() will be communicated via the returned Task Exception property.

public override Task<DataTable?> GetSchemaTableAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation instruction.

Returns

Task<DataTable>

A task representing the asynchronous operation.

Exceptions

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

GetStream(int)

Gets a stream to retrieve data from the specified column.

public override Stream GetStream(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

Stream

A stream.

Exceptions

InvalidOperationException

The connection was dropped or closed during the data retrieval.

-or-

The data reader is closed during the data retrieval.

-or-

There is no data ready to be read (for example, the first Read() hasn't been called, or returned false).

-or-

The data reader tried to read a previously-read column in sequential mode.

-or-

There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified column isn't a binary type that supports reading with a Stream.

GetString(int)

When overridden in a derived class, gets the value of the specified column as an instance of string.

public override string GetString(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

string

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified cast is not valid.

GetTextReader(int)

Gets a text reader to retrieve data from the column.

public override TextReader GetTextReader(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

TextReader

A text reader.

Exceptions

InvalidOperationException

The connection was dropped or closed during the data retrieval.

-or-

The data reader is closed during the data retrieval.

-or-

There is no data ready to be read (for example, the first Read() hasn't been called, or returned false).

-or-

The data reader tried to read a previously-read column in sequential mode.

-or-

There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.

IndexOutOfRangeException

The column index is out of range.

InvalidCastException

The specified column isn't a text type that supports reading with a TextReader.

GetValue(int)

When overridden in a derived class, gets the value of the specified column as an instance of object.

public override object GetValue(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

object

The value of the specified column.

Exceptions

IndexOutOfRangeException

The column index is out of range.

GetValues(object[])

When overridden in a derived class, populates an array of objects with the column values of the current row.

public override int GetValues(object[] values)

Parameters

values object[]

An array of object into which to copy the attribute columns.

Returns

int

The number of instances of object in the array.

Get<T>()

Parses starting at the current row in the current result set, does not change result set. The parser advances the reader, and CanContinue reports its state on return, true when it is left on an untreated row

public (bool CanContinue, T Result) Get<T>()

Returns

(bool CanContinue, T Result)

Type Parameters

T

IsDBNull(int)

When overridden in a derived class, gets a value that indicates whether the column contains nonexistent or missing values.

public override bool IsDBNull(int ordinal)

Parameters

ordinal int

The zero-based column ordinal.

Returns

bool

true if the specified column is equivalent to DBNull; otherwise, false.

Exceptions

IndexOutOfRangeException

The column index is out of range.

IsDBNullAsync(int, CancellationToken)

Asynchronously gets a value that indicates whether the column contains non-existent or missing values.

public override Task<bool> IsDBNullAsync(int ordinal, CancellationToken cancellationToken)

Parameters

ordinal int

The zero-based column to be retrieved.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<bool>

A Task<TResult> whose Result property is true if the specified column value is equivalent to DBNull or false if it is not.

Exceptions

InvalidOperationException

The connection was dropped or closed during the data retrieval.

-or-

The data reader is closed during the data retrieval.

-or-

There is no data ready to be read (for example, the first Read() hasn't been called, or returned false).

-or-

Trying to read a previously read column in sequential mode.

-or-

There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.

IndexOutOfRangeException

The column index is out of range.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

NextResult()

When overridden in a derived class, advances the reader to the next result when reading the results of a batch of statements.

public override bool NextResult()

Returns

bool

true if there are more result sets; otherwise, false.

NextResultAsync(CancellationToken)

Asynchronously advances the reader to the next result when reading the results of a batch of statements.

public override Task<bool> NextResultAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation instruction.

Returns

Task<bool>

A Task<TResult> whose Result property is true if there are more result sets or false if there aren't.

Exceptions

DbException

An error occurred while executing the command text.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

Query(Type)

Parses the current result set in the complete shape selected by resultType.

public object Query(Type resultType)

Parameters

resultType Type

Returns

object

QueryAsync(Type, CancellationToken)

Asynchronously parses the current result set in the complete shape selected by resultType.

public ValueTask<object> QueryAsync(Type resultType, CancellationToken ct = default)

Parameters

resultType Type

ct CancellationToken

Returns

ValueTask<object>

QueryAsync<T>(CancellationToken)

Asynchronously parses the current returning result set as T, then moves to the next result set. Non-returning sets are skipped only when a query reaches them. The result shape defines zero-row and row-count behavior. To parse a set row by row and keep control of the reader, use GetAsync<T>(CancellationToken) or GetCurrentSetParser<T>()

public ValueTask<T> QueryAsync<T>(CancellationToken ct = default)

Parameters

ct CancellationToken

The forwarded cancellation token

Returns

ValueTask<T>

Type Parameters

T

Query<T>()

Parses the current returning result set as T, then moves to the next result set. Non-returning sets are skipped only when a query reaches them. The result shape defines zero-row and row-count behavior. To parse a set row by row and keep control of the reader, use Get<T>() or GetCurrentSetParser<T>()

public T Query<T>()

Returns

T

Type Parameters

T

Read()

When overridden in a derived class, advances the reader to the next record in a result set.

public override bool Read()

Returns

bool

true if there are more rows; otherwise, false.

ReadAsync(CancellationToken)

Asynchronously advances the reader to the next record in a result set.

public override Task<bool> ReadAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation instruction.

Returns

Task<bool>

A Task<TResult> whose Result property is true if there are more rows or false if there aren't.

Exceptions

DbException

An error occurred while executing the command text.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

StreamQueryAsync<T>(bool, CancellationToken)

Asynchronously lazily parses the current returning result set and advances when enumeration completes or its enumerator is disposed. Non-returning sets are skipped only when a query reaches them.

public IAsyncEnumerable<T> StreamQueryAsync<T>(bool goToNextResultSet = true, CancellationToken ct = default)

Parameters

goToNextResultSet bool

Whether ending or disposing the enumeration moves to the next result set.

ct CancellationToken

The forwarded cancellation token

Returns

IAsyncEnumerable<T>

Type Parameters

T

ToString()

Returns a string that represents the current object.

public override string? ToString()

Returns

string

A string that represents the current object.