SqlCommand extensions for SqlDataReader execution - lobodava/artisan-orm GitHub Wiki

Artisan.Orm provides the following SqlCommand extensions which can be used within GetByCommand<T> and RunCommand SqlCommand initialization methods:

• Single-result To extensions which use registered mappers for entity types (or scalar conversion for supported simple types), with inline-mapper overloads also available — see Mappers:

  • cmd.ReadTo<T>
  • cmd.ReadToList<T>
  • cmd.ReadToArray<T>
  • cmd.ReadToObjectRow<T>
  • cmd.ReadToObjectRows<T>
  • cmd.ReadToDictionary<TKey, TValue>
  • cmd.ReadToEnumerable<T>

• Single Result As extensions which use auto mapping:

  • cmd.ReadAs<T>
  • cmd.ReadAsList<T>
  • cmd.ReadAsArray<T>
  • cmd.ReadAsObjectRow
  • cmd.ReadAsObjectRows
  • cmd.ReadAsDictionary<TKey, TValue>
  • cmd.ReadAsEnumerable<T>

• Multiple results extensions where data is read by SqlDataReader extensions:

  • cmd.GetByReader<T>(Func<SqlDataReader, T> func)
  • cmd.ExecuteReader(Action<SqlDataReader> action) — returns the T-SQL RETURN value after the callback finishes; this is not an affected-row count.
  • cmd.ReadToLists<T1, T2> through T1, T2, T3, T4 — typed tuples of lists, including async and inline-mapper overloads.

In the 4.1.0 preparation source, synchronous scalar enumeration includes the first row, and supplied factories are honored for scalar/nullable results as well as objects. SQL NULL in column zero does not suppress a supplied factory; it owns null handling and may read any column. See Inline Mappers for the projection contract and Read Methods Understanding for the version-specific corrections.

Materializing operations have async variants such as ReadToAsync, ReadToListAsync, and ReadAsListAsync. Deferred asynchronous streams use the names ReadToAsyncEnumerable / ReadAsAsyncEnumerable, not ReadToEnumerableAsync.

GetByReaderAsync takes Func<SqlDataReader, T> and ExecuteReaderAsync takes Action<SqlDataReader>. These callbacks are synchronous even though command execution is awaited. Do not pass an async lambda or return a reader-dependent deferred value from them: the reader is disposed when the callback returns. See cmd.GetByReader for signatures and token forwarding.

The helpers dispose readers they create and close a connection only when they opened it. Keep the command/repository alive throughout deferred enumeration. Reader-level materializing operations normally advance to the next result set; reader-level async streams do not and leave reader disposal to their caller.

In 4.1.0, async command materializers forward cancellation to connection opening, command execution, row reads, and result advancement. This does not make synchronous user callbacks asynchronous or automatically interrupt their work. See Streaming with IAsyncEnumerable for stream-specific lifetime behavior.

Sources: synchronous extensions, async extensions.

---

See also:

• Read Methods Understanding