Updated to 5.7.0

Improved transaction methods.
Added cancellation tokens where possible.
Updated documentation.

Author: Oren (electricessence)

ExpressiveCommandBase.cs

@@ -298,7 +298,7 @@ public void Execute(Action<TCommand> handler)
                     var c = cmd as TCommand;
                     if (c == null) throw new InvalidCastException($"Actual command type ({cmd.GetType()}) is not compatible with expected command type ({typeof(TCommand)}).");
                     AddParams(c);
-                    con.Open();
+                    con.EnsureOpen();
                     handler(c);
                 }
             });
@@ -318,7 +318,7 @@ public T Execute<T>(Func<TCommand, T> transform)
                     var c = cmd as TCommand;
                     if (c == null) throw new InvalidCastException($"Actual command type ({cmd.GetType()}) is not compatible with expected command type ({typeof(TCommand)}).");
                     AddParams(c);
-                    con.Open();
+                    con.EnsureOpen();
                     return transform(c);
                 }
             });
@@ -339,7 +339,7 @@ public object ExecuteReturn()
                     var returnParameter = c.CreateParameter();
                     returnParameter.Direction = ParameterDirection.ReturnValue;
                     c.Parameters.Add(returnParameter);
-                    con.Open();
+                    con.EnsureOpen();
                     c.ExecuteNonQuery();
                     return returnParameter.Value;
                 }
