Class ProcedureResult

Namespace

NextORM.Core

Assembly

nextorm.core.dll

The result of a raw command (ExecuteRaw(string, params IReadOnlyList<ProcedureParameter>)) or a stored procedure (ExecuteProcedure(string, params IReadOnlyList<ProcedureParameter>)). Owns the command and its data reader until disposed. The result object itself enumerates its column-bearing result sets: foreach (var set in result) or await foreach (var set in result) yields a ResultSet cursor per set. The legacy Read<T>() / ReadAsync<T>(CancellationToken) path reads sets positionally, each call advancing to the next set.

public sealed class ProcedureResult : IAsyncDisposable, IDisposable, IEnumerable<ResultSet>, IEnumerable, IAsyncEnumerable<ResultSet>

Inheritance

object

ProcedureResult

Implements

IAsyncDisposable

IDisposable

IEnumerable<ResultSet>

IEnumerable

IAsyncEnumerable<ResultSet>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

EntityBuilderExtensions.AsEntityBuilder<T>(object?)

Remarks

The first Read skips leading result sets without columns (DDL/DML statements executed before the result-bearing statement) and then reads the current set. Accessing OutputParameters or ReturnValue closes the reader (discarding any remaining result sets) so providers can populate ADO.NET output parameters. The connection stays owned by the context and is never closed by this object.

Properties

OutputParameters

The output and input/output parameters of the command, snapshotted when first accessed (DBNull normalized to null). Accessing this property closes the reader and discards any result sets not yet read.

public IReadOnlyList<ProcedureOutputParameter> OutputParameters { get; }

Property Value

IReadOnlyList<ProcedureOutputParameter>

RecordsAffected

The number of rows the command's DML statements affected, as reported by the provider, or -1 when the command has no affected-row metadata (a query) or when the value is not available yet. The value is captured when the reader is released — by Dispose() (DisposeAsync()) or implicitly when OutputParameters / ReturnValue closes it — and is not affected by how far the result sets were read. Reading this property never touches a reader: it is safe before, during and after disposal and does not throw once the result has been disposed.

public int RecordsAffected { get; }

Property Value

int

ReturnValue

The return value of the command (a parameter with ReturnValue), or null when the command declares none. Accessing this property closes the reader and discards any result sets not yet read.

public object? ReturnValue { get; }

Property Value

object

Methods

Dispose()

Releases the reader and the command. Safe to call more than once.

public void Dispose()

DisposeAsync()

Asynchronously releases the reader and the command. Safe to call more than once.

public ValueTask DisposeAsync()

Returns

ValueTask

A value task that completes once the reader and command are disposed.

GetAsyncEnumerator(CancellationToken)

Returns an async enumerator over the column-bearing result sets of the command in order, yielding a ResultSet cursor for each. See GetEnumerator() for the traversal semantics.

public IAsyncEnumerator<ResultSet> GetAsyncEnumerator(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels the traversal (including a slow provider move).

Returns

IAsyncEnumerator<ResultSet>

A one-shot, forward-only async sequence of result-set cursors; empty when there is none.

Exceptions

InvalidOperationException

Result sets were already traversed or read another way.

ObjectDisposedException

The result has been disposed.

GetEnumerator()

Returns an enumerator over the column-bearing result sets of the command in order, yielding a ResultSet cursor for each. Leading, intermediate and trailing result sets without columns (DDL/DML) are skipped and do not count toward Index; a set with columns but no rows is still yielded. Each set can be consumed once, eagerly with Read<T>() or lazily with ReadAsync<T>(CancellationToken).

public IEnumerator<ResultSet> GetEnumerator()

Returns

IEnumerator<ResultSet>

A one-shot, forward-only sequence of result-set cursors; empty when there is none.

Remarks

The outer iteration is one-shot and must not be mixed with the legacy Read<T>() / ReadAsync<T>(CancellationToken) sequence or with OutputParameters/ReturnValue while it is active. Disposing the outer enumerator invalidates its cursors but does not dispose this result or its reader.

Exceptions

InvalidOperationException

Result sets were already traversed or read another way.

ObjectDisposedException

The result has been disposed.

ReadAsync<T>(CancellationToken)

Asynchronously advances to the next result set (the first call reads the current one) and materializes all of its rows into T. Each call returns one set; when there are no more sets, an InvalidOperationException is thrown.

public IAsyncEnumerable<T> ReadAsync<T>(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels reading of the result set.

Returns

IAsyncEnumerable<T>

An async sequence over the rows of the current result set.

Type Parameters

T

A mapped entity type or a scalar type (see IRawCommandExecutor).

Remarks

This is a lazy async iterator: it advances to the next result set when enumeration starts, not when the method is called. Enumerate the returned sequence once; a second enumeration would try to read another result set.

Exceptions

InvalidOperationException

There are no further result sets.

ObjectDisposedException

The result has been disposed.

Read<T>()

Advances to the next result set (the first call reads the current one) and materializes all of its rows into T. Each call returns one set; when there are no more sets, an InvalidOperationException is thrown.

public IReadOnlyList<T> Read<T>()

Returns

IReadOnlyList<T>

The materialized rows of the current result set; empty when the set has no rows.

Type Parameters

T

A mapped entity type or a scalar type (see IRawCommandExecutor).

Exceptions

InvalidOperationException

There are no further result sets.

ObjectDisposedException

The result has been disposed.