Skip to content

Correct SqlBatch command behavior exception documentation #4878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mdaigle merged 1 commit into from
Oct 20, 2026
+29 −17
Merged

Correct SqlBatch command behavior exception documentation #4878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 25 additions & 14 deletions doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,11 +235,16 @@
<ExecuteReader name="BehaviorParameter">
<param name="behavior">
An instance of <see cref="T:System.Data.CommandBehavior" />, specifying options for batch execution and data retrieval.
Only <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/> are supported at the batch level.
Supported values at the batch level are <see cref="F:System.Data.CommandBehavior.Default"/>,
<see cref="F:System.Data.CommandBehavior.SequentialAccess"/>, <see cref="F:System.Data.CommandBehavior.CloseConnection"/>,
or a bitwise combination of <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/>.
</param>
<summary>
Sends the <see cref="P:Microsoft.Data.SqlClient.SqlBatch.Commands" /> to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" /> and builds a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
</summary>
<exception cref="T:System.ArgumentOutOfRangeException">
The <paramref name="behavior" /> value is invalid or is not supported at the batch level.
</exception>
<example>
<para>
The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> and a <see cref="T:Microsoft.Data.SqlClient.SqlBatch" />, then adds multiple <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> objects to the batch. It then executes the batch, creating a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />. The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> and then the <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> as the <c>using</c> blocks fall out of scope.
Expand Down Expand Up @@ -293,35 +298,34 @@
<param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>
An asynchronous version of <see cref="M:Microsoft.Data.SqlClient.SqlBatch.ExecuteReader" />, which sends the <see cref="P:Microsoft.Data.SqlClient.SqlBatch.Commands" /> to the <see cref="P:Microsoft.Data.SqlClient.SqlBatch.Connection" /> and builds a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
Exceptions will be reported via the returned Task object.
Operational exceptions are reported via the returned task; usage exceptions are thrown synchronously.
</summary>
<returns>A task representing the asynchronous operation.</returns>
<exception cref="T:Microsoft.Data.SqlClient.SqlException">
An error occurred while executing the batch.
</exception>
<exception cref="T:System.ArgumentException">
The <see cref="T:System.Data.CommandBehavior" /> value is invalid.
</exception>
<exception cref="T:System.OperationCanceledException">
The cancellation token was canceled. This exception is stored into the returned task.
</exception>
</ExecuteReaderAsync>
<ExecuteReaderAsync name="BehaviorParameter">
<param name="behavior">
An instance of <see cref="T:System.Data.CommandBehavior" />, specifying options for batch execution and data retrieval.
Only <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/> are supported at the batch level.
Supported values at the batch level are <see cref="F:System.Data.CommandBehavior.Default"/>,
<see cref="F:System.Data.CommandBehavior.SequentialAccess"/>, <see cref="F:System.Data.CommandBehavior.CloseConnection"/>,
or a bitwise combination of <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/>.
</param>
<param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>
An asynchronous version of <see cref="M:Microsoft.Data.SqlClient.SqlBatch.ExecuteReader" />, which sends the <see cref="P:Microsoft.Data.SqlClient.SqlBatch.Commands" /> to the <see cref="P:Microsoft.Data.SqlClient.SqlBatch.Connection" /> and builds a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
Exceptions will be reported via the returned Task object.
Operational exceptions are reported via the returned task; usage exceptions are thrown synchronously.
</summary>
<returns>A task representing the asynchronous operation.</returns>
<exception cref="T:Microsoft.Data.SqlClient.SqlException">
An error occurred while executing the batch.
</exception>
<exception cref="T:System.ArgumentException">
The <see cref="T:System.Data.CommandBehavior" /> value is invalid.
<exception cref="T:System.ArgumentOutOfRangeException">
The <paramref name="behavior" /> value is invalid or is not supported at the batch level. This exception is thrown synchronously.
</exception>
<exception cref="T:System.OperationCanceledException">
The cancellation token was canceled. This exception is stored into the returned task.
Expand Down Expand Up @@ -381,7 +385,9 @@
<ExecuteDbDataReader>
<param name="behavior">
An instance of <see cref="T:System.Data.CommandBehavior" />, specifying options for batch execution and data retrieval.
Only <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/> are supported at the batch level.
Supported values at the batch level are <see cref="F:System.Data.CommandBehavior.Default"/>,
<see cref="F:System.Data.CommandBehavior.SequentialAccess"/>, <see cref="F:System.Data.CommandBehavior.CloseConnection"/>,
or a bitwise combination of <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/>.
</param>
<summary>
Executes the batch against its connection, returning a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> which can be used to access the results.
Expand All @@ -400,14 +406,16 @@ When the batch returns multiple result sets from different commands, <xref:Micro
<exception cref="T:Microsoft.Data.SqlClient.SqlException">
An error occurred while executing the batch.
</exception>
<exception cref="T:System.ArgumentException">
The <see cref="T:System.Data.CommandBehavior" /> value is invalid.
<exception cref="T:System.ArgumentOutOfRangeException">
The <paramref name="behavior" /> value is invalid or is not supported at the batch level.
</exception>
</ExecuteDbDataReader>
<ExecuteDbDataReaderAsync>
<param name="behavior">
An instance of <see cref="T:System.Data.CommandBehavior" />, specifying options for batch execution and data retrieval.
Only <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/> are supported at the batch level.
Supported values at the batch level are <see cref="F:System.Data.CommandBehavior.Default"/>,
<see cref="F:System.Data.CommandBehavior.SequentialAccess"/>, <see cref="F:System.Data.CommandBehavior.CloseConnection"/>,
or a bitwise combination of <see cref="F:System.Data.CommandBehavior.SequentialAccess"/> and <see cref="F:System.Data.CommandBehavior.CloseConnection"/>.
</param>
<param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>
Expand All @@ -419,13 +427,16 @@ When the batch returns multiple result sets from different commands, <xref:Micro
<![CDATA[
For more information about asynchronous programming, see [Asynchronous Programming](https://learn.microsoft.com/sql/connect/ado-net/asynchronous-programming).

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <xref:System.ArgumentException>, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <xref:System.Data.Common.DbBatch.ExecuteDbDataReader(System.Data.CommandBehavior)>.
This method stores exceptions in the task it returns, including exceptions for invalid or unsupported behavior values. These exceptions are thrown when the task is awaited. For possible exceptions, see <xref:Microsoft.Data.SqlClient.SqlBatch.ExecuteReader(System.Data.CommandBehavior)>.

> [!NOTE]
> This method benefits from <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync(System.Threading.CancellationToken)>, and all the expected exceptions of that method also apply here.
]]>
</format>
</remarks>
<exception cref="T:System.ArgumentOutOfRangeException">
The <paramref name="behavior" /> value is invalid or is not supported at the batch level. This exception is stored in the returned task.
</exception>
<exception cref="T:System.OperationCanceledException">
The cancellation token was canceled. This exception is stored into the returned task.
</exception>
Expand Down
7 changes: 4 additions & 3 deletions src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -371,15 +371,16 @@ private void SetupBatchCommandExecute()
/// <param name="behavior">The behavior flags to validate.</param>
/// <remarks>
/// <para>
/// Only <see cref="CommandBehavior.SequentialAccess"/> and <see cref="CommandBehavior.CloseConnection"/>
/// are supported at the batch level.
/// Supported values at the batch level are <see cref="CommandBehavior.Default"/>,
/// <see cref="CommandBehavior.SequentialAccess"/>, <see cref="CommandBehavior.CloseConnection"/>,
/// or a bitwise combination of <see cref="CommandBehavior.SequentialAccess"/> and <see cref="CommandBehavior.CloseConnection"/>.
/// </para>
/// <para>
/// To apply other behaviors (such as <see cref="CommandBehavior.SingleRow"/> or <see cref="CommandBehavior.SchemaOnly"/>),
/// they must be set on individual <see cref="SqlBatchCommand"/> instances within the batch.
/// </para>
/// </remarks>
/// <exception cref="NotSupportedException">Thrown when unsupported behavior flags are detected.</exception>
/// <exception cref="ArgumentOutOfRangeException">Thrown when the behavior value is invalid or unsupported at the batch level.</exception>
internal static void ValidateExecuteCommandBehavior(string method, CommandBehavior behavior)
{
if (0 != (behavior & ~(CommandBehavior.SequentialAccess | CommandBehavior.CloseConnection)))
Expand Down
Loading