@@ -368,7 +368,7 @@ protected IEnumerable<T> IterateReaderInternal<T>(Func<IDataRecord, T> transform
                     var c = cmd as TCommand;
                     if (c == null) throw new InvalidCastException($"Actual command type ({cmd.GetType()}) is not compatible with expected command type ({typeof(TCommand)}).");
                     AddParams(c);
-                    con.Open();
+                    con.EnsureOpen();
                     using (var reader = c.ExecuteReader(CommandBehavior.CloseConnection))
                     {
                         while (reader.Read())

ExpressiveDbCommandBase.cs

@@ -2,61 +2,76 @@
 using System.Data;
 using System.Data.Common;
 using System.Linq;
+using System.Threading;
 using System.Threading.Tasks;
 
 namespace Open.Database.Extensions
 {
     public static partial class Extensions
     {
-        /// <summary>
-        /// Asynchronously returns all records and iteratively attempts to map the fields to type T.
-        /// </summary>
-        /// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
-        /// <param name="reader">The IDataReader to read results from.</param>
-        /// <param name="fieldMappingOverrides">An override map of field names to column names where the keys are the property names, and values are the column names.</param>
-        /// <returns>A task containing the list of results.</returns>
-        public static async Task<IEnumerable<T>> ResultsAsync<T>(this DbDataReader reader, IEnumerable<(string Field, string Column)> fieldMappingOverrides) where T : new()
+		/// <summary>
+		/// Asynchronously returns all records and iteratively attempts to map the fields to type T.
+		/// </summary>
+		/// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
+		/// <param name="reader">The IDataReader to read results from.</param>
+		/// <param name="fieldMappingOverrides">An override map of field names to column names where the keys are the property names, and values are the column names.</param>
+		/// <param name="token">Optional cancellation token.</param>
+		/// <returns>A task containing the list of results.</returns>
+		public static async Task<IEnumerable<T>> ResultsAsync<T>(this DbDataReader reader, IEnumerable<(string Field, string Column)> fieldMappingOverrides, CancellationToken? token = null) where T : new()
         {
-            if (!await reader.ReadAsync()) return Enumerable.Empty<T>();
+			var t = token ?? CancellationToken.None;
+			if (!await reader.ReadAsync(t)) return Enumerable.Empty<T>();
 
             var x = new Transformer<T>(fieldMappingOverrides);
             // Ignore missing columns.
             var columns = reader.GetMatchingOrdinals(x.ColumnNames, true);
 
-            return x.AsDequeueingEnumerable(await RetrieveAsyncInternal(reader,
-                columns.Select(c => c.Ordinal).ToArray(),
+            return x.AsDequeueingEnumerable(await RetrieveAsyncInternal(reader, t,
+				columns.Select(c => c.Ordinal).ToArray(),
                 columns.Select(c => c.Name).ToArray(), readStarted: true));
         }
 
-        /// <summary>
-        /// Asynchronously returns all records and iteratively attempts to map the fields to type T.
-        /// </summary>
-        /// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
-        /// <param name="reader">The IDataReader to read results from.</param>
-        /// <param name="fieldMappingOverrides">An override map of field names to column names where the keys are the property names, and values are the column names.</param>
-        /// <returns>A task containing the list of results.</returns>
-        public static Task<IEnumerable<T>> ResultsAsync<T>(this DbDataReader reader, IEnumerable<KeyValuePair<string, string>> fieldMappingOverrides) where T : new()
-            => ResultsAsync<T>(reader, fieldMappingOverrides?.Select(kvp => (kvp.Key, kvp.Value)));
-
-        /// <summary>
-        /// Asynchronously returns all records and iteratively attempts to map the fields to type T.
-        /// </summary>
-        /// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
-        /// <param name="reader">The IDataReader to read results from.</param>
-        /// <param name="fieldMappingOverrides">An override map of field names to column names where the keys are the property names, and values are the column names.</param>
-        /// <returns>A task containing the list of results.</returns>
-        public static Task<IEnumerable<T>> ResultsAsync<T>(this DbDataReader reader, params (string Field, string Column)[] fieldMappingOverrides) where T : new()
+		/// <summary>
+		/// Asynchronously returns all records and iteratively attempts to map the fields to type T.
+		/// </summary>
+		/// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
+		/// <param name="reader">The IDataReader to read results from.</param>
+		/// <param name="fieldMappingOverrides">An override map of field names to column names where the keys are the property names, and values are the column names.</param>
+		/// <param name="token">Optional cancellation token.</param>
+		/// <returns>A task containing the list of results.</returns>
+		public static Task<IEnumerable<T>> ResultsAsync<T>(this DbDataReader reader, IEnumerable<KeyValuePair<string, string>> fieldMappingOverrides, CancellationToken? token = null) where T : new()
+            => ResultsAsync<T>(reader, fieldMappingOverrides?.Select(kvp => (kvp.Key, kvp.Value)), token);
+
+		/// <summary>
+		/// Asynchronously returns all records and iteratively attempts to map the fields to type T.
+		/// </summary>
+		/// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
+		/// <param name="reader">The IDataReader to read results from.</param>
+		/// <param name="fieldMappingOverrides">An override map of field names to column names where the keys are the property names, and values are the column names.</param>
+		/// <returns>A task containing the list of results.</returns>
+		public static Task<IEnumerable<T>> ResultsAsync<T>(this DbDataReader reader, params (string Field, string Column)[] fieldMappingOverrides) where T : new()
             => ResultsAsync<T>(reader, fieldMappingOverrides as IEnumerable<(string Field, string Column)>);
 
-        /// <summary>
-        /// Iterates each record and attempts to map the fields to type T.
-        /// Data is temporarily stored (buffered in entirety) in a queue of dictionaries before applying the transform for each iteration.
-        /// </summary>
-        /// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
-        /// <param name="reader">The IDataReader to read results from.</param>
-        /// <param name="fieldMappingOverrides">An optional override map of field names to column names where the keys are the property names, and values are the column names.</param>
-        /// <returns>The enumerable to pull the transformed results from.</returns>
-        public static IEnumerable<T> Results<T>(this IDataReader reader, IEnumerable<(string Field, string Column)> fieldMappingOverrides)
+		/// <summary>
+		/// Asynchronously returns all records and iteratively attempts to map the fields to type T.
+		/// </summary>
+		/// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
+		/// <param name="reader">The IDataReader to read results from.</param>
+		/// <param name="token">A cancellation token.</param>
+		/// <param name="fieldMappingOverrides">An override map of field names to column names where the keys are the property names, and values are the column names.</param>
+		/// <returns>A task containing the list of results.</returns>
+		public static Task<IEnumerable<T>> ResultsAsync<T>(this DbDataReader reader, CancellationToken token, params (string Field, string Column)[] fieldMappingOverrides) where T : new()
+			=> ResultsAsync<T>(reader, fieldMappingOverrides as IEnumerable<(string Field, string Column)>, token);
+
+		/// <summary>
+		/// Iterates each record and attempts to map the fields to type T.
+		/// Data is temporarily stored (buffered in entirety) in a queue of dictionaries before applying the transform for each iteration.
+		/// </summary>
+		/// <typeparam name="T">The model type to map the values to (using reflection).</typeparam>
+		/// <param name="reader">The IDataReader to read results from.</param>
+		/// <param name="fieldMappingOverrides">An optional override map of field names to column names where the keys are the property names, and values are the column names.</param>
+		/// <returns>The enumerable to pull the transformed results from.</returns>
+		public static IEnumerable<T> Results<T>(this IDataReader reader, IEnumerable<(string Field, string Column)> fieldMappingOverrides)
             where T : new()
         {
             if (!reader.Read()) return Enumerable.Empty<T>();

Extensions.Results.cs

@@ -3,6 +3,7 @@
 using System.Data;
 using System.Data.Common;
 using System.Linq;
+using System.Threading;
 using System.Threading.Tasks;
 
 namespace Open.Database.Extensions
@@ -134,19 +135,21 @@ public static QueryResult<Queue<object[]>> Retrieve(this IDbCommand command, IEn
         public static QueryResult<Queue<object[]>> Retrieve(this IDbCommand command, string c, params string[] others)
             => ExecuteReader(command, reader => Retrieve(reader, new string[1] { c }.Concat(others)));
 
-        /// <summary>
-        /// Asynchronously enumerates all the remaining values of the current result set of a data reader.
-        /// DBNull values are left unchanged (retained).
-        /// </summary>
-        /// <param name="reader">The reader to enumerate.</param>
-        /// <returns>The QueryResult that contains a buffer block of the results and the column mappings.</returns>
-        public static async Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader)
+		/// <summary>
+		/// Asynchronously enumerates all the remaining values of the current result set of a data reader.
+		/// DBNull values are left unchanged (retained).
+		/// </summary>
+		/// <param name="reader">The reader to enumerate.</param>
+		/// <param name="token">Optional cancellation token.</param>
+		/// <returns>The QueryResult that contains a buffer block of the results and the column mappings.</returns>
+		public static async Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, CancellationToken? token = null)
         {
-            var fieldCount = reader.FieldCount;
+			var t = token ?? CancellationToken.None;
+			var fieldCount = reader.FieldCount;
             var names = reader.GetNames(); // pull before first read.
             var buffer = new Queue<object[]>();
 
-            while (await reader.ReadAsync())
+            while (await reader.ReadAsync(t))
             {
                 var row = new object[fieldCount];
                 reader.GetValues(row);
@@ -159,7 +162,7 @@ public static async Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbData
                 buffer);
         }
 
-        static async Task<QueryResult<Queue<object[]>>> RetrieveAsyncInternal(DbDataReader reader, int[] ordinals, string[] columnNames = null, bool readStarted = false)
+        static async Task<QueryResult<Queue<object[]>>> RetrieveAsyncInternal(DbDataReader reader, CancellationToken? token, int[] ordinals, string[] columnNames = null, bool readStarted = false)
         {
             var fieldCount = ordinals.Length;
             if (columnNames == null) columnNames = ordinals.Select(n => reader.GetName(n)).ToArray();
@@ -175,14 +178,15 @@ static async Task<QueryResult<Queue<object[]>>> RetrieveAsyncInternal(DbDataRead
                 return row;
             };
 
-            var buffer = new Queue<object[]>();
-            if (readStarted || await reader.ReadAsync())
+			var t = token ?? CancellationToken.None;
+			var buffer = new Queue<object[]>();
+            if (readStarted || await reader.ReadAsync(t))
             {
                 do
                 {
                     buffer.Enqueue(handler(reader));
                 }
-                while (await reader.ReadAsync());
+                while (await reader.ReadAsync(t));
             }
 
             return new QueryResult<Queue<object[]>>(
@@ -191,15 +195,16 @@ static async Task<QueryResult<Queue<object[]>>> RetrieveAsyncInternal(DbDataRead
                 buffer);
         }
 
-        /// <summary>
-        /// Asynchronously enumerates all the remaining values of the current result set of a data reader.
-        /// DBNull values are left unchanged (retained).
-        /// </summary>
-        /// <param name="reader">The reader to enumerate.</param>
-        /// <param name="ordinals">The limited set of ordinals to include.  If none are specified, the returned objects will be empty.</param>
-        /// <returns>The QueryResult that contains a buffer block of the results and the column mappings.</returns>
-        public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, IEnumerable<int> ordinals)
-            => RetrieveAsyncInternal(reader, ordinals as int[] ?? ordinals.ToArray());
+		/// <summary>
+		/// Asynchronously enumerates all the remaining values of the current result set of a data reader.
+		/// DBNull values are left unchanged (retained).
+		/// </summary>
+		/// <param name="reader">The reader to enumerate.</param>
+		/// <param name="ordinals">The limited set of ordinals to include.  If none are specified, the returned objects will be empty.</param>
+		/// <param name="token">Optional cancellation token.</param>
+		/// <returns>The QueryResult that contains a buffer block of the results and the column mappings.</returns>
+		public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, IEnumerable<int> ordinals, CancellationToken? token = null)
+            => RetrieveAsyncInternal(reader, token, ordinals as int[] ?? ordinals.ToArray());
 
         /// <summary>
         /// Asynchronously enumerates all the remaining values of the current result set of a data reader.
@@ -212,21 +217,35 @@ public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader
         public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, int n, params int[] others)
             => RetrieveAsync(reader, new int[1] { n }.Concat(others));
 
-        /// <summary>
-        /// Asynchronously enumerates all records within the current result set using an IDataReader and returns the desired results.
-        /// DBNull values are left unchanged (retained).
-        /// </summary>
-        /// <param name="reader">The IDataReader to read results from.</param>
-        /// <param name="columnNames">The column names to select.</param>
-        /// <param name="normalizeColumnOrder">Orders the results arrays by ordinal.</param>
-        /// <returns>The QueryResult that contains all the results and the column mappings.</returns>
-        public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, IEnumerable<string> columnNames, bool normalizeColumnOrder = false)
+		/// <summary>
+		/// Asynchronously enumerates all the remaining values of the current result set of a data reader.
+		/// DBNull values are left unchanged (retained).
+		/// </summary>
+		/// <param name="reader">The reader to enumerate.</param>
+		/// <param name="n">The first ordinal to include in the request to the reader for each record.</param>
+		/// <param name="token">A cancellation token.</param>
+		/// <param name="others">The remaining ordinals to request from the reader for each record.</param>
+		/// <returns>The QueryResult that contains a buffer block of the results and the column mappings.</returns>
+		public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, CancellationToken token, int n, params int[] others)
+			=> RetrieveAsync(reader, new int[1] { n }.Concat(others), token);
+
+		/// <summary>
+		/// Asynchronously enumerates all records within the current result set using an IDataReader and returns the desired results.
+		/// DBNull values are left unchanged (retained).
+		/// </summary>
+		/// <param name="reader">The IDataReader to read results from.</param>
+		/// <param name="columnNames">The column names to select.</param>
+		/// <param name="normalizeColumnOrder">Orders the results arrays by ordinal.</param>
+		/// <param name="token">Optional cancellation token.</param>
+		/// <returns>The QueryResult that contains all the results and the column mappings.</returns>
+		public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, IEnumerable<string> columnNames, bool normalizeColumnOrder = false, CancellationToken? token = null)
         {
             // Validate columns first.
             var columns = reader.GetOrdinalMapping(columnNames, normalizeColumnOrder);
 
-            return RetrieveAsyncInternal(reader,
-                columns.Select(c => c.Ordinal).ToArray(),
+            return RetrieveAsyncInternal(reader, token,
+
+				columns.Select(c => c.Ordinal).ToArray(),
                 columns.Select(c => c.Name).ToArray());
         }
 
@@ -241,5 +260,16 @@ public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader
         public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, string c, params string[] others)
             => RetrieveAsync(reader, new string[1] { c }.Concat(others));
 
-    }
+		/// <summary>
+		/// Asynchronously enumerates all records within the current result set using an IDataReader and returns the desired results.
+		/// DBNull values are left unchanged (retained).
+		/// </summary>
+		/// <param name="reader">The IDataReader to read results from.</param>
+		/// <param name="token">Optional cancellation token.</param>
+		/// <param name="c">The first column name to include in the request to the reader for each record.</param>
+		/// <param name="others">The remaining column names to request from the reader for each record.</param>
+		/// <returns>The QueryResult that contains all the results and the column mappings.</returns>
+		public static Task<QueryResult<Queue<object[]>>> RetrieveAsync(this DbDataReader reader, CancellationToken token, string c, params string[] others)
+			=> RetrieveAsync(reader, new string[1] { c }.Concat(others), false, token);
+	}
 }