Skip to content

Old APIs with a direct 11.0 replacement are marked [Obsolete], each naming its replacement - #107

Merged
electricessence merged 9 commits into
masterfrom
chore/deprecate-legacy
Nov 10, 2026
Merged

electricessence merged 9 commits into
masterfrom
chore/deprecate-legacy

Conversation

@electricessence

@electricessence electricessence commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Builds on PR 106 (merged): the Retrieve().DequeueAsMappedDictionaries() replacement in the messages and samples compiles warning-free because of it.

What changes

22 members in 7 groups are marked [Obsolete] (a warning, CS0618, not an error) and will be removed in 12. Every message names the exact call to type instead, the behaviour difference, and ends with "Removed in 12." There is no new public API, and no PublicAPI file change (the analyzer does not track [Obsolete]). Nothing in Source calls any of them.

Old member Replacement Behaviour difference
Results<T>(IExecuteReader, RowMap<T>? = null) .Map<T>().ToList(); with a map .Map(map).ToList() Later result sets are read (.SingleResult() keeps the old behaviour). Returns List<T>. Map does not accept a null map.
ExpressiveDbCommand.ResultsAsync<T>(RowMap<T>? = null) and ResultsAsync<T>() .Map<T>().ToListAsync(); with a map .Map(map).ToListAsync() (token optional) The same as above.
ResultsFromDataTable<T> (IDataReader, IDbCommand) using var table = command.ToDataTable(); table.To<T>(map, true).ToList() Same rows (the old body was exactly this). A type that cannot be mapped is reported after the data is loaded; read RowMap<T>.Default first to fail early.
FirstOrDefault(selector) on IExecuteReader .Map(selector).FirstOrDefault() Later result sets are read.
SingleOrDefault(selector) on IExecuteReader .Map(selector).SingleOrDefault() Later result sets are read.
Take(count, selector) on IExecuteReader .Map(selector).Take(count).ToList() Later result sets are read. Take(0) now runs the command.
Skip(count, selector) on IExecuteReader .Map(selector).Skip(count).ToList() Later result sets are read. The selector is not run on skipped rows.
SkipThenTake(skip, take, selector) on IExecuteReader .Map(selector).Skip(skip).Take(take).ToList() As Skip and Take.
ExpressiveDbCommand.TakeAsync(selector, count, behavior) .Map(selector).Take(count).ToListAsync(cancellationToken) Later result sets are read. Returns List<T>. Take(0) now runs the command. No CommandBehavior: with one, use IterateReaderWhileAsync(r => { list.Add(selector(r)); return list.Count < count; }, behavior).
ExpressiveDbCommand.ToListAsync(selector, behavior) .Map(selector).ToListAsync(cancellationToken) Later result sets are read. No CommandBehavior: with one, use IterateReaderAsync(r => list.Add(selector(r)), behavior).
QueryResultCollection<T>, QueryResultCollection<T, TResult> None Nothing in the library returns it. Use a List<T> from Map<T>().ToList(), or your own class.
QueryResultExtensions.AsMappedDictionaries (3 overloads) cmd.Retrieve().DequeueAsMappedDictionaries(); async (await cmd.RetrieveAsync()).DequeueAsMappedDictionaries() Nothing produces the input it takes. DequeueAsMappedDictionaries drains the queue as it is enumerated, so it reads once.
QueryResultExtensions.DequeueAs<T> (5 overloads) cmd.Map<T>().ToList() (cmd.Map(map).ToList() with a map); async await cmd.Map<T>().ToListAsync(); IDbCommand command.Results<T>(); IDataReader reader.ResultsBuffered<T>(); DbCommand async await command.ResultsAsync<T>() One pass instead of copying raw rows first. A missing required column is reported at the first row (not for an empty result). Later result sets are read. Null map not accepted. DequeueAs<T> returned a one-pass enumerable; ToList() returns a List<T>. Results<T>(IDbCommand) takes no CommandBehavior.

DiagnosticId and UrlFormat are not used: they do not exist on ObsoleteAttribute for netstandard2.0/2.1, and a custom id would stop existing CS0618 suppressions from covering these.

