feat: UseDeferredEnumeration option

Author: yv989c

src/QueryableValues.SqlServer/QueryableValuesSqlServerOptions.cs

@@ -1,11 +1,15 @@
-namespace BlazarTech.QueryableValues
+using System;
+using System.Collections.Generic;
+
+namespace BlazarTech.QueryableValues
 {
     /// <summary>
     /// QueryableValues options for SQL Server.
     /// </summary>
     public sealed class QueryableValuesSqlServerOptions
     {
         internal bool WithUseSelectTopOptimization { get; private set; } = true;
+        internal bool WithUseDeferredEnumeration { get; private set; } = true;
 
         /// <summary>
         /// When possible, uses a <c>TOP(n)</c> clause in the underlying <c>SELECT</c> statement to assist SQL Server memory grant estimation. The default is <see langword="true"/>.
@@ -21,5 +25,29 @@ public QueryableValuesSqlServerOptions UseSelectTopOptimization(bool useSelectTo
             WithUseSelectTopOptimization = useSelectTopOptimization;
             return this;
         }
+
+#if !EFCORE3
+        /// <summary>
+        /// If <see langword="true"/>, the <see cref="IEnumerable{T}"/> provided to any of the <c>AsQueryableValues</c> methods will be enumerated when the query is materialized; otherwise, it will be immediately enumerated once. The default is <see langword="true"/>.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Leaving this feature enabled has the following advantages:<br/>
+        /// - If your sequence of values is behind an <see cref="IEnumerable{T}"/>, it will be enumerated only when needed.<br/>
+        /// - The sequence is enumerated every time the query is materialized, allowing the query to be aware of any changes done to the underlying sequence.
+        /// </para>
+        /// <para>
+        /// You may want to disable this feature if you rely on the <see cref="Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions.ToQueryString(System.Linq.IQueryable)"/> method across your application.
+        /// As of EF 7.0, the implementation of that API is making incompatible assumptions about the underlying ADO.NET query parameters, resulting in an <see cref="InvalidCastException"/> when this option is enabled.
+        /// </para>
+        /// </remarks>
+        /// <param name="useDeferredEnumeration"></param>
+        /// <returns>The same <see cref="QueryableValuesSqlServerOptions"/> instance so subsequent configurations can be chained.</returns>
+        public QueryableValuesSqlServerOptions UseDeferredEnumeration(bool useDeferredEnumeration = true)
+        {
+            WithUseDeferredEnumeration = useDeferredEnumeration;
+            return this;
+        }
+#endif
     }
 }

src/QueryableValues.SqlServer/SqlServer/XmlQueryableFactory.cs

@@ -82,17 +82,15 @@ private SqlParameter[] GetSqlParameters<T>(DeferredValues<T> deferredValues)
             var xmlParameter = new SqlParameter(null, SqlDbType.Xml)
             {
                 // DeferredValues allows us to defer the enumeration of values until the query is materialized.
-                // Uses deferredValues.ToString() at evaluation time.
-                Value = deferredValues
+                Value = _options.WithUseDeferredEnumeration ? deferredValues : deferredValues.ToString(null)
             };
 
             if (UseSelectTopOptimization(deferredValues))
             {
                 // bigint to avoid implicit casting by the TOP operation (observed in the execution plan).
                 var countParameter = new SqlParameter(null, SqlDbType.BigInt)
                 {
-                    // Uses deferredValues.ToInt64() at evaluation time.
-                    Value = deferredValues
+                    Value = _options.WithUseDeferredEnumeration ? deferredValues : deferredValues.ToInt64(null)
                 };
 
                 sqlParameters = new[] { xmlParameter, countParameter };