[mdaigle]

Description

SqlBatch.ValidateExecuteCommandBehavior documents NotSupportedException, but invalid or unsupported behavior values throw ArgumentOutOfRangeException. Align the source comment and public XML documentation with the existing contract.

• Document all accepted batch behaviors: Default, SequentialAccess, CloseConnection, and the combination of the two flags.
• Use the precise exception type across behavior-taking reader methods and remove the inapplicable entry from the overload without a behavior parameter.
• Clarify synchronous validation in public ExecuteReaderAsync versus task-based exception reporting in the protected async wrapper.

Documentation only; no runtime behavior, public API signatures, or helper names change.

Issues

Fixes #4823

Testing

• .\eng\pipelines\onebranch\scripts\validate-xml-docs.ps1 -SnippetsDirectory .\doc\snippets - passed across 99 files. Reported 15 informational unprefixed-cref notices in unrelated snippets.
• git --no-pager diff --check - passed.
• Inspected the complete diff to confirm that all four behavior-taking reader sections are consistent and executable code is unchanged.

No unit or integration tests were added or run, and no driver build was run, because this is a documentation-only correction. Existing SqlBatchTest assertions already cover invalid and unsupported values throwing ArgumentOutOfRangeException.

• Tests added or updated (not applicable: documentation only)
• Public API changes documented (documentation corrected; signatures unchanged)
• Verified against customer repro (not applicable: no runtime defect)
• Ensure no breaking changes introduced

Guidelines

Please review the contribution guidelines before submitting a pull request:

• Contributing
• Code of Conduct
• Best Practices
• Coding Style
• Review Process

[Copilot]

🔵 Needs a closer look

Reported milestone validation failure and pending build checks remain unresolved in the available evidence.

No open issues 🎉

What changed in this PR

Corrects SqlBatch exception documentation to match the existing contract, addressing #4823 without runtime or API changes.

Changes:

• Lists all supported batch behaviors and their valid combination.
• Documents ArgumentOutOfRangeException on behavior-taking reader methods.
• Clarifies synchronous validation versus task-based exception reporting.

File	Description
src/​Microsoft.Data.SqlClient/​src/​Microsoft/​Data/​SqlClient/​SqlBatch.cs	Corrects the validation helper’s XML comment.
doc/​snippets/​Microsoft.Data.SqlClient/​SqlBatch.xml	Aligns public reader documentation with existing behavior.

_{Review effort: Balanced}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.51%. Comparing base (c7ab087) to head (1f1a9cd).
⚠️ Report is 16 commits behind head on main.

❗ There is a different number of reports uploaded between BASE (c7ab087) and HEAD (1f1a9cd). Click for more details.

HEAD has 2 uploads less than BASE

Flag	BASE (c7ab087)	HEAD (1f1a9cd)
CI-SqlClient	2	0

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4878      +/-   ##
==========================================
- Coverage   72.40%   65.51%   -6.90%     
==========================================
  Files         292      286       -6     
  Lines       45471    68617   +23146     
==========================================
+ Hits        32924    44951   +12027     
- Misses      12547    23666   +11119     

Flag	Coverage Δ
CI-SqlClient	?
PR-SqlClient-Project	65.51% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.