Docs

  • whats-new-11.md: new section "Deprecated in 11.0" (table above, a before/after example for each group, and why Map reads later result sets); the 11 example in "Upgrading from 10.x" now uses Map<Person>(PersonMap).ToList(); the two "Known limitations" bullets that named DequeueAs<T>() are reworded.
  • foundation.md (two sentences), mapping.md (the map parameter sentence, the "column must feed it" routes, and a paragraph in "Results, and a failure after the first one"), performance.md (one bullet), release-notes.md (one sentence on the 10.1.0 bullet).
  • XML docs: every member starts with "Obsolete: use ..." with a resolving cref, and a remarks line linking to the section above.
  • The before/after code in the docs is the new compiled sample docsite/samples/Deprecated.cs.

Tests

  • Existing tests of the old behaviour stay, each call wrapped in a scoped #pragma warning disable CS0618 (with the reason: kept covered until 12). CS0618 is not in any NoWarn.
  • New DeprecationTests: a reflection test over all 22 members (is [Obsolete], a warning, names its replacement call, ends "Removed in 12."), and equivalence tests (old and new give the same rows) for Results<T>, ResultsFromDataTable<T>, the selector forms, AsMappedDictionaries and DequeueAs<T> (the ExpressiveDbCommand async forms are compared by the sample checks below; QueryResultCollection has nothing to compare), plus the pinned differences: a null map, a selector that throws on a skipped row, Take(0) running the command.
  • Deprecated.cs plus 10 new checks in the samples Program.cs: before and after agree for every group (including Retrieve().DequeueAsMappedDictionaries() and its awaited form, which compile warning-free with nullable enabled under -warnaserror), and the same two differences.
  • The benchmark that measures Retrieve().DequeueAs<T>() carries a scoped pragma.

Checks

From the gate (verify-gate.ps1) on the committed tree:

  • Release and Debug builds: 0 warnings, 0 errors (distinct warning lines: 0).
  • Core tests: 9255 passed, 0 failed, in Release and in Debug.
  • Samples build 0 warnings, 0 errors; "All 96 sample checks passed."
  • Style and analyzers on every project, all target frameworks, info level: 0 findings.
  • DocFX: 0 warnings, 0 errors.

Not in this change

The version bump and the "Changes since rc.3" note for rc.4. In 12, the removals need *REMOVED* lines in the PublicAPI files.

🤖 Generated with Claude Code

electricessence and others added 9 commits November 9, 2026 18:49
…aries without a nullable warning

Retrieve returns QueryResultQueue<object[]>, but DequeueAs<T> and DequeueAsMappedDictionaries
took QueryResult<Queue<object?[]>>. QueryResult<T> is invariant, so a nullable-enabled caller
got CS8620 on cmd.Retrieve().DequeueAsMappedDictionaries(). The rows hold object values (DBNull
for NULL, never null), so the parameters are now QueryResult<Queue<object[]>>, as is
Transformer<T>.AsDequeueingEnumerable(QueryResult<Queue<object[]>>). This is a nullable
annotation change only; there is no binary change.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…aming its replacement (library)

Groups 1-7: IExecuteReader Results<T>, ExpressiveDbCommand ResultsAsync<T>/TakeAsync/ToListAsync(transform), ResultsFromDataTable<T>, the selector FirstOrDefault/SingleOrDefault/Take/Skip/SkipThenTake, QueryResultCollection, AsMappedDictionaries and DequeueAs<T>. Removal in 12. No new public API.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…tionTests guards the messages and the replacements

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…rogram.cs checks they agree

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… the pages that named the old calls

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…th attributes, the sample uses a typed command and ImmutableArray

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…s (IDE0303)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…rned a one-pass enumerable and ToList() returns a List<T>, the QueryResultCollection message is one shared constant, and Deprecated.cs has a blank line between every method.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	Benchmarks/Open.Database.Extensions.Benchmarks/SyncBenchmarks.cs
#	Source/Core/Core/QueryResult.cs
#	Tests/Open.Database.Extensions.Core.Tests/ConstructorBindingTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/MappingCharacterizationTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/MappingCostAndRaceCharacterizationTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/RequiredMemberTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/RetrieveSurfaceTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/RowMapFamilyTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/RowMapNullTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/RowMapUnderscoreTests.cs
#	Tests/Open.Database.Extensions.Core.Tests/UnmappableTypeTests.cs
@electricessence
electricessence merged commit a18bab6 into master Nov 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant