diff --git a/Benchmarks/Open.Database.Extensions.Benchmarks/SyncBenchmarks.cs b/Benchmarks/Open.Database.Extensions.Benchmarks/SyncBenchmarks.cs index 1c229584..8720027c 100644 --- a/Benchmarks/Open.Database.Extensions.Benchmarks/SyncBenchmarks.cs +++ b/Benchmarks/Open.Database.Extensions.Benchmarks/SyncBenchmarks.cs @@ -92,7 +92,9 @@ public long Stream_ODE() => _conn.Command(Sql).Map().Read(static items => public List QueryResult_Dapper() => _conn.Query(Sql).AsList(); [BenchmarkCategory("QueryResult"), Benchmark] +#pragma warning disable CS0618 // measures the deprecated Retrieve + DequeueAs route until 12 public List QueryResult_ODE() => _conn.Command(Sql).Retrieve().DequeueAs().ToList(); +#pragma warning restore CS0618 [BenchmarkCategory("Dictionary"), Benchmark(Baseline = true)] public Dictionary Dictionary_Dapper() => _conn.Query(Sql).ToDictionary(p => p.Id); diff --git a/Source/Core/Core/QueryResult.cs b/Source/Core/Core/QueryResult.cs index cd8304f4..31172551 100644 --- a/Source/Core/Core/QueryResult.cs +++ b/Source/Core/Core/QueryResult.cs @@ -69,11 +69,14 @@ static ImmutableArray Immute(IEnumerable source) } /// +/// Obsolete: nothing in the library returns this type; there is no replacement (rows come back as a from ). /// A container for data reader results that also provides the column names and /// other helpful data methods. /// +/// Obsolete in 11.0, removed in 12. See Deprecated in 11.0. /// The type of the items in the resultant enumerable. /// The type of the result property. +[Obsolete(QueryResultExtensions._queryResultCollectionObsolete)] public class QueryResultCollection : QueryResult, IEnumerable where TResult : IEnumerable { @@ -108,10 +111,13 @@ IEnumerator IEnumerable.GetEnumerator() } /// +/// Obsolete: nothing in the library returns this type; there is no replacement (rows come back as a from ). /// A container for data reader results that also provides the column names and /// other helpful data methods. /// +/// Obsolete in 11.0, removed in 12. See Deprecated in 11.0. /// The type of the items in the resultant enumerable. +[Obsolete(QueryResultExtensions._queryResultCollectionObsolete)] public class QueryResultCollection : QueryResultCollection> { /// Constructs a . @@ -176,6 +182,14 @@ public QueryResultQueue( /// public static class QueryResultExtensions { + internal const string _queryResultCollectionObsolete = "Nothing in the library returns this type, and there is no replacement. Get rows as a List from .Map().ToList(), or keep your own class. Removed in 12."; + const string AsMappedDictionariesTail = " DequeueAsMappedDictionaries drains the queue as you enumerate it, so it can be read once; this method could be read again. Removed in 12."; + const string AsMappedDictionariesObsolete = "Nothing in the library returns the QueryResult> this takes. To read rows as dictionaries use .Retrieve().DequeueAsMappedDictionaries(), or .Map(record => ...) with a selector that builds the dictionary." + AsMappedDictionariesTail; + const string AsMappedDictionariesAsyncObsolete = "Nothing in the library returns the QueryResult> this takes. To read rows as dictionaries use (await cmd.RetrieveAsync()).DequeueAsMappedDictionaries(), or .Map(record => ...) with a selector that builds the dictionary." + AsMappedDictionariesTail; + + const string DequeueAsTail = "Map reads in one pass instead of buffering raw rows first, reports a missing required column at the first row (so not for an empty result), and also reads later result sets: add .SingleResult() to read only the first, as Retrieve did. DequeueAs returned a one-pass enumerable; ToList() returns a List. Removed in 12."; + const string DequeueAsObsolete = "Use cmd.Map().ToList() instead of cmd.Retrieve().DequeueAs(), or cmd.Map(map).ToList() when you passed a RowMap (DequeueAs accepted a null map; Map(map) throws on null). On an IDbCommand use command.Results() (it takes no CommandBehavior); on an IDataReader use reader.ResultsBuffered() (reader.Results() is lazy). " + DequeueAsTail; + const string DequeueAsAsyncObsolete = "Use await cmd.Map().ToListAsync() instead of (await cmd.RetrieveAsync()).DequeueAs(), or cmd.Map(map).ToListAsync() when you passed a RowMap (DequeueAs accepted a null map; Map(map) throws on null). On a DbCommand use await command.ResultsAsync(). " + DequeueAsTail; /// /// Returns an enumerable that dequeues the results and returns a column /// mapped dictionary for each entry. values are converted to null. @@ -217,9 +231,11 @@ public static class QueryResultExtensions => (await source.ConfigureAwait(false)).DequeueAsMappedDictionaries(); /// + /// Obsolete: use then (async: ). /// Returns an enumerable that dequeues the results and attempts to map the /// fields to type T. /// + /// Obsolete in 11.0, removed in 12. Replace the whole chain cmd.Retrieve().DequeueAs<T>(): on an IExecuteReader use cmd.Map<T>().ToList() (cmd.Map(map).ToList() with a ); on an IDbCommand use Results<T>(); on an IDataReader use ResultsBuffered<T>(); on a DbCommand async use ResultsAsync<T>(). See Deprecated in 11.0 for the differences and a before/after example. /// Declare the once and pass it: a map built in the call (a new RowMap<T>(...) or a collection expression in the argument) is rebuilt, and its row reader compiled, on every call. /// DBNull values are converted to null. /// The query result. Typically produced by a @@ -228,6 +244,7 @@ public static class QueryResultExtensions /// An enumerable that dequeues the results and returns an entity /// of type T. /// + [Obsolete(DequeueAsObsolete)] public static IEnumerable DequeueAs( this QueryResult> source, RowMap? map = null) @@ -242,6 +259,7 @@ public static IEnumerable DequeueAs( /// /// Declare the once and pass it: a map built in the call (a new RowMap<T>(...) or a collection expression in the argument) is rebuilt, and its row reader compiled, on every call. /// + [Obsolete(DequeueAsAsyncObsolete)] public static async ValueTask> DequeueAs( this Task>> source, RowMap? map = null) @@ -256,6 +274,7 @@ public static async ValueTask> DequeueAs( /// /// Declare the once and pass it: a map built in the call (a new RowMap<T>(...) or a collection expression in the argument) is rebuilt, and its row reader compiled, on every call. /// + [Obsolete(DequeueAsAsyncObsolete)] public static async ValueTask> DequeueAs( this ValueTask>> source, RowMap? map = null) @@ -265,25 +284,30 @@ public static async ValueTask> DequeueAs( } /// + [Obsolete(DequeueAsAsyncObsolete)] [OverloadResolutionPriority(1)] public static ValueTask> DequeueAs( this Task>> source) => DequeueAs(source, null); /// + [Obsolete(DequeueAsAsyncObsolete)] [OverloadResolutionPriority(1)] public static ValueTask> DequeueAs( this ValueTask>> source) => DequeueAs(source, null); /// + /// Obsolete: nothing produces the source this takes. Use on a Retrieve() result, or with your own selector. /// Returns an enumerable that dequeues the results and returns a column /// mapped dictionary for each entry. values are converted to null. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0. /// The query result. Typically produced by a /// .Retrieve method. /// An enumerable that dequeues the results and returns a column /// mapped dictionary for each entry + [Obsolete(AsMappedDictionariesObsolete)] public static IEnumerable> AsMappedDictionaries(this QueryResult> source) { return source is null @@ -307,11 +331,13 @@ public static ValueTask> DequeueAs( /// + [Obsolete(AsMappedDictionariesAsyncObsolete)] public static async ValueTask>> AsMappedDictionaries(this ValueTask>> source) => AsMappedDictionaries(await source.ConfigureAwait(false)); /// + [Obsolete(AsMappedDictionariesAsyncObsolete)] public static async ValueTask>> AsMappedDictionaries(this Task>> source) => AsMappedDictionaries(await (source ?? throw new ArgumentNullException(nameof(source))).ConfigureAwait(false)); } diff --git a/Source/Core/ExpressiveDbCommandBase.cs b/Source/Core/ExpressiveDbCommandBase.cs index 0967ca91..1ebf04ae 100644 --- a/Source/Core/ExpressiveDbCommandBase.cs +++ b/Source/Core/ExpressiveDbCommandBase.cs @@ -17,6 +17,11 @@ public abstract partial class ExpressiveDbCommandBase { + const string LaterSets = "Map also reads the later result sets, so a failure in one is thrown; add .SingleResult() to read only the first, as this method does."; + const string ResultsAsyncObsolete = "Use .Map().ToListAsync() instead (.Map(map).ToListAsync() when you pass a RowMap; Map does not accept a null map; pass a CancellationToken to ToListAsync if you want one, it is optional and combines with the command's token). " + LaterSets + " Map returns a List. Removed in 12."; + const string TakeAsyncObsolete = "Use .Map(selector).Take(count).ToListAsync(cancellationToken) instead. " + LaterSets + " It returns a List, and Take(0) now runs the command; this method did not. Map has no CommandBehavior argument: if you passed one, use var list = new List(); await cmd.IterateReaderWhileAsync(r => { list.Add(selector(r)); return list.Count < count; }, behavior). Removed in 12."; + const string ToListAsyncObsolete = "Use .Map(selector).ToListAsync(cancellationToken) instead. " + LaterSets + " Map has no CommandBehavior argument: if you passed one, use var list = new List(); await cmd.IterateReaderAsync(r => list.Add(selector(r)), behavior). Removed in 12."; + /// Constructs a an expressive command. /// The pool to acquire connections from. /// The command type. @@ -174,13 +179,20 @@ public async ValueTask ExecuteScalarAsync(Func> tran } /// + /// Obsolete: use , then , then . /// Asynchronously iterates a IDataReader and returns the each result until the count is met. /// + /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0. + /// Map has no argument: if you passed one, run the reader yourself with + /// IterateReaderWhileAsync(record => { list.Add(selector(record)); return list.Count < count; }, behavior). + /// /// The return type of the transform function. /// The transform function to process each IDataRecord. /// The maximum number of records before complete. /// The behavior to use with the data reader. /// The value from the transform. + [Obsolete(TakeAsyncObsolete)] public ValueTask> TakeAsync(Func transform, int count, CommandBehavior behavior = CommandBehavior.Default) { if (transform is null) throw new ArgumentNullException(nameof(transform)); @@ -238,11 +250,18 @@ public ValueTask> RetrieveAsync(string c, params IEnu => RetrieveAsync(others.Prepend(c)); /// + /// Obsolete: use then . /// Asynchronously returns all records via a transform function. /// + /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0. + /// Map has no argument: if you passed one, run the reader yourself with + /// IterateReaderAsync(record => list.Add(selector(record)), behavior). + /// /// The desired column names. /// The behavior to use with the data reader. /// A task containing the list of results. + [Obsolete(ToListAsyncObsolete)] public async ValueTask> ToListAsync(Func transform, CommandBehavior behavior = CommandBehavior.Default) { var results = new List(); @@ -251,13 +270,16 @@ public async ValueTask> ToListAsync(Func transform, C } /// + /// Obsolete: use then . /// Asynchronously returns all records and iteratively attempts to map the fields to type T. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// Declare the once and pass it: a map built in the call (a new RowMap<T>(...) or a collection expression in the argument) is rebuilt, and its row reader compiled, on every call. /// The model type to map the values to (using reflection). /// An optional prebuilt ; reads by column name. /// A task containing the list of results. /// + [Obsolete(ResultsAsyncObsolete)] public ValueTask> ResultsAsync(RowMap? map = null) { // An unmappable T fails here, before the command runs. @@ -267,6 +289,7 @@ public ValueTask> ResultsAsync(RowMap? map = null) } /// + [Obsolete(ResultsAsyncObsolete)] public ValueTask> ResultsAsync() { // An unmappable T fails here, before the command runs. diff --git a/Source/Core/Extensions/IExecuteReader.cs b/Source/Core/Extensions/IExecuteReader.cs index 325c3243..6b37032c 100644 --- a/Source/Core/Extensions/IExecuteReader.cs +++ b/Source/Core/Extensions/IExecuteReader.cs @@ -5,6 +5,15 @@ /// public static class IExecuteReaderExtensions { + const string LaterSets = "Map also reads the later result sets, so a failure in one is thrown; add .SingleResult() to read only the first, as this method does."; + const string SkipDifference = "Map does not run the selector on skipped rows, so a selector that throws on one no longer fails the call."; + const string ResultsObsolete = "Use .Map().ToList() instead (.Map(map).ToList() when you pass a RowMap; Map does not accept a null map). " + LaterSets + " Map returns a List. Removed in 12."; + const string FirstOrDefaultObsolete = "Use .Map(selector).FirstOrDefault() instead. " + LaterSets + " Removed in 12."; + const string SingleOrDefaultObsolete = "Use .Map(selector).SingleOrDefault() instead. " + LaterSets + " Removed in 12."; + const string TakeObsolete = "Use .Map(selector).Take(count).ToList() instead. " + LaterSets + " Take(0) now runs the command; this method did not. Removed in 12."; + const string SkipObsolete = "Use .Map(selector).Skip(count).ToList() instead. " + LaterSets + " " + SkipDifference + " Removed in 12."; + const string SkipThenTakeObsolete = "Use .Map(selector).Skip(skip).Take(take).ToList() instead. " + LaterSets + " " + SkipDifference + " Take(0) now runs the command; this method did not. Removed in 12."; + /// /// Iterates a reader on a command with a handler function. /// @@ -133,12 +142,15 @@ public static T First(this IExecuteReader command, Func trans } /// + /// Obsolete: use then . /// Iterates an IDataReader and returns the first result through a transform function. Returns default(T) if none. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// The return type of the transform function. /// The IExecuteReader to iterate. /// The transform function to process each IDataRecord. /// The value from the transform. + [Obsolete(FirstOrDefaultObsolete)] public static T? FirstOrDefault(this IExecuteReader command, Func transform) { if (command is null) throw new ArgumentNullException(nameof(command)); @@ -170,14 +182,17 @@ public static T Single(this IExecuteReader command, Func tran } /// + /// Obsolete: use then . /// Iterates an IDataReader and returns the first result through a transform function. /// Returns default(T) if none. /// Throws if more than one entry. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// The return type of the transform function. /// The IExecuteReader to iterate. /// The transform function to process each IDataRecord. /// The value from the transform. + [Obsolete(SingleOrDefaultObsolete)] public static T? SingleOrDefault(this IExecuteReader command, Func transform) { if (command is null) throw new ArgumentNullException(nameof(command)); @@ -190,13 +205,16 @@ public static T Single(this IExecuteReader command, Func tran } /// + /// Obsolete: use , then , then . /// Iterates an IDataReader and returns the first number of results defined by the count. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// The return type of the transform function. /// The IExecuteReader to iterate. /// The maximum number of records to return. /// The transform function to process each IDataRecord. /// The results from the transform limited by the take count. + [Obsolete(TakeObsolete)] public static List Take(this IExecuteReader command, int count, Func transform) { if (command is null) throw new ArgumentNullException(nameof(command)); @@ -210,13 +228,16 @@ public static List Take(this IExecuteReader command, int count, Func + /// Obsolete: use , then , then . /// Iterates an IDataReader and skips the first number of results defined by the count. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// The return type of the transform function. /// The IExecuteReader to iterate. /// The number of records to skip. /// The transform function to process each IDataRecord. /// The results from the transform after the skip count. + [Obsolete(SkipObsolete)] public static List Skip(this IExecuteReader command, int count, Func transform) { if (command is null) throw new ArgumentNullException(nameof(command)); @@ -232,14 +253,17 @@ public static List Skip(this IExecuteReader command, int count, Func + /// Obsolete: use , then , and . /// Iterates an IDataReader and skips by the skip parameter returns the maximum remaining defined by the take parameter. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// The return type of the transform function. /// The IExecuteReader to iterate. /// The number of entries to skip before starting to take results. /// The maximum number of records to return. /// The transform function to process each IDataRecord. /// The results from the skip, transform and take operation. + [Obsolete(SkipThenTakeObsolete)] public static List SkipThenTake(this IExecuteReader command, int skip, int take, Func transform) { if (command is null) throw new ArgumentNullException(nameof(command)); @@ -402,15 +426,18 @@ public static QueryResultQueue Retrieve(this IExecuteReader command, s } /// + /// Obsolete: use then . /// Iterates each record and attempts to map the fields to type T. /// Data is temporarily stored (buffered in entirety) in a queue before applying the transform for each iteration. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// Declare the once and pass it: a map built in the call (a new RowMap<T>(...) or a collection expression in the argument) is rebuilt, and its row reader compiled, on every call. /// The IExecuteReader to iterate. /// The model type to map the values to (using reflection). /// An optional prebuilt ; reads by column name. /// The enumerable to pull the transformed results from. /// + [Obsolete(ResultsObsolete)] public static IEnumerable Results(this IExecuteReader command, RowMap? map = null) { if (command is null) throw new ArgumentNullException(nameof(command)); diff --git a/Source/Core/Extensions/Results.cs b/Source/Core/Extensions/Results.cs index 7c86d9c2..4f4d9047 100644 --- a/Source/Core/Extensions/Results.cs +++ b/Source/Core/Extensions/Results.cs @@ -193,18 +193,21 @@ public static ValueTask> ResultsAsync( CancellationToken cancellationToken) => ResultsAsync(command, null, true, cancellationToken); - // NOTE: The Results methods should be faster than the ResultsFromDataTable variations but are provided for validation of this assumption. + const string ResultsFromDataTableObsolete = "Use .ToDataTable() then .To(map, true) instead, for example: using var table = command.ToDataTable(); var rows = table.To(map, true).ToList(). This method threw for a type that cannot be mapped before it ran; To still throws, but after the data is loaded: read RowMap.Default (or build your RowMap) first to keep the early failure. Removed in 12."; /// + /// Obsolete: use then . /// Loads all data into a DataTable before Iterates each record and attempts to map the fields to type T. /// Data is temporarily stored (buffered in entirety) in a queue before applying the transform for each iteration. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// Declare the once and pass it: a map built in the call (a new RowMap<T>(...) or a collection expression in the argument) is rebuilt, and its row reader compiled, on every call. /// The model type to map the values to (using reflection). /// The IDataReader to read results from. /// An optional prebuilt ; reads by column name. /// The enumerable to pull the transformed results from. /// + [Obsolete(ResultsFromDataTableObsolete)] public static IEnumerable ResultsFromDataTable(this IDataReader reader, RowMap? map = null) { // An unmappable T fails here, before the command runs. @@ -215,15 +218,18 @@ public static IEnumerable ResultsFromDataTable(this IDataReader reader, Ro } /// + /// Obsolete: use then . /// Loads all data into a DataTable before Iterates each record and attempts to map the fields to type T. /// Data is temporarily stored (buffered in entirety) in a queue before applying the transform for each iteration. /// + /// Obsolete in 11.0, removed in 12. See Deprecated in 11.0 for the difference and a before/after example. /// Declare the once and pass it: a map built in the call (a new RowMap<T>(...) or a collection expression in the argument) is rebuilt, and its row reader compiled, on every call. /// The model type to map the values to (using reflection). /// The command to generate a reader from. /// An optional prebuilt ; reads by column name. /// The enumerable to pull the transformed results from. /// + [Obsolete(ResultsFromDataTableObsolete)] public static IEnumerable ResultsFromDataTable(this IDbCommand command, RowMap? map = null) { // An unmappable T fails here, before the command runs. diff --git a/Tests/Open.Database.Extensions.Core.Tests/CaseInsensitiveMappingTests.cs b/Tests/Open.Database.Extensions.Core.Tests/CaseInsensitiveMappingTests.cs index e29b7494..2578d4ab 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/CaseInsensitiveMappingTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/CaseInsensitiveMappingTests.cs @@ -20,7 +20,9 @@ public static void Transformer_MatchesColumn_RegardlessOfCase(string columnName) queue.Enqueue(["Ada"]); var result = new QueryResult>([0], [columnName], queue); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. List people = [.. result.DequeueAs()]; + #pragma warning restore CS0618 Assert.Equal("Ada", Assert.Single(people).FirstName); } diff --git a/Tests/Open.Database.Extensions.Core.Tests/ConstructorBindingTests.cs b/Tests/Open.Database.Extensions.Core.Tests/ConstructorBindingTests.cs index ce07cede..dd7f65b7 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/ConstructorBindingTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/ConstructorBindingTests.cs @@ -26,7 +26,9 @@ internal static List ReadRows(Route route, ImmutableArray colum if (route == Route.Buffered) { var result = new QueryResult>([.. Enumerable.Range(0, columns.Length)], [.. columns.Select(c => c.Name)], new Queue(rows!)); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. return result.DequeueAs(map).ToList(); + #pragma warning restore CS0618 } ImmutableArray shown = route == Route.Typed ? columns : [.. columns.Select(c => new ColumnDef(c.Name, typeof(object)))]; @@ -126,7 +128,9 @@ public static async Task Results_ResultsBuffered_AndTheAsyncTwins_BuildThePositi Assert.Equal(expected, FakeReader.Create(["Id", "Title"], rows).ResultsBuffered()); Assert.Equal(expected, TypedReader.Create(PostColumns, rows).Results()); Assert.Equal(expected, TypedReader.Create(PostColumns, rows).ResultsBuffered()); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Equal(expected, new FakeExecuteReader(() => TypedReader.Create(PostColumns, rows)).Results()); + #pragma warning restore CS0618 Assert.Equal(expected, await TypedReader.Create(PostColumns, rows).ResultsBufferedAsync(ct)); var streamed = new List(); diff --git a/Tests/Open.Database.Extensions.Core.Tests/DeprecationTests.cs b/Tests/Open.Database.Extensions.Core.Tests/DeprecationTests.cs new file mode 100644 index 00000000..3b663bb3 --- /dev/null +++ b/Tests/Open.Database.Extensions.Core.Tests/DeprecationTests.cs @@ -0,0 +1,252 @@ +using Open.Database.Extensions.Core; +using System.Reflection; + +#nullable enable + +namespace Open.Database.Extensions.Tests; + +// The members that are obsolete in 11.0 (removed in 12) each say what to type instead. +// The first test is the guard that a member never ships obsolete without naming its alternative. +// The others show that the alternative gives the same rows as the old call for the common case, and pin the documented differences. +[ExcludeFromCodeCoverage] +public static class DeprecationTests +{ + sealed class Thing + { + public int Id { get; set; } + public string? Name { get; set; } + public string? Note { get; set; } + } + + static FakeExecuteReader Command(int count) + => new(() => ReaderFixtures.Reader(ReaderFixtures.Rows(count))); + + static string Show(IEnumerable things) => string.Join(",", things.Select(t => $"{t.Id}:{t.Name}")); + + static bool IsFunc(Type t) => t.IsGenericType && t.GetGenericTypeDefinition() == typeof(Func<,>); + + static IEnumerable Of(Type type, string name, Func? where = null) + => type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.Instance | BindingFlags.DeclaredOnly) + .Where(m => m.Name == name && (where is null || where(m))); + + static IEnumerable OnReader(string name, bool selector) + => Of(typeof(IExecuteReaderExtensions), name, m => + { + ParameterInfo[] p = m.GetParameters(); + return p[0].ParameterType == typeof(IExecuteReader) + && p.Any(x => IsFunc(x.ParameterType)) == selector; + }); + + // (group, members, text every message must contain) + static IEnumerable<(string Group, MemberInfo[] Members, string[] Contains)> Table() + { + Type command = typeof(ExpressiveDbCommandBase<,,,,>); + + yield return ("1a Results(IExecuteReader)", [.. OnReader("Results", false)], [".Map().ToList()", ".Map(map).ToList()", ".SingleResult()"]); + yield return ("1b/1c ResultsAsync", [.. Of(command, "ResultsAsync")], [".Map().ToListAsync()", ".Map(map).ToListAsync()", ".SingleResult()"]); + yield return ("2 ResultsFromDataTable", [.. Of(typeof(CoreExtensions), "ResultsFromDataTable")], [".ToDataTable()", ".To(map, true)", "RowMap.Default"]); + yield return ("3a FirstOrDefault(selector)", [.. OnReader("FirstOrDefault", true)], [".Map(selector).FirstOrDefault()"]); + yield return ("3b SingleOrDefault(selector)", [.. OnReader("SingleOrDefault", true)], [".Map(selector).SingleOrDefault()"]); + yield return ("3c Take(selector)", [.. OnReader("Take", true)], [".Map(selector).Take(count).ToList()", "Take(0) now runs the command"]); + yield return ("3d Skip(selector)", [.. OnReader("Skip", true)], [".Map(selector).Skip(count).ToList()", "does not run the selector on skipped rows"]); + yield return ("3e SkipThenTake(selector)", [.. OnReader("SkipThenTake", true)], [".Map(selector).Skip(skip).Take(take).ToList()", "Take(0) now runs the command"]); + yield return ("4a TakeAsync", [.. Of(command, "TakeAsync")], [".Map(selector).Take(count).ToListAsync(cancellationToken)", "IterateReaderWhileAsync"]); + yield return ("4b ToListAsync(selector)", [.. Of(command, "ToListAsync", m => m.GetParameters().Any(p => p.ParameterType == typeof(CommandBehavior)))], [".Map(selector).ToListAsync(cancellationToken)", "IterateReaderAsync"]); +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + yield return ("5 QueryResultCollection", [typeof(QueryResultCollection<,>), typeof(QueryResultCollection<>)], ["no replacement", ".Map().ToList()"]); +#pragma warning restore CS0618 + yield return ("6a AsMappedDictionaries", [.. Of(typeof(QueryResultExtensions), "AsMappedDictionaries", m => m.GetParameters()[0].ParameterType.GetGenericTypeDefinition() == typeof(QueryResult<>))], [".Retrieve().DequeueAsMappedDictionaries()"]); + yield return ("6b/6c AsMappedDictionaries (async)", [.. Of(typeof(QueryResultExtensions), "AsMappedDictionaries", m => m.GetParameters()[0].ParameterType.GetGenericTypeDefinition() != typeof(QueryResult<>))], ["(await cmd.RetrieveAsync()).DequeueAsMappedDictionaries()"]); + yield return ("7a DequeueAs", [.. Of(typeof(QueryResultExtensions), "DequeueAs", m => m.GetParameters()[0].ParameterType.GetGenericTypeDefinition() == typeof(QueryResult<>))], ["cmd.Map().ToList()", "command.Results()", "reader.ResultsBuffered()"]); + yield return ("7b-7e DequeueAs (async)", [.. Of(typeof(QueryResultExtensions), "DequeueAs", m => m.GetParameters()[0].ParameterType.GetGenericTypeDefinition() != typeof(QueryResult<>))], ["await cmd.Map().ToListAsync()", "(await cmd.RetrieveAsync()).DequeueAs()", "await command.ResultsAsync()"]); + } + + [Fact] + public static void EveryObsoleteMember_IsAWarning_NamesItsReplacement_AndSaysWhenItGoes() + { + int members = 0; + foreach ((string group, MemberInfo[] list, string[] contains) in Table()) + { + Assert.NotEmpty(list); + foreach (MemberInfo member in list) + { + members++; + ObsoleteAttribute obsolete = member.GetCustomAttribute() + ?? throw new Xunit.Sdk.XunitException($"{group}: {member} is not [Obsolete]."); + Assert.False(obsolete.IsError, $"{group}: {member} must be a warning, not an error."); + string message = obsolete.Message ?? string.Empty; + Assert.EndsWith("Removed in 12.", message); + foreach (string text in contains) + Assert.True(message.Contains(text, StringComparison.Ordinal), $"{group}: {member} does not say \"{text}\"."); + } + } + + Assert.Equal(22, members); // 3 + 2 + 5 + 2 + 2 + 3 + 5 + } + + // ---- group 1 ---- + + [Fact] + public static void Results_AndMapToList_GiveTheSameRows() + { + FakeExecuteReader command = Command(3); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + string old = Show(command.Results()); +#pragma warning restore CS0618 + string replacement = Show(command.Map().ToList()); + + Assert.Equal("1:n1,2:n2,3:n3", old); + Assert.Equal(old, replacement); + } + + [Fact] + public static void ANullMap_IsAcceptedByResults_ButNotByMap() + { + FakeExecuteReader command = Command(1); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + Assert.Single(command.Results((RowMap?)null)); +#pragma warning restore CS0618 + Assert.Throws(() => command.Map((RowMap)null!)); + } + + // ---- group 2 ---- + + [Fact] + public static void ResultsFromDataTable_AndToDataTableThenTo_GiveTheSameRows() + { + using var source = new DataTable(); + source.Columns.Add("Id", typeof(int)); + source.Columns.Add("Name", typeof(string)); + source.Rows.Add(1, "n1"); + source.Rows.Add(2, "n2"); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + string old = Show(source.CreateDataReader().ResultsFromDataTable()); +#pragma warning restore CS0618 + using var table = source.CreateDataReader().ToDataTable(); + string replacement = Show(table.To(null, true).ToList()); + + Assert.Equal("1:n1,2:n2", old); + Assert.Equal(old, replacement); + } + + // ---- group 3 ---- + + [Fact] + public static void TheSelectorForms_AndTheirMapForms_GiveTheSameRows() + { + static int Id(IDataRecord record) => record.GetInt32(0); + FakeExecuteReader command = Command(5); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + Assert.Equal(command.Map(Id).FirstOrDefault(), command.FirstOrDefault(Id)); + Assert.Equal(command.Map(Id).Take(2).ToList(), command.Take(2, Id)); + Assert.Equal(command.Map(Id).Skip(3).ToList(), command.Skip(3, Id)); + Assert.Equal(command.Map(Id).Skip(1).Take(3).ToList(), command.SkipThenTake(1, 3, Id)); + Assert.Equal(Command(1).Map(Id).SingleOrDefault(), Command(1).SingleOrDefault(Id)); +#pragma warning restore CS0618 + } + + [Fact] + public static void MapDoesNotRunTheSelectorOnASkippedRow_ButSkipDid() + { + int calls = 0; + int Counting(IDataRecord record) + { + calls++; + return record.GetInt32(0); + } + + FakeExecuteReader command = Command(3); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + command.Skip(1, Counting); +#pragma warning restore CS0618 + int oldCalls = calls; + calls = 0; + command.Map(Counting).Skip(1).ToList(); + + Assert.Equal((3, 2), (oldCalls, calls)); + + // So a selector that throws on a skipped row failed the old call and no longer fails the new one. + var seen = new List(); + int ThrowsOnId1(IDataRecord record) + { + int id = record.GetInt32(0); + seen.Add(id); + return id == 1 ? throw new InvalidOperationException() : id; + } + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + Exception? thrown = Record.Exception(() => command.Skip(1, ThrowsOnId1)); +#pragma warning restore CS0618 + Assert.IsType(thrown); + Assert.Equal([1], seen); + Assert.Equal([2, 3], command.Map(ThrowsOnId1).Skip(1).ToList()); + } + + [Fact] + public static void ATakeOfZero_RunsTheCommandThroughMap_ButDidNotThroughTake() + { + static int Id(IDataRecord record) => record.GetInt32(0); + var old = Command(3); + var replacement = Command(3); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + Assert.Empty(old.Take(0, Id)); +#pragma warning restore CS0618 + Assert.Empty(replacement.Map(Id).Take(0).ToList()); + + Assert.Equal(0, old.ExecuteCount); + Assert.Equal(1, replacement.ExecuteCount); + } + + // ---- group 6 ---- + + [Fact] + public static void AsMappedDictionaries_AndDequeueAsMappedDictionaries_GiveTheSameDictionaries() + { + static object?[][] Raw() => [[1, "a"], [2, DBNull.Value]]; + string[] names = ["Id", "Name"]; + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + var old = new QueryResult>([0, 1], names, Raw()).AsMappedDictionaries().ToList(); +#pragma warning restore CS0618 + var replacement = new QueryResult>([0, 1], names, new Queue(Raw()!)).DequeueAsMappedDictionaries().ToList(); + + Assert.Equal(2, old.Count); + Assert.Equal(old.Count, replacement.Count); + for (int i = 0; i < old.Count; i++) + Assert.Equal(old[i].OrderBy(p => p.Key), replacement[i].OrderBy(p => p.Key)); + Assert.Null(replacement[1]["Name"]); + } + + // ---- group 7 ---- + + [Fact] + public static void RetrieveThenDequeueAs_AndMapToList_GiveTheSameRows() + { + FakeExecuteReader command = Command(3); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + string old = Show(command.Retrieve().DequeueAs()); +#pragma warning restore CS0618 + string replacement = Show(command.Map().ToList()); + + Assert.Equal("1:n1,2:n2,3:n3", old); + Assert.Equal(old, replacement); + } + + [Fact] + public static void ANullMap_IsAcceptedByDequeueAs_ButNotByMap() + { + FakeExecuteReader command = Command(1); + +#pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. + Assert.Single(command.Retrieve().DequeueAs(null)); +#pragma warning restore CS0618 + Assert.Throws(() => command.Map((RowMap)null!)); + } +} diff --git a/Tests/Open.Database.Extensions.Core.Tests/ExecuteReaderEdgeTests.cs b/Tests/Open.Database.Extensions.Core.Tests/ExecuteReaderEdgeTests.cs index 0885e1d3..3b8b033a 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/ExecuteReaderEdgeTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/ExecuteReaderEdgeTests.cs @@ -30,7 +30,9 @@ public static void First_OfNoRows_Throws_AndFirstOrDefault_ReturnsDefault() FakeExecuteReader command = Command(0, out _); Assert.Throws(() => command.First(Id)); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Null(command.FirstOrDefault(Name)); + #pragma warning restore CS0618 } [Theory] @@ -39,7 +41,9 @@ public static void First_AsksTheProviderForOneRow_AndReadsOnlyThatRow(string op) { FakeExecuteReader command = Command(5, out Func rowsRead); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. int id = op == "First" ? command.First(Id) : command.FirstOrDefault(Id); + #pragma warning restore CS0618 Assert.Equal(1, id); Assert.Equal(1, rowsRead()); @@ -55,7 +59,9 @@ public static void Single_WithTwoRows_Throws_SoTheProviderMustNotBeLimitedToOneR { FakeExecuteReader command = Command(2, out _); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Throws(() => op == "Single" ? command.Single(Id) : command.SingleOrDefault(Id)); + #pragma warning restore CS0618 Assert.False(Assert.Single(command.Behaviors).HasFlag(CommandBehavior.SingleRow)); // with it, the second row could never be seen } @@ -73,9 +79,11 @@ public static void TheSlice_IsWhatTheCountsSay_InTheOrderTheRowsCame(string call List ids = parts[0] switch { + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. "Take" => command.Take(int.Parse(parts[1]), Id), "Skip" => command.Skip(int.Parse(parts[1]), Id), _ => command.SkipThenTake(int.Parse(parts[1]), int.Parse(parts[2]), Id), + #pragma warning restore CS0618 }; Assert.Equal(expectedIds, string.Join(",", ids)); @@ -86,7 +94,9 @@ public static void Take_StopsReadingOnceItHasEnough() { FakeExecuteReader command = Command(5, out Func rowsRead); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. command.Take(2, Id); + #pragma warning restore CS0618 Assert.Equal(2, rowsRead()); } @@ -96,8 +106,10 @@ public static void ATakeOfZero_ReturnsNothing_WithoutExecutingTheCommand() { FakeExecuteReader command = Command(5, out _); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Empty(command.Take(0, Id)); Assert.Empty(command.SkipThenTake(3, 0, Id)); + #pragma warning restore CS0618 Assert.Equal(0, command.ExecuteCount); } @@ -112,9 +124,11 @@ public static void ANegativeCount_IsRefusedBeforeTheCommandRuns(string call, str { switch (call) { + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. case "Take": command.Take(-1, Id); break; case "Skip": command.Skip(-1, Id); break; default: command.SkipThenTake(0, -1, Id); break; + #pragma warning restore CS0618 } }); diff --git a/Tests/Open.Database.Extensions.Core.Tests/LeakMatrixTests.cs b/Tests/Open.Database.Extensions.Core.Tests/LeakMatrixTests.cs index deb2db8c..2c40bb06 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/LeakMatrixTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/LeakMatrixTests.cs @@ -78,7 +78,9 @@ static Terminal Async(string name, Traits traits, F using IEnumerator e = seq.GetEnumerator(); return e.MoveNext(); })), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Sync>("Results", RM, c => c.Results()), + #pragma warning restore CS0618 Sync("ExecuteReader.State", Traits.Reader, c => c.ExecuteReader(0, static (r, _) => r.Read())), Sync>("Retrieve", Traits.Reader, c => c.Retrieve()), Sync("ExecuteScalar", Traits.None, c => c.ExecuteScalar()), @@ -97,7 +99,9 @@ static Terminal Async(string name, Traits traits, F await using IAsyncEnumerator e = seq.GetAsyncEnumerator(ct); return await e.MoveNextAsync(); }, ct)), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Async>("ResultsAsync", RM, (c, ct) => c.UseCancellationToken(ct).ResultsAsync()), + #pragma warning restore CS0618 Async("ExecuteReaderAsync.State", Traits.Reader, (c, ct) => c.UseCancellationToken(ct).ExecuteReaderAsync(0, static (r, _) => new ValueTask(r.Read()))), Async>("RetrieveAsync", Traits.Reader, (c, ct) => c.UseCancellationToken(ct).RetrieveAsync()), Async("ExecuteScalarAsync", Traits.None, (c, ct) => c.UseCancellationToken(ct).ExecuteScalarAsync()), diff --git a/Tests/Open.Database.Extensions.Core.Tests/LeakRetentionTests.cs b/Tests/Open.Database.Extensions.Core.Tests/LeakRetentionTests.cs index 0ffaf908..ad78e122 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/LeakRetentionTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/LeakRetentionTests.cs @@ -66,7 +66,9 @@ static async Task CallAndTrack(string terminal, LeakSource sour model = (await command.Map().ToListAsync(token))[0]; break; case "ResultsAsync": + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. model = (await command.ResultsAsync()).First(); + #pragma warning restore CS0618 break; case "ToChannelAsync": ChannelReader channel = command.ToChannelAsync(true); diff --git a/Tests/Open.Database.Extensions.Core.Tests/MappingCharacterizationTests.cs b/Tests/Open.Database.Extensions.Core.Tests/MappingCharacterizationTests.cs index 6e0f43e1..bea938aa 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/MappingCharacterizationTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/MappingCharacterizationTests.cs @@ -23,7 +23,9 @@ static List Read(bool buffered, ImmutableArray columns, object? } var result = new QueryResult>([.. Enumerable.Range(0, columns.Length)], [.. columns.Select(c => c.Name)], new Queue([row!])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. return result.DequeueAs(map).ToList(); + #pragma warning restore CS0618 } static ImmutableArray Columns(params string[] names) => [.. names.Select(n => new ColumnDef(n, typeof(object)))]; diff --git a/Tests/Open.Database.Extensions.Core.Tests/MappingCostAndRaceCharacterizationTests.cs b/Tests/Open.Database.Extensions.Core.Tests/MappingCostAndRaceCharacterizationTests.cs index dee330fa..2f19db4f 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/MappingCostAndRaceCharacterizationTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/MappingCostAndRaceCharacterizationTests.cs @@ -273,7 +273,9 @@ public static void BufferedRows_MappedByManyThreadsAtOnce_GiveCorrectRows() for (int n = 0; n < 100; n++) { var result = new QueryResult>([.. Enumerable.Range(0, names.Length)], [.. names], new Queue([Row(columns, 1)!])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. AssertGadgets([.. result.DequeueAs(shared)], 1, hasNote: names.Contains("gadget_note")); + #pragma warning restore CS0618 } }); } @@ -489,7 +491,9 @@ public static void BufferedRows_OfARecord_MappedByManyThreadsAtOnce_GiveCorrectR for (int n = 0; n < 100; n++) { var result = new QueryResult>([.. Enumerable.Range(0, names.Length)], [.. names], new Queue([Row(columns, 1)!])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. AssertGadgetRecords([.. result.DequeueAs(shared)], 1, hasNote: names.Contains("gadget_note")); + #pragma warning restore CS0618 } }); } diff --git a/Tests/Open.Database.Extensions.Core.Tests/NullGuardDefectTests.cs b/Tests/Open.Database.Extensions.Core.Tests/NullGuardDefectTests.cs index 12844c53..b526299d 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/NullGuardDefectTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/NullGuardDefectTests.cs @@ -78,15 +78,21 @@ public static void IterateReader_NullSelector_IsRefusedBeforeTheCommandRuns() // Defect 6: a null result is an empty collection. It used to be refused by two of the constructors and a NullReferenceException when enumerated. [Fact] public static void QueryResultCollection_Sequences_NullResult_IsEmpty() + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. => Assert.Empty(new QueryResultCollection>(Ordinals, Names, null!)); + #pragma warning restore CS0618 [Fact] public static void QueryResultCollection_OfT_Sequences_NullResult_IsEmpty() + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. => Assert.Empty(new QueryResultCollection(Ordinals, Names, null!)); + #pragma warning restore CS0618 [Fact] public static void QueryResultCollection_ImmutableArray_NullResult_IsEmpty() + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. => Assert.Empty(new QueryResultCollection>([0], ["id"], null!)); + #pragma warning restore CS0618 // Defect 7: a null remainder means no more ordinals. It used to be a NullReferenceException while enumerated, after the first value. [Fact] diff --git a/Tests/Open.Database.Extensions.Core.Tests/QueryResultTests.cs b/Tests/Open.Database.Extensions.Core.Tests/QueryResultTests.cs index 8198c8f8..d68c34b6 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/QueryResultTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/QueryResultTests.cs @@ -57,10 +57,14 @@ public static void ImplicitConversion_ReturnsResult_AndRejectsNull() [Fact] public static void QueryResultCollection_NullResultIsEmpty_AndEnumeratesResult() { + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Empty(new QueryResultCollection>( + #pragma warning restore CS0618 ImmutableArray.Empty, ImmutableArray.Empty, null!)); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. var collection = new QueryResultCollection( + #pragma warning restore CS0618 ImmutableArray.Empty, ImmutableArray.Empty, Result); Assert.Equal([1, 2, 3], collection.ToList()); } @@ -88,7 +92,9 @@ public static void AsMappedDictionaries_MapsNamesToValues_AndConvertsDBNullToNul [2, DBNull.Value], }); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. var dictionaries = result.AsMappedDictionaries().ToList(); + #pragma warning restore CS0618 Assert.Equal(2, dictionaries.Count); Assert.Equal(1, dictionaries[0]["Id"]); diff --git a/Tests/Open.Database.Extensions.Core.Tests/RequiredMemberTests.cs b/Tests/Open.Database.Extensions.Core.Tests/RequiredMemberTests.cs index 110ead0e..f6c9c857 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/RequiredMemberTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/RequiredMemberTests.cs @@ -224,7 +224,9 @@ public static async Task AnEmptyResult_NeverReportsAMissingColumn_OnTheReaderRou Assert.Null(command.Map().FirstOrDefault()); Assert.Empty(await command.Map().ToListAsync(ct)); Assert.Null(await command.Map().FirstOrDefaultAsync(ct)); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Empty(command.Results()); + #pragma warning restore CS0618 Assert.Empty(FakeReader.Create(["Id"]).Results()); Assert.Empty(FakeReader.Create(["Id"]).ResultsBuffered()); @@ -245,7 +247,9 @@ public static void TheBufferedRoutes_BuildThePlanWhenTheBufferIsHandedOver_SoEve { string message = Missing("RequiredPost", "Title", "String", "Title"); var result = new QueryResult>([0], ["Id"], new Queue()); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Equal(message, Assert.Throws(() => result.DequeueAs()).Message); + #pragma warning restore CS0618 var table = new DataTable(); table.Columns.Add("Id", typeof(int)); @@ -253,7 +257,9 @@ public static void TheBufferedRoutes_BuildThePlanWhenTheBufferIsHandedOver_SoEve // With every column present an empty buffer maps to nothing. var complete = new QueryResult>([0, 1], ["Id", "Title"], new Queue()); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Empty(complete.DequeueAs()); + #pragma warning restore CS0618 } // ---- T15: a null column for a required property in a pair cannot be ignored ---- @@ -350,9 +356,13 @@ public static async Task Async_AndBufferedRoutes_MapARequiredType_AndReportAMiss Assert.Equal(message, (await Assert.ThrowsAsync(async () => await new FakeExecuteReader(() => TypedReader.Create(IdOnly, [1])).Map().ToListAsync(ct))).Message); var result = new QueryResult>([0, 1], ["Id", "Title"], new Queue(rows!)); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Equal([1, 2], (await Task.FromResult(result).DequeueAs()).Select(p => p.Id)); + #pragma warning restore CS0618 var one = new QueryResult>([0], ["Id"], new Queue([[1]])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Equal(message, (await Assert.ThrowsAsync(async () => await new ValueTask>>(one).DequeueAs())).Message); + #pragma warning restore CS0618 } [Fact] @@ -578,7 +588,9 @@ static void AddProperty(TypeBuilder type, string name, Type propertyType, Constr var result = new QueryResult>([0], ["Id"], new Queue([[1]])); try { + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Single(result.DequeueAs()); + #pragma warning restore CS0618 return null; } catch (ValueMappingException ex) diff --git a/Tests/Open.Database.Extensions.Core.Tests/RetrieveSurfaceTests.cs b/Tests/Open.Database.Extensions.Core.Tests/RetrieveSurfaceTests.cs index 01f0b53a..790cbfc0 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/RetrieveSurfaceTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/RetrieveSurfaceTests.cs @@ -367,7 +367,9 @@ public static void Retrieve_DequeueAsMappedDictionaries_NeedsNoCast() [Fact] public static void Retrieve_DequeueAs_NeedsNoCast() { + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. List rows = [.. NamedRowsCommand().Retrieve().DequeueAs()]; + #pragma warning restore CS0618 Assert.Equal([1, 2], rows.Select(r => r.Id)); Assert.Equal(["a", "b"], rows.Select(r => r.Name)); diff --git a/Tests/Open.Database.Extensions.Core.Tests/RowMapDeclarationTests.cs b/Tests/Open.Database.Extensions.Core.Tests/RowMapDeclarationTests.cs index 546f4066..5301f4f0 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/RowMapDeclarationTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/RowMapDeclarationTests.cs @@ -279,7 +279,9 @@ public static void Probe_Results_AcceptsACollectionExpression_AndAVariable() AssertRenamed(Reader().Results(declared).ToList()); AssertRenamed(Reader().Results([new(nameof(Item.Id), "item_id"), new(nameof(Item.Name), "item_name"), new(nameof(Item.Total), "item_total"), new(nameof(Item.Note), "item_note")]).ToList()); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. AssertRenamed(RowMapTests.Cmd(RowMapTests.Renamed, 2).Results([new(nameof(Item.Id), "item_id"), new(nameof(Item.Name), "item_name"), new(nameof(Item.Total), "item_total"), new(nameof(Item.Note), "item_note")]).ToList()); + #pragma warning restore CS0618 AssertRenamed(Reader().Results(new RowMap([new(nameof(Item.Id), "item_id"), new(nameof(Item.Name), "item_name"), new(nameof(Item.Total), "item_total"), new(nameof(Item.Note), "item_note")])).ToList()); AssertRenamed(Reader().Results(new RowMap(new(nameof(Item.Id), "item_id"), new(nameof(Item.Name), "item_name"), new(nameof(Item.Total), "item_total"), new(nameof(Item.Note), "item_note"))).ToList()); Assert.Equal(7, Assert.Single(FakeReader.Create(["Id"], [[7]]).Results([]).ToList()).Id); diff --git a/Tests/Open.Database.Extensions.Core.Tests/RowMapFamilyTests.cs b/Tests/Open.Database.Extensions.Core.Tests/RowMapFamilyTests.cs index 4358e185..16f2eeb7 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/RowMapFamilyTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/RowMapFamilyTests.cs @@ -17,8 +17,10 @@ public static void ExecuteReaderResults_WithoutAMap_ReadsByColumnName() { var command = new FakeExecuteReader(["Id", "Name"], [1, "one"]); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Assert.Equal(1, command.Results().Single().Id); Assert.Equal(1, command.Results((RowMap?)null).Single().Id); + #pragma warning restore CS0618 } sealed class AsyncCommand(FakeExecuteReader inner) : IExecuteReaderAsync @@ -124,14 +126,18 @@ static async Task> Enumerate(IAsyncEnumerable source) ["Results(IDataReader)"] = m => Now(Reader().Results(m)), ["ResultsBuffered(IDataReader)"] = m => Now(Reader().ResultsBuffered(m)), ["Results(IDbCommand)"] = m => Now(Command().Results(m)), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. ["Results(IExecuteReader)"] = m => Now(Exec().Results(m)), + #pragma warning restore CS0618 ["ResultsAsync(DbDataReader)"] = m => Enumerate(DbReader().ResultsAsync(m)), ["ResultsBufferedAsync(DbDataReader)"] = async m => (await DbReader().ResultsBufferedAsync(m)).ToList(), ["ResultsAsync(DbCommand)"] = async m => (await DbCmd().ResultsAsync(m)).ToList(), ["To(DataTable)"] = m => Now(Table().To(m)), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. ["DequeueAs(QueryResult)"] = m => Now(Queued().DequeueAs(m)), ["DequeueAs(Task)"] = async m => (await Task.FromResult(Queued()).DequeueAs(m)).ToList(), ["DequeueAs(ValueTask)"] = async m => (await new ValueTask>>(Queued()).DequeueAs(m)).ToList(), + #pragma warning restore CS0618 // Channel: a new channel ["ToChannel(IDataReader)"] = m => Drain(Reader().ToChannel(true, m)), diff --git a/Tests/Open.Database.Extensions.Core.Tests/RowMapNullTests.cs b/Tests/Open.Database.Extensions.Core.Tests/RowMapNullTests.cs index 2f0c10a9..4635602d 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/RowMapNullTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/RowMapNullTests.cs @@ -84,7 +84,9 @@ static List ViaReader(RowMap map, string? nullColumn) static List ViaArray(RowMap map, string? nullColumn) { QueryResult> result = new([.. Enumerable.Range(0, SolidNames.Length)], [.. SolidNames], new Queue([SolidRow(nullColumn)!])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. return result.DequeueAs(map).ToList(); + #pragma warning restore CS0618 } static readonly Func, string?, List>[] Routes = [ViaReader, ViaArray]; @@ -132,7 +134,9 @@ public static void NullInEveryColumn_KeepsEveryInitializer() AssertSame(new Solid(), Assert.Single(Cmd(SolidColumns, allNull).Map(map).ToList())); QueryResult> result = new([.. Enumerable.Range(0, SolidNames.Length)], [.. SolidNames], new Queue([allNull!])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. AssertSame(new Solid(), Assert.Single(result.DequeueAs(map).ToList())); + #pragma warning restore CS0618 } } @@ -147,7 +151,9 @@ public static void NullInAPropertyWithoutAnInitializer_LeavesTheDefault() Assert.Equal(Shade.None, viaReader.Shade); QueryResult> result = new([0, 1, 2], ["Count", "Created", "Shade"], new Queue([[null!, DBNull.Value, DBNull.Value]])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Plain viaArray = Assert.Single(result.DequeueAs(RowMap.Default).ToList()); + #pragma warning restore CS0618 Assert.Equal(0, viaArray.Count); Assert.Equal(default, viaArray.Created); Assert.Equal(Shade.None, viaArray.Shade); @@ -191,7 +197,9 @@ public static void NullableAndReferenceProperties_GetNull() // Buffered rows: a C# null and a DBNull both count as NULL. QueryResult> result = new([0, 1, 2], ["Maybe", "Text", "Tint"], new Queue([[null!, DBNull.Value, DBNull.Value]])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. Optional viaArray = Assert.Single(result.DequeueAs(RowMap.Default).ToList()); + #pragma warning restore CS0618 Assert.Null(viaArray.Maybe); Assert.Null(viaArray.Text); Assert.Null(viaArray.Tint); diff --git a/Tests/Open.Database.Extensions.Core.Tests/RowMapUnderscoreTests.cs b/Tests/Open.Database.Extensions.Core.Tests/RowMapUnderscoreTests.cs index 9a90bac1..c1f5bec9 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/RowMapUnderscoreTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/RowMapUnderscoreTests.cs @@ -165,7 +165,9 @@ public static void AColumnFeedsOneProperty_AndNeverTakesAFilledOne(string[] colu public static void BufferedRows_MapUnderscoredColumns() { QueryResult> result = new([.. Enumerable.Range(0, CountsNames.Length)], [.. CountsNames], new Queue([CountsRow()!])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. AssertCounts(result.DequeueAs().Single()); + #pragma warning restore CS0618 } // ---- (g) a NULL through an underscored column keeps the initializer ---- @@ -176,7 +178,9 @@ public static void ANullThroughAnUnderscoredColumn_KeepsTheInitializer() AssertCounts(Cmd(CountsColumns, CountsRow(nullDate: true)).Map().ToList().Single(), nullDate: true); QueryResult> result = new([.. Enumerable.Range(0, CountsNames.Length)], [.. CountsNames], new Queue([CountsRow(nullDate: true)!])); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. AssertCounts(result.DequeueAs().Single(), nullDate: true); + #pragma warning restore CS0618 } // ---- a wide result set ---- diff --git a/Tests/Open.Database.Extensions.Core.Tests/TransformerResultsTests.cs b/Tests/Open.Database.Extensions.Core.Tests/TransformerResultsTests.cs index fec79753..7d8e3319 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/TransformerResultsTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/TransformerResultsTests.cs @@ -77,7 +77,9 @@ public static void DequeueAs_MapsBufferedRows_CaseInsensitivelyWithOverride() queue); var map = new RowMap([new(nameof(Person.FirstName), "first_name")]); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. List people = [.. result.DequeueAs(map)]; + #pragma warning restore CS0618 Assert.Equal(2, people.Count); Assert.Equal("Jane", people[0].FirstName); diff --git a/Tests/Open.Database.Extensions.Core.Tests/UnmappableTypeTests.cs b/Tests/Open.Database.Extensions.Core.Tests/UnmappableTypeTests.cs index 0c4cec92..9c3e7661 100644 --- a/Tests/Open.Database.Extensions.Core.Tests/UnmappableTypeTests.cs +++ b/Tests/Open.Database.Extensions.Core.Tests/UnmappableTypeTests.cs @@ -392,16 +392,20 @@ static Task Run(Action call) ["Results(IDataReader, null)"] = () => Run(() => Reader().Results(null)), ["ResultsBuffered(IDataReader)"] = () => Run(() => Reader().ResultsBuffered()), ["Results(IDbCommand)"] = () => Run(() => Command().Results()), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. ["Results(IExecuteReader)"] = () => Run(() => Exec().Results()), + #pragma warning restore CS0618 ["ResultsAsync(DbDataReader)"] = () => Done(DbReader().ResultsAsync()), ["ResultsBufferedAsync(DbDataReader)"] = async () => await DbReader().ResultsBufferedAsync(), ["ResultsAsync(DbCommand)"] = async () => await DbCmd().ResultsAsync(), // Core: DataTable and Retrieve ["To(DataTable)"] = () => Run(() => Table().To()), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. ["DequeueAs(QueryResult)"] = () => Run(() => Queued().DequeueAs()), ["DequeueAs(Task)"] = async () => await Task.FromResult(Queued()).DequeueAs(), ["DequeueAs(ValueTask)"] = async () => await new ValueTask>>(Queued()).DequeueAs(), + #pragma warning restore CS0618 ["new Transformer()"] = () => Run(() => Transformer.Create()), // Channel: a new channel @@ -569,22 +573,28 @@ static ExpressiveDbCommand Expressive(Touched touched) // Core: a command ["Results(IDbCommand)"] = t => Run(() => Command(t).Results()), ["Results(IDbCommand, null)"] = t => Run(() => Command(t).Results(null)), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. ["Results(IExecuteReader)"] = t => Run(() => Exec(t).Results()), ["Results(IExecuteReader, null)"] = t => Run(() => Exec(t).Results(null)), + #pragma warning restore CS0618 ["Map() (IExecuteReader)"] = t => Run(() => Exec(t).Map().ToList()), ["ResultsAsync(DbCommand)"] = async t => await DbCmd(t).ResultsAsync(), ["ResultsAsync(DbCommand, null, token)"] = async t => await DbCmd(t).ResultsAsync(null, CancellationToken.None), ["ResultsAsync(DbCommand, token)"] = async t => await DbCmd(t).ResultsAsync(CancellationToken.None), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. ["ResultsFromDataTable(IDbCommand)"] = t => Run(() => Command(t).ResultsFromDataTable()), ["ExpressiveDbCommand.ResultsAsync()"] = async t => await Expressive(t).ResultsAsync(), ["ExpressiveDbCommand.ResultsAsync(null)"] = async t => await Expressive(t).ResultsAsync(null), + #pragma warning restore CS0618 // Core: a reader ["Results(IDataReader)"] = t => Run(() => Reader(t).Results()), ["ResultsBuffered(IDataReader)"] = t => Run(() => Reader(t).ResultsBuffered()), ["ResultsAsync(DbDataReader)"] = t => Done(DbReader(t).ResultsAsync()), ["ResultsBufferedAsync(DbDataReader)"] = async t => await DbReader(t).ResultsBufferedAsync(), + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. ["ResultsFromDataTable(IDataReader)"] = t => Run(() => Reader(t).ResultsFromDataTable()), + #pragma warning restore CS0618 // Channel: a command, a new channel ["ToChannel(IDbCommand)"] = t => Done(Command(t).ToChannel(true)), @@ -662,11 +672,15 @@ public static async Task TheProbes_SeeAnExecution_OfAMappableType() Assert.True(touched.Count() > 0); touched = new Touched(); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. _ = await Expressive(touched).ResultsAsync(); + #pragma warning restore CS0618 Assert.True(touched.Count() > 0); touched = new Touched(); + #pragma warning disable CS0618 // Obsolete in 11.0, removed in 12: kept covered until then. _ = Exec(touched).Results().ToList(); + #pragma warning restore CS0618 Assert.True(touched.Count() > 0); } } diff --git a/docsite/articles/foundation.md b/docsite/articles/foundation.md index 10daeed3..78e09bb0 100644 --- a/docsite/articles/foundation.md +++ b/docsite/articles/foundation.md @@ -35,7 +35,7 @@ A command built from a single connection refuses concurrent terminals: a second Several helpers exist to keep the time a connection is open short: - `EnsureOpen()` and `EnsureOpenAsync()` open a closed (or broken) connection and return its prior state, so you can restore it. -- Buffering helpers such as `Results()` queue the rows first and apply the transformation as you enumerate them. +- Buffering helpers such as `ResultsBuffered()` buffer the rows and map them in one call. On an `IExecuteReader`, `Results()`, `FirstOrDefault(selector)`, `SingleOrDefault(selector)`, `Take`, `Skip` and `SkipThenTake` are deprecated; use `Map(...)`. See [Deprecated in 11.0](whats-new-11.md#deprecated-in-110). - `Map()` streams rows straight out of the reader while the connection is open; the connection is released as soon as the terminal returns. ## Transactions @@ -46,6 +46,6 @@ Several helpers exist to keep the time a connection is open short: ## Reader and command helpers -The foundation also includes helpers you can use without the expressive syntax: `ForEach` and `ForEachAsync` over a reader, `Select` and `SelectAsync`, `AsEnumerable` and `AsAsyncEnumerable` (rows as `object[]`), `ToList`, `ToArray`, `ToDataTable` and friends on commands. Buffered reads copy the rows out of the reader first, so the connection can be released early: `Retrieve()` copies every row into a queue of `object[]`, and `DequeueAs()` maps that queue to `T` as you enumerate it. `Results()` buffers and maps in one call, and `FirstOrdinalResults()` reads the first column of every row as `T`. For typed rows `Map()` is the better route (see [Performance](performance.md#where-it-is-not-faster)). +The foundation also includes helpers you can use without the expressive syntax: `ForEach` and `ForEachAsync` over a reader, `Select` and `SelectAsync`, `AsEnumerable` and `AsAsyncEnumerable` (rows as `object[]`), `ToList`, `ToArray`, `ToDataTable` and friends on commands. Buffered reads copy the rows out of the reader first, so the connection can be released early: `Retrieve()` copies every row into a queue of `object[]` (raw rows with column names; `DequeueAsMappedDictionaries()` turns them into dictionaries). `DequeueAs()`, which mapped that queue to `T`, is deprecated: use `Map().ToList()`. `ResultsBuffered()` (and `Results()` on an `IDbCommand`, which buffers the rows and stays) buffers and maps in one call; `Results()` on an `IExecuteReader` is deprecated, use `Map().ToList()`. `FirstOrdinalResults()` reads the first column of every row as `T`. For typed rows `Map()` is the better route (see [Performance](performance.md#where-it-is-not-faster)). See the [API reference](xref:Open.Database.Extensions) for the full list. diff --git a/docsite/articles/mapping.md b/docsite/articles/mapping.md index 716be839..150da3fd 100644 --- a/docsite/articles/mapping.md +++ b/docsite/articles/mapping.md @@ -64,7 +64,7 @@ A constructor parameter is matched like a property: the same three tiers (exact, An `init` property is set like any other settable property. A `required` property is set the same way, and it must be fed: -- **A column must feed it, whatever the query** (a `required` property of a base class too). When the column names and types of a query include none for it, the first row throws `ValueMappingException`, with the property, its type, the model and the column that was looked for in the message. A query with no rows never reports it, except through the routes that know the columns before the first row: [`Retrieve()`](foundation.md#reader-and-command-helpers) with `DequeueAs()`, `DataTable.To()`, and `ToChannel` and the Dataflow methods ([Channels and Dataflow](channels-and-dataflow.md)). +- **A column must feed it, whatever the query** (a `required` property of a base class too). When the column names and types of a query include none for it, the first row throws `ValueMappingException`, with the property, its type, the model and the column that was looked for in the message. A query with no rows never reports it, except through the routes that know the columns before the first row: `DataTable.To()`, and `ToChannel` and the Dataflow methods ([Channels and Dataflow](channels-and-dataflow.md)). (`Retrieve()` with `DequeueAs()` did too; it is deprecated.) - **A constructor parameter's default does not feed it.** A `required` property needs its own column, even when a constructor parameter has the same name. - **A NULL in that column is not an error.** The column must be there, but a NULL cell leaves the property as it was: its initializer, else its default (`null` for a reference type), as for any other property. - **It cannot be ignored.** A `RowMap` pair with a `null` column for a `required` property throws `ArgumentException` when the map is created. @@ -143,7 +143,7 @@ Declare it with the collection syntax, created on first use with the C# 14 `fiel [!code-csharp[](../samples/Mapping.cs#map_declared)] -Pass it to `Map`. The same `map` parameter is on `Results()` and `DequeueAs()` ([the foundation](foundation.md#reader-and-command-helpers)) and on `ToChannel`, `AsSourceBlock` and `ToTargetBlock` ([Channels and Dataflow](channels-and-dataflow.md)): +Pass it to `Map`. The same `map` parameter is on `Results()` on a reader or an `IDbCommand` ([the foundation](foundation.md#reader-and-command-helpers); the `IExecuteReader` form is deprecated, use `Map(map).ToList()`) and on `ToChannel`, `AsSourceBlock` and `ToTargetBlock` ([Channels and Dataflow](channels-and-dataflow.md)). `DequeueAs()` also took one and is deprecated: use `Map(map).ToList()`. [!code-csharp[](../samples/Mapping.cs#map_declared_use)] @@ -230,6 +230,8 @@ A *result* here is one whole result set: what `NextResult` moves between. It is Two cases do not read through, so a later failure goes unseen: `.SingleResult()`, and a `Read` or an enumeration you stopped early (a `break` out of the rows, `First()` on them) or that ended in an exception of yours (the mapping, your selector, `SingleOrDefault` finding two rows, your handler). Your own exception is never replaced by a later one. `FirstOrDefault` and `Take` are not stopping early: they return their rows and still read through, and the provider discards the first set's unread rows on the way. +The deprecated `Results` on an `IExecuteReader`, the selector `FirstOrDefault`, `SingleOrDefault`, `Take`, `Skip` and `SkipThenTake`, `ExpressiveDbCommand.TakeAsync` and `ToListAsync(selector)`, and `Retrieve().DequeueAs()` read only the first result set. `Map` reads through the rest, and `.SingleResult()` restores the old behavior. See [Deprecated in 11.0](whats-new-11.md#deprecated-in-110). + `.SingleResult()` goes after `Map` (and on the result of `Skip` and `Take`). It asserts nothing: it does not check that there is only one result set. It stops after the first, so a later failure is not seen, and the reader is asked for `SingleResult` (`SingleRow` too for `FirstOrDefault` when nothing is skipped), which lets the provider stop early: ```csharp diff --git a/docsite/articles/performance.md b/docsite/articles/performance.md index 5c94e126..6eb2fadb 100644 --- a/docsite/articles/performance.md +++ b/docsite/articles/performance.md @@ -35,7 +35,7 @@ With a real database the server and the network dominate the time, so the speed ## Where it is not faster -- `Retrieve().DequeueAs()` copies every row to `object[]` first and maps later. It is not faster than a plain loop, and for typed results `Map()` is the better route. +- `Retrieve().DequeueAs()` is deprecated: it copies every row to `object[]` first and maps later, so it is not faster than a plain loop. Use `Map()`. - `ToChannel` and the Dataflow methods are not faster than reading rows in a plain loop. They exist to feed pipelines: see [Channels and Dataflow](channels-and-dataflow.md). - Selector-based mapping (`Map(selector)`) and `ScalarAsync` are ties with Dapper. - A few fixed-cost scenarios, such as a scalar query, allocate slightly more than Dapper because of the command object. diff --git a/docsite/articles/release-notes.md b/docsite/articles/release-notes.md index a5b19de5..7e1cc9f1 100644 --- a/docsite/articles/release-notes.md +++ b/docsite/articles/release-notes.md @@ -15,6 +15,8 @@ A modernization and allocation-reduction pass. Source-compatible with 10.0: exis cmd.Results([new("FirstName", "first_name"), new("LastName", "last_name")]); ``` + In 11, `Results` on an `IExecuteReader` and `ExpressiveDbCommand.ResultsAsync` are deprecated: see [Deprecated in 11.0](whats-new-11.md#deprecated-in-110). + - **Modernized `params`.** Ordinal helpers (`Retrieve`, `AsEnumerable` and others) accept `params IEnumerable` and `params IEnumerable`: any enumerable, not just arrays. - **Read-only inputs.** Several read-only `IList` parameters were widened to `IReadOnlyList` (`GetValuesFromOrdinals`, `EnumerateValuesFromOrdinals`, `ToDictionary`). Arrays, `List`, `ImmutableArray` and similar types still bind. A custom type that implements only `IList`, and not also `IReadOnlyList`, would need to recompile; no BCL collection is affected. - **Lower per-query overhead.** `Transformer` caches its per-type reflection once instead of rebuilding it on every query. Buffered and data-table paths pre-size collections and avoid redundant `Select` iterators. diff --git a/docsite/articles/whats-new-11.md b/docsite/articles/whats-new-11.md index 6fa97bd9..8ada7203 100644 --- a/docsite/articles/whats-new-11.md +++ b/docsite/articles/whats-new-11.md @@ -49,7 +49,7 @@ var people = cmd.Results(new("FirstName", "first_name"), new("LastName", // 11 public static RowMap PersonMap => field ??= [new(nameof(Person.FirstName), "first_name"), new(nameof(Person.LastName), "last_name")]; -var people = cmd.Results(PersonMap); +var people = cmd.Map(PersonMap).ToList(); ``` To keep a dictionary, build the map from it: `new RowMap(dictionary)`. Only `Map` also takes the pairs themselves, but that builds a new map on every call (about 0.43 ms and 29.5 KB for 12 properties): declare a map for anything that runs more than occasionally. @@ -71,6 +71,70 @@ These can change behavior without a compile error, most likely first: 13. **`EnsureOpenAsync` and `OpenAsync` have an obsolete `bool configureAwait` overload.** The library always awaits with `ConfigureAwait(false)`; returning to your context is your call. The `bool` overloads still compile with a warning and ignore the argument. 14. **Smaller items.** A static property is no longer mapped. `ResultsBuffered*` and `FirstOrdinalResults` still buffer into a queue and return a dequeuing enumerable. +## Deprecated in 11.0 + +These are obsolete in 11.0 (compile warning CS0618) and will be removed in 12. Each warning names the call to use instead. The old call still works until then. + +| Old call | New call | Behaviour difference | +|---|---|---| +| `Results(IExecuteReader)` | `.Map().ToList()`; with a map `.Map(map).ToList()` | Later result sets are read, so a later failure throws (`.SingleResult()` keeps the old behaviour). Returns a `List`. A null map is not accepted: use `Map()`. | +| `ExpressiveDbCommand.ResultsAsync` | `.Map().ToListAsync()` (token optional: `.ToListAsync(cancellationToken)`); with a map `.Map(map).ToListAsync()` | The same as above. | +| `ResultsFromDataTable` (reader, command) | `using var table = command.ToDataTable(); table.To(map, true)` | The same rows: the old body did exactly this, and `true` clears the table as rows are read. A type that cannot be mapped is reported after the data is loaded, not before the command runs: read `RowMap.Default` first to fail early. | +| `FirstOrDefault(selector)`, `SingleOrDefault(selector)` on `IExecuteReader` | `.Map(selector).FirstOrDefault()`, `.Map(selector).SingleOrDefault()` | Later result sets are read (`.SingleResult()` keeps the old behaviour). | +| `Take(n, selector)`, `Skip(n, selector)`, `SkipThenTake(s, t, selector)` on `IExecuteReader` | `.Map(selector).Take(n).ToList()`, `.Map(selector).Skip(n).ToList()`, `.Map(selector).Skip(s).Take(t).ToList()` | The selector is not run on skipped rows, so a selector that throws on one no longer fails the call. `Take(0)` now runs the command. Later result sets are read. | +| `ExpressiveDbCommand.TakeAsync(selector, n)`, `ExpressiveDbCommand.ToListAsync(selector)` | `.Map(selector).Take(n).ToListAsync(cancellationToken)`, `.Map(selector).ToListAsync(cancellationToken)` | Later result sets are read. Returns a `List`. `Take(0)` now runs the command. `Map` has no `CommandBehavior` argument: if you passed one, call `IterateReaderAsync(handler, behavior)` or `IterateReaderWhileAsync(handler, behavior)` yourself. | +| `QueryResultCollection`, `QueryResultCollection` | None | Nothing in the library returns it. Use the `List` from `Map().ToList()`, or your own class. | +| `cmd.Retrieve().DequeueAs()` (`QueryResultExtensions.DequeueAs`, 5 overloads) | `cmd.Map().ToList()`; with a map `cmd.Map(map).ToList()`. Async: `(await cmd.RetrieveAsync()).DequeueAs()` becomes `await cmd.Map().ToListAsync()`. On an `IDbCommand`: `command.Results()`. On an `IDataReader`: `reader.ResultsBuffered()`. On a `DbCommand`, async: `await command.ResultsAsync()`. | `Map` reads in one pass instead of copying raw rows first. A missing `required` column is reported at the first row, so not for an empty result. Later result sets are read (`.SingleResult()` keeps the first only, as `Retrieve` did). A null map is not accepted. `DequeueAs` returned a one-pass enumerable; `ToList()` returns a `List`. `Results(IDbCommand)` takes no `CommandBehavior`, where `Retrieve(IDbCommand, behavior)` did. | +| `QueryResultExtensions.AsMappedDictionaries` | `cmd.Retrieve().DequeueAsMappedDictionaries()`; async `(await cmd.RetrieveAsync()).DequeueAsMappedDictionaries()` | Nothing in the library produces the input it takes. `DequeueAsMappedDictionaries` drains the queue as it is enumerated, so it can be read once, where `AsMappedDictionaries` could be read again. | + +### Before and after + +Each pair below is compiled and run by the documentation build, and a check asserts that the two give the same result. + +`Results` on a command: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_results_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_results_after)] + +`ResultsAsync` on an expressive command: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_resultsasync_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_resultsasync_after)] + +`ResultsFromDataTable`: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_resultsfromdatatable_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_resultsfromdatatable_after)] + +The selector forms on an `IExecuteReader`: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_selector_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_selector_after)] + +`TakeAsync` and `ToListAsync` with a selector: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_takeasync_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_takeasync_after)] + +`QueryResultCollection` has no replacement; a list holds the same rows: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_collection_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_collection_after)] + +`AsMappedDictionaries`: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_mappeddictionaries_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_mappeddictionaries_after)] + +`Retrieve().DequeueAs()`: + +[!code-csharp[](../samples/Deprecated.cs#deprecated_dequeueas_before)] +[!code-csharp[](../samples/Deprecated.cs#deprecated_dequeueas_after)] + +### Why `Map` reads later result sets + +The old calls read only the first result set. `Map` reads through the later ones, so a failure in a later result set is thrown, not left unread. See [Results, and a failure after the first one](mapping.md#results-and-a-failure-after-the-first-one). Add `.SingleResult()` to read only the first, as the old calls did. + ## Fixes - **`ExecuteReturn()` and `ExecuteReturnAsync()`** return `default(T)` for a NULL return value instead of throwing `NullReferenceException` for a value type. @@ -84,11 +148,11 @@ These can change behavior without a compile error, most likely first: ## Known limitations -- `Retrieve()` followed by `DequeueAs()` is a two-pass route: rows are copied into `object[]` and mapped as they are drained. It is slower and allocates more than a direct `Map()` at larger sizes. For typed results prefer `Map()` or `ResultsBuffered()`. +- `Retrieve()` followed by `DequeueAs()` is deprecated in 11.0 (a two-pass route, slower than `Map()`): use `Map().ToList()`. See [Deprecated in 11.0](#deprecated-in-110). - The unmapped `ToChannel` overloads can still lose the row that was in flight when a read fails while the target is full. The cause is in the underlying channel library. - Output parameters can be sent, but their values cannot be read back after the call. Providers other than SQL Server supply no real parameter names, so `AddParam(search.Author)` uses the last member as written there. - `MappedQuery` has `FirstOrDefault` and `SingleOrDefault` but no throwing `First` or `Single`: check the result for `null`. -- A missing column for a `required` property is reported at the first row, so an empty result does not report it. `DequeueAs()`, `DataTable.To()`, `ToChannel` and the Dataflow methods know the columns before any row and report it even when no row follows. +- A missing column for a `required` property is reported by `Map` at the first row, so an empty result does not report it. `DataTable.To()`, `ToChannel` and the Dataflow methods know the columns before any row and report it even when no row follows. (`DequeueAs()` did too; it is deprecated.) - The synchronous `ToTargetBlock` overloads post each row without waiting: when the target is complete, or bounded and full, or when the internal 1,024-row buffer of the mapped overloads is full, reading stops without an error, and only the number the call returns (the rows read and handed over) shows the shortfall. Use the `Async` overload to feed a bounded target. - `AddParams(source)` sends every public member of `source` that the procedure declares, so pass an object you trust, and add a value that only the server may decide (a tenant, a deleted-rows flag) with `AddParam("name", value)`: a name you pass yourself always wins. - The unit tests run on in-memory providers. The documentation samples run on SQLite, and the benchmarks on the in-memory provider, SQLite and SQL Server LocalDB. Feedback from other providers and workloads is welcome. diff --git a/docsite/samples/Deprecated.cs b/docsite/samples/Deprecated.cs new file mode 100644 index 00000000..9aaa856a --- /dev/null +++ b/docsite/samples/Deprecated.cs @@ -0,0 +1,224 @@ +using System.Data; +using Microsoft.Data.Sqlite; +using Open.Database.Extensions; +using Open.Database.Extensions.Core; + +namespace Samples; + +/// +/// The "before" is the call that is obsolete in 11.0 (removed in 12), inside a pragma that hides its CS0618 warning; +/// the "after" is the call to type instead. Program.cs checks that both give the same result. +/// +public static class Deprecated +{ + const string PostsSql = "select * from posts order by id"; + const string IdsSql = "select id from posts order by id"; + + public static string Key(IEnumerable posts) => string.Join(",", posts.Select(post => $"{post.Id}:{post.Title}")); + + public static string Key(IEnumerable ids) => string.Join(",", ids); + + public static string Key(IEnumerable> rows) + => string.Join(";", rows.Select(row => string.Join(",", row.OrderBy(pair => pair.Key, StringComparer.Ordinal).Select(pair => $"{pair.Key}={pair.Value}")))); + + // The selector the old calls and Map both take. + static long Id(IDataRecord record) => record.GetInt64(0); + +#pragma warning disable CS0618 // shown in the docs as the call to replace + public static (string Before, string After) Results(SqliteConnection connection) + { + #region deprecated_results_before + List before = connection.Command(PostsSql).Results().ToList(); + #endregion + + #region deprecated_results_after + List after = connection.Command(PostsSql).Map().ToList(); + #endregion + + return (Key(before), Key(after)); + } + + public static async Task<(string Before, string After)> ResultsAsync(SqliteConnection connection) + { + #region deprecated_resultsasync_before + List before = (await connection.Command(PostsSql).ResultsAsync()).ToList(); + #endregion + + #region deprecated_resultsasync_after + List after = await connection.Command(PostsSql).Map().ToListAsync(); + #endregion + + return (Key(before), Key(after)); + } + + public static (string Before, string After) ResultsFromDataTable(SqliteConnection connection) + { + static SqliteCommand Create(SqliteConnection connection) + { + SqliteCommand command = connection.CreateCommand(); + command.CommandText = PostsSql; + return command; + } + + using SqliteCommand oldCommand = Create(connection); + #region deprecated_resultsfromdatatable_before + List before = oldCommand.ResultsFromDataTable().ToList(); + #endregion + + using SqliteCommand newCommand = Create(connection); + #region deprecated_resultsfromdatatable_after + // Reading the map first keeps the old behavior of failing before the command runs for a type that cannot be mapped. + RowMap map = RowMap.Default; + using var table = newCommand.ToDataTable(); + List after = table.To(map, true).ToList(); + #endregion + + return (Key(before), Key(after)); + } + + public static (string Before, string After) SelectorForms(SqliteConnection connection) + { + IExecuteReader command = connection.Command(IdsSql); + + #region deprecated_selector_before + long? first = command.FirstOrDefault(Id); + List taken = command.Take(2, Id); + List skipped = command.Skip(3, Id); + List sliced = command.SkipThenTake(1, 2, Id); + #endregion + + #region deprecated_selector_after + long? firstAfter = command.Map(Id).FirstOrDefault(); + List takenAfter = command.Map(Id).Take(2).ToList(); + List skippedAfter = command.Map(Id).Skip(3).ToList(); + List slicedAfter = command.Map(Id).Skip(1).Take(2).ToList(); + #endregion + + return ( + $"{first}|{Key(taken)}|{Key(skipped)}|{Key(sliced)}", + $"{firstAfter}|{Key(takenAfter)}|{Key(skippedAfter)}|{Key(slicedAfter)}"); + } + + /// A selector that throws on the first row: the old Skip ran it on the skipped row, Map does not. + public static (bool OldThrew, bool NewThrew) SkippedRowSelector(SqliteConnection connection) + { + static long ThrowsOnTheFirstRow(IDataRecord record) => record.GetInt64(0) == 1 ? throw new InvalidOperationException() : record.GetInt64(0); + IExecuteReader command = connection.Command(IdsSql); + + bool oldThrew; + try + { + command.Skip(1, ThrowsOnTheFirstRow); + oldThrew = false; + } + catch (InvalidOperationException) + { + oldThrew = true; + } + + bool newThrew; + try + { + command.Map(ThrowsOnTheFirstRow).Skip(1).ToList(); + newThrew = false; + } + catch (InvalidOperationException) + { + newThrew = true; + } + + return (oldThrew, newThrew); + } + + /// A command that cannot run (a missing table) shows it: Take(0) did not run it, and Map(...).Take(0) does. + public static (bool OldFailed, bool NewFailed) TakeOfZero(SqliteConnection connection) + { + IExecuteReader command = connection.Command("select id from no_such_table"); + + bool oldFailed; + try + { + command.Take(0, Id); + oldFailed = false; + } + catch (SqliteException) + { + oldFailed = true; + } + + bool newFailed; + try + { + command.Map(Id).Take(0).ToList(); + newFailed = false; + } + catch (SqliteException) + { + newFailed = true; + } + + return (oldFailed, newFailed); + } + + public static async Task<(string Before, string After)> TakeAsyncAndToListAsync(SqliteConnection connection) + { + #region deprecated_takeasync_before + IList taken = await connection.Command(IdsSql).TakeAsync(Id, 2); + List all = await connection.Command(IdsSql).ToListAsync(Id); + #endregion + + #region deprecated_takeasync_after + List takenAfter = await connection.Command(IdsSql).Map(Id).Take(2).ToListAsync(); + List allAfter = await connection.Command(IdsSql).Map(Id).ToListAsync(); + #endregion + + return ($"{Key(taken)}|{Key(all)}", $"{Key(takenAfter)}|{Key(allAfter)}"); + } + + /// Nothing in the library returns a QueryResultCollection, so there is no runnable before and after. + public static int Collection(SqliteConnection connection) + { + #region deprecated_collection_before + var rows = new QueryResultCollection([0], ["id"], connection.Command(IdsSql).Map(Id).ToList()); + #endregion + + #region deprecated_collection_after + List ids = connection.Command(IdsSql).Map(Id).ToList(); + #endregion + + return rows.Count() + ids.Count; + } + + public static async Task<(string Before, string After, string BeforeAsync, string AfterAsync)> MappedDictionaries(SqliteConnection connection) + { + // Nothing returns the QueryResult> that AsMappedDictionaries takes, so the sample builds one from a Retrieve. + QueryResult> retrieved = connection.Command(IdsSql).Retrieve(); + var source = new QueryResult>(retrieved.Ordinals, retrieved.Names, retrieved.Result.ToArray()); + + #region deprecated_mappeddictionaries_before + IEnumerable> before = source.AsMappedDictionaries(); + #endregion + + #region deprecated_mappeddictionaries_after + IEnumerable> after = connection.Command(IdsSql).Retrieve().DequeueAsMappedDictionaries(); + IEnumerable> afterAsync = (await connection.Command(IdsSql).RetrieveAsync()).DequeueAsMappedDictionaries(); + #endregion + + var beforeAsync = await Task.FromResult(new QueryResult>(retrieved.Ordinals, retrieved.Names, source.Result)).AsMappedDictionaries(); + return (Key(before), Key(after), Key(beforeAsync), Key(afterAsync)); + } + + public static (string Before, string After) DequeueAs(SqliteConnection connection) + { + #region deprecated_dequeueas_before + List before = connection.Command(PostsSql).Retrieve().DequeueAs().ToList(); + #endregion + + #region deprecated_dequeueas_after + List after = connection.Command(PostsSql).Map().ToList(); + #endregion + + return (Key(before), Key(after)); + } +#pragma warning restore CS0618 +} diff --git a/docsite/samples/Program.cs b/docsite/samples/Program.cs index de2ad63e..370d52db 100644 --- a/docsite/samples/Program.cs +++ b/docsite/samples/Program.cs @@ -173,6 +173,26 @@ void Check(bool condition, string what) long newId = ExpressiveCommands.InsertAndReadId(factory); Check(newId == 6 && factory.Command("select title from posts where id = 6").ExecuteScalar() == "New", "an insert and select last_insert_rowid() in one command return the generated id to ExecuteScalar()"); factory.Command("delete from posts where id = 6").ExecuteNonQuery(); +// Deprecated in 11.0: each old call and the call that replaces it give the same result. +Db.Seed(); +(string resultsBefore, string resultsAfter) = Deprecated.Results(connection); +Check(resultsBefore.Length > 0 && resultsBefore == resultsAfter, "Results() and Map().ToList() return the same rows"); +(resultsBefore, resultsAfter) = await Deprecated.ResultsAsync(connection); +Check(resultsBefore.Length > 0 && resultsBefore == resultsAfter, "ResultsAsync() and Map().ToListAsync() return the same rows"); +(resultsBefore, resultsAfter) = Deprecated.ResultsFromDataTable(connection); +Check(resultsBefore.Length > 0 && resultsBefore == resultsAfter, "ResultsFromDataTable() and ToDataTable().To(map, true) return the same rows"); +(resultsBefore, resultsAfter) = Deprecated.SelectorForms(connection); +Check(resultsBefore == "1|1,2|4,5|2,3" && resultsBefore == resultsAfter, "FirstOrDefault, Take, Skip and SkipThenTake with a selector match their Map forms"); +Check(Deprecated.SkippedRowSelector(connection) == (true, false), "a selector that throws on a skipped row failed Skip, and does not fail Map(...).Skip"); +Check(Deprecated.TakeOfZero(connection) == (false, true), "Take(0) did not run the command; Map(...).Take(0) does"); +(resultsBefore, resultsAfter) = await Deprecated.TakeAsyncAndToListAsync(connection); +Check(resultsBefore == "1,2|1,2,3,4,5" && resultsBefore == resultsAfter, "TakeAsync and ToListAsync with a selector match their Map forms"); +Check(Deprecated.Collection(connection) == 10, "QueryResultCollection holds rows; a List from Map holds the same"); +(string dictBefore, string dictAfter, string dictBeforeAsync, string dictAfterAsync) = await Deprecated.MappedDictionaries(connection); +Check(dictBefore.Length > 0 && dictBefore == dictAfter && dictBeforeAsync == dictAfterAsync && dictBefore == dictBeforeAsync, "AsMappedDictionaries and Retrieve().DequeueAsMappedDictionaries() (awaited too) return the same dictionaries"); +(resultsBefore, resultsAfter) = Deprecated.DequeueAs(connection); +Check(resultsBefore.Length > 0 && resultsBefore == resultsAfter, "Retrieve().DequeueAs() and Map().ToList() return the same rows"); + Console.WriteLine($"All {checks} sample checks passed."); return 0;