Skip to content

Document how to read several result sets, and when to use Map<T>() or Results<T>() - #87

Merged
electricessence merged 1 commit into
fix/stabilization-after-rc1from
docs/several-result-sets
Nov 9, 2026
Merged

electricessence merged 1 commit into
fix/stabilization-after-rc1from
docs/several-result-sets

Conversation

@electricessence

Copy link
Copy Markdown
Collaborator

Builds on #85: merge that one first.

The library still reads one result set per call; this change documents how to read several yourself, and adds tests for it.

  • New page several-result-sets.md: the sync and async pattern (ExecuteReader, map, NextResult, map), the same on a connection you set up yourself, a loop for an unknown number of sets, unknown shapes (FieldCount, GetName, AsEnumerable, ToDataTables), the rules, and why the library does not do it for you. Every code block runs in the sample checks.
  • It states plainly what SQL Server does with an error raised after the rows (RAISERROR after a SELECT): it reaches you only when NextResult moves past that set. A table lists the measured cases, and the page shows the one-call check.
  • mapping.md has a new "Map<T>() or Results<T>()" section: a table by where you call it (when rows are read, when the connection is released, what you get back), and why Results<T> exists. Its old "Several result sets" section is now a pointer to the new page.
  • foundation.md is corrected: Results<T>() maps every row during the call and releases the connection; only the DataTable path queues rows first. coming-from-dapper.md and whats-new-11.md link to the new page.
  • XML docs only in Source/: one sentence on Map<T> and the reader-level Results<T>, ResultsAsync<T>, ResultsBuffered<T> and ResultsBufferedAsync<T> that they read the current result set and never move to the next.
  • New tests: on SQL Server LocalDB, two result sets of different shapes read sync and async with the caller's NextResult, and an error after the rows (Map<T>().ToList() returns the rows; the caller's NextResult throws SqlException); skipped where LocalDB is missing. In NeverNextResultTests: ToTargetBlock on a command, and the FirstOrDefault cases now use three rows and assert only one row was read.
  • No library behavior or public API changes.
  • Verification: Core, Channel and Dataflow build in Release with code style enforced: 0 warnings, 0 errors. Tests: 9,241 passed, 0 failed, 0 skipped in Release and in Debug (9,237 before, plus 4 new). Samples: "All 94 sample checks passed." DocFX: 0 warnings, 0 errors.

🤖 Generated with Claude Code

…provider and Never-NextResult tests

A new page shows how to read several result sets with the caller's NextResult, including the SQL Server error that follows the rows. mapping.md compares Map<T>() and Results<T>(); foundation.md no longer says Results<T>() queues rows. XML docs say the reader-level mappers read the current set only. No library behavior or public API changes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@electricessence
electricessence merged commit b461195 into fix/stabilization-after-rc1 Nov 9, 2026
2 checks passed
@electricessence
electricessence deleted the docs/several-result-sets branch November 9, 2026 15:14
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