SqlCommand.xml

<docs>
	<members name="SqlCommand">
		<SqlCommand>
			<summary>
				Represents a Transact-SQL statement or stored procedure to execute against a SQL Server database. This class cannot be inherited.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When an instance of <xref:Microsoft.Data.SqlClient.SqlCommand> is created, the read/write properties are set to their initial values. For a list of these values, see the <xref:Microsoft.Data.SqlClient.SqlCommand> constructor.

<xref:Microsoft.Data.SqlClient.SqlCommand> features the following methods for executing commands at a SQL Server database:

|Item|Description|
|----------|-----------------|
|<xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A>|Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this <xref:Microsoft.Data.SqlClient.SqlCommand>, generally executing commands such as INSERT, DELETE, UPDATE, and SET statements. Each call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> must be paired with a call to <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> which finishes the operation, typically on a separate thread.|
|<xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A>|Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this <xref:Microsoft.Data.SqlClient.SqlCommand> and retrieves one or more results sets from the server. Each call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> must be paired with a call to <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> which finishes the operation, typically on a separate thread.|
|<xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A>|Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this <xref:Microsoft.Data.SqlClient.SqlCommand>. Each call to `BeginExecuteXmlReader` must be paired with a call to `EndExecuteXmlReader`, which finishes the operation, typically on a separate thread, and returns an <xref:System.Xml.XmlReader> object.|
|<xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A>|Executes commands that return rows. For increased performance, <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> invokes commands using the Transact-SQL `sp_executesql` system stored procedure. Therefore, <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> might not have the effect that you want if used to execute commands such as Transact-SQL SET statements.|
|<xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery%2A>|Executes commands such as Transact-SQL INSERT, DELETE, UPDATE, and SET statements.|
|<xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar%2A>|Retrieves a single value (for example, an aggregate value) from a database.|
|<xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A>|Sends the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> to the <xref:Microsoft.Data.SqlClient.SqlCommand.Connection%2A> and builds an <xref:System.Xml.XmlReader> object.|

You can reset the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property and reuse the <xref:Microsoft.Data.SqlClient.SqlCommand> object. However, you must close the <xref:Microsoft.Data.SqlClient.SqlDataReader> before you can execute a new or previous command.

If a <xref:Microsoft.Data.SqlClient.SqlException> is generated by the method executing a <xref:Microsoft.Data.SqlClient.SqlCommand>, the <xref:Microsoft.Data.SqlClient.SqlConnection> remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the <xref:Microsoft.Data.SqlClient.SqlConnection>. However, the user can reopen the connection and continue.

> [!NOTE]
> Nameless, also called ordinal, parameters are not supported by the .NET Framework Data Provider for SQL Server.

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlConnection>, a <xref:Microsoft.Data.SqlClient.SqlCommand>, and a <xref:Microsoft.Data.SqlClient.SqlDataReader>. The example reads through the data, writing it to the console. Finally, the example closes the <xref:Microsoft.Data.SqlClient.SqlDataReader> and then the <xref:Microsoft.Data.SqlClient.SqlConnection> as it exits the `Using` code blocks.

[!code-csharp[SqlCommand Example#1](~/../sqlclient/doc/samples/SqlCommand.cs#1)]

The following sample shows how to create and execute different types of SqlCommand objects.

First you must create the sample database, by executing the following script:

[!code-sql[Setup Database](~/../sqlclient/doc/samples/SqlCommand_Setup.sql#1)]

Next, compile and execute the following:

[!code-csharp[SqlCommand Example#2](~/../sqlclient/doc/samples/SqlCommand_Intro.cs#1)]
]]></format>
			</remarks>
		</SqlCommand>
		<ctor name="default">
			<summary>
				Initializes a new instance of the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				class.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The base constructor initializes all fields to their default values. The following table shows initial property values for an instance of <xref:Microsoft.Data.SqlClient.SqlCommand>.

|Properties|Initial value|
|----------------|-------------------|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A>|empty string ("")|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A>|30|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A>|`CommandType.Text`|
|<xref:Microsoft.Data.SqlClient.SqlCommand.Connection%2A>|Null|

You can change the value for any of these properties through a separate call to the property.



## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and sets the `CommandTimeout` property.

[!code-csharp[Classic WebData IDbCommand_CommandTimeout.cs](~/../sqlclient/doc/samples/IDbCommand_CommandTimeout.cs)]
]]></format>
			</remarks>
		</ctor>
		<ctor name="cmdTextString">
			<param name="cmdText">
				The text of the query.
			</param>
			<summary>
				Initializes a new instance of the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				class with the text of the query.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When an instance of <xref:Microsoft.Data.SqlClient.SqlCommand> is created, the following read/write properties are set to initial values.

|Properties|Initial value|
|----------------|-------------------|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A>|`cmdText`|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A>|30|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A>|`CommandType.Text`|
|<xref:Microsoft.Data.SqlClient.SqlCommand.Connection%2A>|null|

You can change the value for any of these properties through a separate call to the property.

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand>, passing in the connection string and command text.

[!code-csharp[SqlCommand_SqlCommand1](~/../sqlclient/doc/samples/SqlCommand_SqlCommand1.cs#1)]
]]></format>
			</remarks>
		</ctor>
		<ctor name="cmdTextStringAndSqlConnection">
			<param name="cmdText">
				The text of the query.
			</param>
			<param name="connection">
				A
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				that represents the connection to an instance of SQL Server.
			</param>
			<summary>
				Initializes a new instance of the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				class with the text of the query and a
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The following table shows initial property values for an instance of <xref:Microsoft.Data.SqlClient.SqlCommand>.

|Properties|Initial value|
|----------------|-------------------|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A>|`cmdText`|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A>|30|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A>|`CommandType.Text`|
|<xref:Microsoft.Data.SqlClient.SqlCommand.Connection%2A>|A new <xref:Microsoft.Data.SqlClient.SqlConnection> that is the value for the `connection` parameter.|

You can change the value for any of these parameters by setting the related property.

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and sets some of its properties.

[!code-csharp[SqlCommand_SqlCommand2.cs](~/../sqlclient/doc/samples/SqlCommand_SqlCommand2.cs#1)]
]]></format>
			</remarks>
		</ctor>
		<ctor name="cmdTextStringAndSqlConnectionAndSqlTransaction">
			<param name="cmdText">
				The text of the query.
			</param>
			<param name="connection">
				A
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				that represents the connection to an instance of SQL Server.
			</param>
			<param name="transaction">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlTransaction" />
				in which the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				executes.
			</param>
			<summary>
				Initializes a new instance of the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				class with the text of the query, a
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				, and the
				<see cref="T:Microsoft.Data.SqlClient.SqlTransaction" />
				.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The following table shows initial property values for an instance of <xref:Microsoft.Data.SqlClient.SqlCommand>.

|Properties|Initial value|
|----------------|-------------------|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A>|`cmdText`|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A>|30|
|<xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A>|`CommandType.Text`|
|<xref:Microsoft.Data.SqlClient.SqlCommand.Connection%2A>|A new <xref:Microsoft.Data.SqlClient.SqlConnection> that is the value for the `connection` parameter.|

You can change the value for any of these parameters by setting the related property.
]]></format>
			</remarks>
		</ctor>
		<ctor name="cmdTextStringAndSqlConnectionAndSqlTransactionAndSqlCommandColumnEncryptionSetting">
			<param name="cmdText">
				The text of the query.
			</param>
			<param name="connection">
				A
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				that represents the connection to an instance of SQL Server.
			</param>
			<param name="transaction">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlTransaction" />
				in which the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				executes.
			</param>
			<param name="columnEncryptionSetting">
				The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine).
			</param>
			<summary>
				Initializes a new instance of the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				class with specified command text, connection, transaction, and encryption setting.
			</summary>
			<remarks>
				To be added.
			</remarks>
		</ctor>
		<BeginExecuteNonQuery name="default">
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll or wait for results, or both; this value is also needed when invoking
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" />
				, which returns the number of affected rows.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[
					
## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that does not return rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> method to finish the operation. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> method returns immediately, but until the code executes the corresponding <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> before the command's execution is completed causes the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous.

Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the <xref:System.IAsyncResult.IsCompleted%2A> property of the <xref:System.IAsyncResult> returned by the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> method; or wait for the completion of one or more commands using the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the returned <xref:System.IAsyncResult>.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.


## Examples
The following console application creates updates data within the **AdventureWorks** sample database, doing its work asynchronously. In order to emulate a long-running process, this example inserts a WAITFOR statement in the command text. Normally, you would not take efforts to make your commands run slower, but doing this in this case makes it easier to demonstrate the asynchronous behavior.

[!code-csharp[SqlCommand_BeginExecuteNonQuery](~/../sqlclient/doc/samples/SqlCommand_BeginExecuteNonQuery.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
        closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).

        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
      </exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</BeginExecuteNonQuery>
		<BeginExecuteNonQuery name="AsyncCallbackAndStateObject">
			<param name="callback">
				An
				<see cref="T:System.AsyncCallback" />
				delegate that is invoked when the command's execution has completed. Pass
				<see langword="null" />
				(
				<see langword="Nothing" />
				in Microsoft Visual Basic) to indicate that no callback is required.
			</param>
			<param name="stateObject">
				A user-defined state object that is passed to the callback procedure. Retrieve this object from within the callback procedure using the
				<see cref="P:System.IAsyncResult.AsyncState" />
				property.
			</param>
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				, given a callback procedure and state information.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll or wait for results, or both; this value is also needed when invoking
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" />
				, which returns the number of affected rows.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that does not return rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> method to finish the operation. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> method returns immediately, but until the code executes the corresponding <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> before the command's execution is completed causes the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

The `callback` parameter lets you specify an <xref:System.AsyncCallback> delegate that is called when the statement has completed. You can call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `asyncStateObject` parameter, and your callback procedure can retrieve this information using the <xref:System.IAsyncResult.AsyncState%2A> property.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous.

Because the callback procedure executes from within a background thread supplied by the Microsoft .NET common language runtime, it is very important that you take a rigorous approach to handling cross-thread interactions from within your applications. For example, you must not interact with a form's contents from within your callback procedure; should you have to update the form, you must switch back to the form's thread in order to do your work. The example in this topic demonstrates this behavior.

All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.

## Examples
The following Windows application demonstrates the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> method, executing a Transact-SQL statement that includes a delay of several seconds (emulating a long-running command).

This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called.

To set up this example, create a new Windows application. Put a <xref:System.Windows.Forms.Button> control and a <xref:System.Windows.Forms.Label> control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment.

[!code-csharp[DataWorks SqlCommand_BeginExecuteNonQueryForm#1](~/../sqlclient/doc/samples/SqlCommand_BeginExecuteNonQueryForm.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
        closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).

        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
      </exception>
		</BeginExecuteNonQuery>
		<BeginExecuteReader name="default">
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				, and retrieves one or more result sets from the server.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll or wait for results, or both; this value is also needed when invoking
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" />
				, which returns a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				instance that can be used to retrieve the returned rows.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method to finish the operation and retrieve the <xref:Microsoft.Data.SqlClient.SqlDataReader> returned by the command. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method returns immediately, but until the code executes the corresponding <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> before the command's execution is completed causes the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> may block if more data is required and the underlying network's read operation blocks.

Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the <xref:System.IAsyncResult.IsCompleted%2A> property of the <xref:System.IAsyncResult> returned by the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method; or wait for the completion of one or more commands using the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the returned <xref:System.IAsyncResult>.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.


## Examples
The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the <xref:System.IAsyncResult.IsCompleted%2A> property value. As soon as the process has completed, the code retrieves the <xref:Microsoft.Data.SqlClient.SqlDataReader> and displays its contents.

[!code-csharp[SqlCommand_BeginExecuteReader#1](~/../sqlclient/doc/samples/SqlCommand_BeginExecuteReader.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
        closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).

        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
      </exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</BeginExecuteReader>
		<BeginExecuteReader name="CommandBehavior">
			<param name="behavior">
				One of the
				<see cref="T:System.Data.CommandBehavior" />
				values, indicating options for statement execution and data retrieval.
			</param>
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				using one of the
				<see cref="T:System.Data.CommandBehavior" />
				values.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll, wait for results, or both; this value is also needed when invoking
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" />
				, which returns a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				instance that can be used to retrieve the returned rows.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method to finish the operation and retrieve the <xref:Microsoft.Data.SqlClient.SqlDataReader> returned by the command. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method returns immediately, but until the code executes the corresponding <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> before the command's execution is completed causes the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

The `behavior` parameter lets you specify options that control the behavior of the command and its connection. These values can be combined together (using the programming language's `OR` operator); generally, developers use the `CommandBehavior.CloseConnection` value to make sure that the connection is closed by the runtime when the <xref:Microsoft.Data.SqlClient.SqlDataReader> is closed.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> may block if more data is required and the underlying network's read operation blocks.

Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the <xref:System.IAsyncResult.IsCompleted%2A> property of the <xref:System.IAsyncResult> returned by the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery%2A> method; or wait for the completion of one or more commands using the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the returned <xref:System.IAsyncResult>.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.


## Examples
The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the <xref:System.IAsyncResult.IsCompleted%2A> property value. Once the process has completed, the code retrieves the <xref:Microsoft.Data.SqlClient.SqlDataReader> and displays its contents.

This example also passes the `CommandBehavior.CloseConnection` and `CommandBehavior.SingleRow` values in the behavior parameter, causing the connection to be closed with the returned <xref:Microsoft.Data.SqlClient.SqlDataReader> is closed, and to optimize for a single row result.

[!code-csharp[SqlCommand_BeginExecuteReaderAsyncSimple](~/../sqlclient/doc/samples/SqlCommand_BeginExecuteReaderAsyncSimple.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
        closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).

        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
      </exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</BeginExecuteReader>
		<BeginExecuteReader name="AsyncCallbackAndstateObject">
			<param name="callback">
				An
				<see cref="T:System.AsyncCallback" />
				delegate that is invoked when the command's execution has completed. Pass
				<see langword="null" />
				(
				<see langword="Nothing" />
				in Microsoft Visual Basic) to indicate that no callback is required.
			</param>
			<param name="stateObject">
				A user-defined state object that is passed to the callback procedure. Retrieve this object from within the callback procedure using the
				<see cref="P:System.IAsyncResult.AsyncState" />
				property.
			</param>
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				and retrieves one or more result sets from the server, given a callback procedure and state information.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll, wait for results, or both; this value is also needed when invoking
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" />
				, which returns a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				instance which can be used to retrieve the returned rows.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method to finish the operation and retrieve the <xref:Microsoft.Data.SqlClient.SqlDataReader> returned by the command. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method returns immediately, but until the code executes the corresponding <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> before the command's execution is completed cause the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

The `callback` parameter lets you specify an <xref:System.AsyncCallback> delegate that is called when the statement has completed. You can call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the <xref:System.IAsyncResult.AsyncState%2A> property.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> may block if more data is required and the underlying network's read operation blocks.

Because the callback procedure executes from within a background thread supplied by the Microsoft .NET runtime, it is very important that you take a rigorous approach to handling cross-thread interactions from within your applications. For example, you must not interact with a form's contents from within your callback procedure; should you have to update the form, you must switch back to the form's thread in order to do your work. The example in this topic demonstrates this behavior.

All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.


## Examples
The following Windows application demonstrates the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). Because the sample executes the command asynchronously, the form remains responsive while awaiting the results. This example passes the executing <xref:Microsoft.Data.SqlClient.SqlCommand> object as the `stateObject` parameter; doing so makes it simple to retrieve the <xref:Microsoft.Data.SqlClient.SqlCommand> object from within the callback procedure, so that the code can call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method corresponding to the initial call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A>.

This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called.

To set up this example, create a new Windows application. Put a <xref:System.Windows.Forms.Button> control, a <xref:System.Windows.Forms.DataGridView> control, and a <xref:System.Windows.Forms.Label> control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment.

[!code-csharp[SqlCommand_BeginExecuteReaderAsync.cs](~/../sqlclient/doc/samples/SqlCommand_BeginExecuteReaderAsync.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
        closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).

        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
      </exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</BeginExecuteReader>
		<BeginExecuteReader name="AsyncCallbackAndstateObjectAndCommandBehavior">
			<param name="callback">
				An
				<see cref="T:System.AsyncCallback" />
				delegate that is invoked when the command's execution has completed. Pass
				<see langword="null" />
				(
				<see langword="Nothing" />
				in Microsoft Visual Basic) to indicate that no callback is required.
			</param>
			<param name="stateObject">
				A user-defined state object that is passed to the callback procedure. Retrieve this object from within the callback procedure using the
				<see cref="P:System.IAsyncResult.AsyncState" />
				property.
			</param>
			<param name="behavior">
				One of the
				<see cref="T:System.Data.CommandBehavior" />
				values, indicating options for statement execution and data retrieval.
			</param>
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				, using one of the
				<see langword="CommandBehavior" />
				values, and retrieving one or more result sets from the server, given a callback procedure and state information.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll or wait for results, or both; this value is also needed when invoking
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" />
				, which returns a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				instance which can be used to retrieve the returned rows.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method to finish the operation and retrieve the <xref:Microsoft.Data.SqlClient.SqlDataReader> returned by the command. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method returns immediately, but until the code executes the corresponding <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> before the command's execution is completed causes the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

The `callback` parameter lets you specify an <xref:System.AsyncCallback> delegate that is called when the statement has completed. You can call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the <xref:System.IAsyncResult.AsyncState%2A> property.

The `behavior` parameter lets you specify options that control the behavior of the command and its connection. These values can be combined together (using the programming language's `Or` operator); generally, developers use the `CloseConnection` value to make sure that the connection is closed by the runtime when the <xref:Microsoft.Data.SqlClient.SqlDataReader> is closed. Developers can also optimize the behavior of the <xref:Microsoft.Data.SqlClient.SqlDataReader> by specifying the `SingleRow` value when it is known in advance that the Transact-SQL statement or stored procedure only returns a single row.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> may block if more data is required and the underlying network's read operation blocks.

Because the callback procedure executes from within a background thread supplied by the Microsoft .NET common language runtime, it is very important that you take a rigorous approach to handling cross-thread interactions from within your applications. For example, you must not interact with a form's contents from within your callback procedure--should you have to update the form, you must switch back to the form's thread in order to do your work. The example in this topic demonstrates this behavior.

All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.


## Examples
The following Windows application demonstrates the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). Because the sample executes the command asynchronously, the form remains responsive while awaiting the results. This example passes the executing <xref:Microsoft.Data.SqlClient.SqlCommand> object as the `stateObject` parameter; doing so makes it simple to retrieve the <xref:Microsoft.Data.SqlClient.SqlCommand> object from within the callback procedure, so that the code can call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method corresponding to the initial call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A>.

This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called.

To set up this example, create a new Windows application. Put a <xref:System.Windows.Forms.Button> control, a <xref:System.Windows.Forms.DataGridView> control, and a <xref:System.Windows.Forms.Label> control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment.

This example passes the `CommandBehavior.CloseConnection` value in the `behavior` parameter, causing the returned <xref:Microsoft.Data.SqlClient.SqlDataReader> to automatically close its connection when it is closed.

[!code-csharp[SqlCommand_BeginExecuteReaderAsyncBehavior](~/../sqlclient/doc/samples/SqlCommand_BeginExecuteReaderAsyncBehavior.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
        closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).

        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
      </exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</BeginExecuteReader>
		<BeginExecuteXmlReader name="default">
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				and returns results as an
				<see cref="T:System.Xml.XmlReader" />
				object.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll or wait for results, or both; this value is also needed when invoking
				<see langword="EndExecuteXmlReader" />
				, which returns a single XML value.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> method starts the process of asynchronously executing a Transact-SQL statement that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the `EndExecuteXmlReader` method to finish the operation and retrieve the XML returned by the command. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> method returns immediately, but until the code executes the corresponding `EndExecuteXmlReader` method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the `EndExecuteXmlReader` before the command's execution is completed causes the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

The <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns `ntext` data that contains valid XML.

A typical <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> query can be formatted as in the following C# example:

```csharp
SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM dbo.Contact FOR XML AUTO, XMLDATA", SqlConn);
```

This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the `EndExecuteXmlReader` method attaches the <xref:System.Xml.XmlReader> to the value on the first row, and discards the rest of the result set.

The multiple active result set (MARS) feature lets multiple actions use the same connection.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous.

Because this overload does not support a callback procedure, developers need to either poll to determine whether the command has completed, using the <xref:System.IAsyncResult.IsCompleted%2A> property of the <xref:System.IAsyncResult> returned by the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> method; or wait for the completion of one or more commands using the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the returned <xref:System.IAsyncResult>.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.


## Examples
The following console application starts the process of retrieving XML data asynchronously. While waiting for the results, this simple application sits in a loop, investigating the <xref:System.IAsyncResult.IsCompleted%2A> property value. Once the process has completed, the code retrieves the XML and displays its contents.

[!code-csharp[SqlCommand_BeginExecuteXmlReader#1]((~/../sqlclient/doc/samples/SqlCommand_BeginExecuteXmlReader.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
        
        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</BeginExecuteXmlReader>
		<BeginExecuteXmlReader name="AsyncCallbackAndstateObject">
			<param name="callback">
				An
				<see cref="T:System.AsyncCallback" />
				delegate that is invoked when the command's execution has completed. Pass
				<see langword="null" />
				(
				<see langword="Nothing" />
				in Microsoft Visual Basic) to indicate that no callback is required.
			</param>
			<param name="stateObject">
				A user-defined state object that is passed to the callback procedure. Retrieve this object from within the callback procedure using the
				<see cref="P:System.IAsyncResult.AsyncState" />
				property.
			</param>
			<summary>
				Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				and returns results as an
				<see cref="T:System.Xml.XmlReader" />
				object, using a callback procedure.
			</summary>
			<returns>
				An
				<see cref="T:System.IAsyncResult" />
				that can be used to poll, wait for results, or both; this value is also needed when the
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" />
				is called, which returns the results of the command as XML.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> method to finish the operation and retrieve the requested XML data. The <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> method returns immediately, but until the code executes the corresponding <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <xref:Microsoft.Data.SqlClient.SqlCommand> object. Calling the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> before the command's execution is completed causes the <xref:Microsoft.Data.SqlClient.SqlCommand> object to block until the execution is finished.

The <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns data that contains valid XML. This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> method attaches the <xref:System.Xml.XmlReader> to the value on the first row, and discards the rest of the result set.

A typical <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> query can be formatted as in the following C# example:

```csharp
SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM Contact FOR XML AUTO, XMLDATA", SqlConn);
```

This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> method attaches the <xref:System.Xml.XmlReader> to the value on the first row, and discards the rest of the result set.

The multiple active result set (MARS) feature lets multiple actions use the same connection.

The `callback` parameter lets you specify an <xref:System.AsyncCallback> delegate that is called when the statement has completed. You can call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the <xref:System.IAsyncResult.AsyncState%2A> property.

Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters is sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous.

All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

This method ignores the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property.


## Examples
The following Windows application demonstrates the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). This example passes the executing <xref:Microsoft.Data.SqlClient.SqlCommand> object as the `stateObject` parameter--doing so makes it simple to retrieve the <xref:Microsoft.Data.SqlClient.SqlCommand> object from within the callback procedure, so that the code can call the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> method corresponding to the initial call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A>.

This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called.

To set up this example, create a new Windows application. Put a <xref:System.Windows.Forms.Button> control, a <xref:System.Windows.Forms.ListBox> control, and a <xref:System.Windows.Forms.Label> control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment.

[!code-csharp[SqlCommand_BeginExecuteXmlReaderAsync](~/../sqlclient/doc/samples/SqlCommand_BeginExecuteXmlReaderAsync.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				Any error that occurred while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
        closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).

        - or -

        <see cref="P:Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding" />
        is set to true and a parameter with direction Output or InputOutput has been added to the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Parameters" /> collection.
      </exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<altmember cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" />
			<altmember cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" />
		</BeginExecuteXmlReader>
		<Cancel>
			<summary>
				Tries to cancel the execution of a
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
If there is nothing to cancel, nothing occurs. However, if there is a command in process, and the attempt to cancel fails, no exception is generated.

In some rare cases, if you call <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A>, then call <xref:Microsoft.Data.SqlClient.SqlDataReader.Close%2A> (implicitly or explicitly) before calling <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A>, and then call <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A>, the cancel command will not be sent to SQL Server and the result set can continue to stream after you call <xref:Microsoft.Data.SqlClient.SqlConnection.Close%2A>. To avoid this, make sure that you call <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> before closing the reader or connection.


## Examples
The following example demonstrates the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.

[!code-csharp[SqlCommand_Cancel](~/../sqlclient/doc/samples/SqlCommand_Cancel.cs)]
]]></format>
			</remarks>
		</Cancel>
		<Clone>
			<summary>
				Creates a new
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				object that is a copy of the current instance.
			</summary>
			<returns>
				A new
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				object that is a copy of this instance.
			</returns>
			<remarks>
				To be added.
			</remarks>
		</Clone>
		<ColumnEncryptionSetting>
			<summary>
				Gets the column encryption setting for this command.
			</summary>
			<value>
				The column encryption setting for this command.
			</value>
		</ColumnEncryptionSetting>
		<CommandText>
			<summary>
				Gets or sets the Transact-SQL statement, table name or stored procedure to execute at the data source.
			</summary>
			<value>
				The Transact-SQL statement or stored procedure to execute. The default is an empty string.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A> property is set to `StoredProcedure`, the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the `Execute` methods.

The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a Transact-SQL statement or a stored procedure called by a command of `CommandType.Text`. In this case, named parameters must be used. For example:

```sql
SELECT * FROM dbo.Customers WHERE CustomerID = @CustomerID
```

For more information, see [Configuring parameters](/sql/connect/ado-net/configure-parameters).

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and sets some of its properties.

[!code-csharp[SqlCommand_CommandText](~/../sqlclient/doc/samples/SqlCommand_CommandText.cs)]
]]></format>
			</remarks>
		</CommandText>
		<CommandTimeout>
			<summary>
				Gets or sets the wait time (in seconds) before terminating the attempt to execute a command and generating an error. The default is 30 seconds.
			</summary>
			<value>
				The time in seconds to wait for the command to execute. The default is 30 seconds.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
A value of 0 indicates no limit (an attempt to execute a command will wait indefinitely).

> [!NOTE]
> The <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> property will be ignored during old-style asynchronous method calls such as <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A>. It will be honored by the newer async methods such as <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync%2A>.

> [!NOTE]
> This property is the cumulative time-out (for all network packets that are read during the invocation of a method) for all network reads during command execution or processing of the results. A time-out can still occur after the first row is returned, and does not include user processing time, only network read time.

For example, with a 30 second time out, if <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> requires two network packets, then it has 30 seconds to read both network packets. If you call <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> again, it will have another 30 seconds to read any data that it requires.

[!code-csharp[SqlCommand CommandTimeout](~/../sqlclient/doc/samples/SqlCommand_CommandTimeout.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.ArgumentException">The value set is less than 0.</exception>
		</CommandTimeout>
		<CommandType>
			<summary>
				Gets or sets a value indicating how the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				property is to be interpreted.
			</summary>
			<value>
				One of the
				<see cref="T:System.Data.CommandType" />
				values. The default is
				<see langword="Text" />
				.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When you set the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A> property to `StoredProcedure`, you should set the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods.

The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a SQL Statement or a stored procedure called with a <xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A> of <xref:System.Data.CommandType.Text>. In this case, named parameters must be used. For example:

SELECT * FROM Customers WHERE CustomerID = @CustomerID

For more information, see [Configuring parameters](/sql/connect/ado-net/configure-parameters).

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and sets some of its properties.

[!code-csharp[IDbCommand_CommandTimeout](~/../sqlclient/doc/samples/IDbCommand_CommandTimeout.cs)]
]]></format>
			</remarks>
		</CommandType>
		<Connection>
			<summary>
				Gets or sets the
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				used by this instance of the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				.
			</summary>
			<value>
				The connection to a data source. The default value is
				<see langword="null" />
				.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
If the command is enlisted in an existing transaction, and the connection is changed, trying to execute the command will throw an <xref:System.InvalidOperationException>.

If the <xref:Microsoft.Data.SqlClient.SqlCommand.Transaction%2A> property is not null and the transaction has already been committed or rolled back, <xref:Microsoft.Data.SqlClient.SqlCommand.Transaction%2A> is set to null.



## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and sets some of its properties.

[!code-csharp[SqlCommand_Connection](~/../sqlclient/doc/samples/SqlCommand_Connection.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				property was changed while the command was enlisted in a transaction.
			</exception>
		</Connection>
		<CreateDbParameter>
			<summary>
				To be added.
			</summary>
			<returns>
				To be added.
			</returns>
			<remarks>
				To be added.
			</remarks>
		</CreateDbParameter>
		<CreateParameter>
			<summary>
				Creates a new instance of a
				<see cref="T:Microsoft.Data.SqlClient.SqlParameter" />
				object.
			</summary>
			<returns>
				A
				<see cref="T:Microsoft.Data.SqlClient.SqlParameter" />
				object.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.SqlClient.SqlCommand.CreateParameter%2A> method is a strongly-typed version of <xref:System.Data.IDbCommand.CreateParameter%2A>.
]]></format>
			</remarks>
		</CreateParameter>
		<DbConnection>
			<summary>
				To be added.
			</summary>
			<value>
				To be added.
			</value>
			<remarks>
				To be added.
			</remarks>
		</DbConnection>
		<DbParameterCollection>
			<summary>
				Gets the collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> objects.
			</summary>
			<value>
				The parameters of the SQL statement or stored procedure.
			</value>
			<remarks>
				To be added.
			</remarks>
		</DbParameterCollection>
		<DbTransaction>
			<summary>
				To be added.
			</summary>
			<value>
				To be added.
			</value>
			<remarks>
				To be added.
			</remarks>
		</DbTransaction>
		<DesignTimeVisible>
			<summary>
				Gets or sets a value indicating whether the command object should be visible in a Windows Form Designer control.
			</summary>
			<value>
				A value indicating whether the command object should be visible in a control. The default is
				<see langword="true" />
				.
			</value>
			<remarks>
				To be added.
			</remarks>
		</DesignTimeVisible>
		<Dispose>
			<param name="disposing">
				To be added.
			</param>
			<summary>
				To be added.
			</summary>
			<remarks>
				To be added.
			</remarks>
		</Dispose>
    <EnableOptimizedParameterBinding>
      <summary>
        Gets or sets a value indicating whether the command object should optimize parameter performance by disabling Output and InputOutput directions when submitting the command to the SQL Server. <br />
        This option is only used when the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /> is <see cref="System.Data.CommandType.Text" >Text</see> otherwise it is ignored.
      </summary>
      <value>
        A value indicating whether the command object should optimize parameter performance by disabling Output and InputOuput parameter directions when submitting the command to the SQL Server. 
        The default is <see langword="false" />.
      </value>
      <remarks>
        <format type="text/markdown">
          <![CDATA[
## Remarks
You must set the value for this property before the command is executed for it to take effect.

When a command is submitted to the server with parameters a list of the parameter names is sent as part of the submission. The list is used on the server to match Output and InputOutput parameters to the results of the query execution so that the values can be returned to the caller. This option disables the construction and submission of the parameter name list and as a consequence disables the use of Output and InputOutput parameters. The return parameter is not affected by this option.

A command sent with this option changes the way parameters are handled on the server, because there is no need to maintain an output parameter map. The result of this change is that queries with large numbers of input parameters may execute much faster. 

The fewest number of parameters where this will take effect depends on the individual situation and should be detected by measuring query duration with and without the option enabled. Any query with more than 24 parameters may show lower overall query duration. Queries with parameter counts lower than 24 are unlikely to show a difference.

> [!NOTE]
If the option is enabled and a parameter with Direction Output or InputOutput is present in the Parameters collection an InvalidOperationException will be thrown when the command is executed.

]]>
</format>
      </remarks>
    </EnableOptimizedParameterBinding>
		<EndExecuteNonQuery name="IAsyncResult">
			<param name="asyncResult">
				The
				<see cref="T:System.IAsyncResult" />
				returned by the call to
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" />
				.
			</param>
			<summary>
				Finishes asynchronous execution of a Transact-SQL statement.
			</summary>
			<returns>
				The number of rows affected (the same behavior as
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery" />
				).
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When you call <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery> to execute a Transact-SQL statement, you must call <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the <xref:System.IAsyncResult> instance returned by the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery> method. If a callback procedure was specified in the call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery>, this method must be called.

## Examples
For examples demonstrating the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery%2A> method, see <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery>.
]]></format>
			</remarks>
			<exception cref="T:System.ArgumentException">
				<paramref name="asyncResult" />
				parameter is null (
				<see langword="Nothing" />
				in Microsoft Visual Basic)
			</exception>
			<exception cref="T:System.InvalidOperationException">
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" />
				was called more than once for a single command execution, or the method was mismatched against its execution method (for example, the code called
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" />
				to complete execution of a call to
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				The amount of time specified in
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" />
				elapsed and the asynchronous operation specified with
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" />
				is not complete.
				
				-or-
			
				In some situations,
				<see cref="T:System.IAsyncResult" />
				can be set to
				<see langword="IsCompleted" />
				incorrectly. If this occurs and
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" />
				is called, EndExecuteNonQuery could raise a SqlException error if the amount of time specified in
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" />
				elapsed and the asynchronous operation specified with
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" />
				is not complete. To correct this situation, you should either increase the value of CommandTimeout or reduce the work being done by the asynchronous operation.
			</exception>
		</EndExecuteNonQuery>
		<EndExecuteNonQueryAsync name="IAsyncResult">
			<summary>
				To be added.
			</summary>
			<remarks>
				To be added.
			</remarks>
		</EndExecuteNonQueryAsync>
		<EndExecuteReader name="IAsyncResult2">
			<param name="asyncResult">
				The
				<see cref="T:System.IAsyncResult" />
				returned by the call to
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" />
				.
			</param>
			<summary>
				Finishes asynchronous execution of a Transact-SQL statement, returning the requested
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				.
			</summary>
			<returns>
				A
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				object that can be used to retrieve the requested rows.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When you call <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to execute a Transact-SQL statement, you must call <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the <xref:System.IAsyncResult> instance returned by the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> method. If a callback procedure was specified in the call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A>, this method must be called.


## Examples
For examples demonstrating the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader%2A> method, see <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A>.
]]></format>
			</remarks>
			<exception cref="T:System.ArgumentException">
				<paramref name="asyncResult" />
				parameter is null (
				<see langword="Nothing" />
				in Microsoft Visual Basic)
			</exception>
			<exception cref="T:System.InvalidOperationException">
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" />
				was called more than once for a single command execution, or the method was mismatched against its execution method (for example, the code called
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" />
				to complete execution of a call to
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" />
				.
			</exception>
		</EndExecuteReader>
		<EndExecuteXmlReader name="IAsyncResult">
			<param name="asyncResult">
				The
				<see cref="T:System.IAsyncResult" />
				returned by the call to
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" />
				.
			</param>
			<summary>
				Finishes asynchronous execution of a Transact-SQL statement, returning the requested data as XML.
			</summary>
			<returns>
				An
				<see cref="T:System.Xml.XmlReader" />
				object that can be used to fetch the resulting XML data.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When you call <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to execute a Transact-SQL statement, you must call <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the <xref:System.IAsyncResult> instance returned by the <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> method. If a callback procedure was specified in the call to <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A>, this method must be called.

## Examples
For examples demonstrating the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader%2A> method, see <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A>.
]]></format>
			</remarks>
			<exception cref="T:System.ArgumentException">
				<paramref name="asyncResult" />
				parameter is null (
				<see langword="Nothing" />
				in Microsoft Visual Basic)
			</exception>
			<exception cref="T:System.InvalidOperationException">
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" />
				was called more than once for a single command execution, or the method was mismatched against its execution method (for example, the code called
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" />
				to complete execution of a call to
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" />
				.
			</exception>
		</EndExecuteXmlReader>
		<ExecuteDbDataReader name="CommandBehavior">
			<param name="behavior">
				To be added.
			</param>
			<summary>
				To be added.
			</summary>
			<returns>
				To be added.
			</returns>
			<remarks>
				To be added.
			</remarks>
		</ExecuteDbDataReader>
		<ExecuteDbDataReaderAsync>
			<param name="behavior">
				To be added.
			</param>
			<param name="cancellationToken">
				To be added.
			</param>
			<summary>
				To be added.
			</summary>
			<returns>
				To be added.
			</returns>
			<remarks>
				To be added.
			</remarks>
		</ExecuteDbDataReaderAsync>
		<ExecuteNonQuery name="default">
			<summary>
				Executes a Transact-SQL statement against the connection and returns the number of rows affected.
			</summary>
			<returns>
				The number of rows affected.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
You can use the <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery%2A> to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a <xref:System.Data.DataSet> by executing UPDATE, INSERT, or DELETE statements.

Although the <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery%2A> returns no rows, any output parameters or return values mapped to parameters are populated with data.

For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1.
When a trigger exists on a table being inserted or updated, the return value includes the number of rows affected by both the insert or update operation and the number of rows affected by the trigger or triggers.
When SET NOCOUNT ON is set on the connection (before or as part of executing the command, or as part of a trigger initiated by the execution of the command) the rows affected by individual statements stop contributing to the count of rows affected that is returned by this method.
If no statements are detected that contribute to the count, the return value is -1. If a rollback occurs, the return value is also -1.
## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and then executes it using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery%2A>. The example is passed a string that is a Transact-SQL statement (such as UPDATE, INSERT, or DELETE) and a string to use to connect to the data source.

[!code-csharp[SqlCommand_ExecuteNonQuery](~/../sqlclient/doc/samples/SqlCommand_ExecuteNonQuery.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteNonQuery>
		<ExecuteNonQueryAsync name="CancellationToken">
			<param name="cancellationToken">
				The cancellation instruction.
			</param>
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery" />
				, which executes a Transact-SQL statement against the connection and returns the number of rows affected. The cancellation token can be used to request that the operation be abandoned before the command timeout elapses.  Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).

> [!NOTE]
>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.


]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQueryAsync(System.Threading.CancellationToken)" />
				more than once for the same instance before task completion.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteNonQueryAsync>
		<ExecuteReader name="default">
			<summary>
				Sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				and builds a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				.
			</summary>
			<returns>
				A
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				object.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A> property is set to `StoredProcedure`, the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property should be set to the name of the stored procedure. The command executes this stored procedure when you call <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A>.

> [!NOTE]
> If a transaction is deadlocked, an exception may not be thrown until <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> is called.

The multiple active result set (MARS) feature allows for multiple actions using the same connection.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.


## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand>, and then executes it by passing a string that is a Transact-SQL SELECT statement, and a string to use to connect to the data source.

[!code-csharp[SqlCommand_ExecuteReader](~/../sqlclient/doc/samples/SqlCommand_ExecuteReader.cs)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The current state of the connection is closed.
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" />
				requires an open
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteReader>
		<ExecuteReader name="CommandBehavior">
			<param name="behavior">
				One of the
				<see cref="T:System.Data.CommandBehavior" />
				values.
			</param>
			<summary>
				Sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				, and builds a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				using one of the
				<see cref="T:System.Data.CommandBehavior" />
				values.
			</summary>
			<returns>
				A
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				object.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
When the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A> property is set to `StoredProcedure`, the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property should be set to the name of the stored procedure. The command executes this stored procedure when you call <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A>.

> [!NOTE]
> Use <xref:System.Data.CommandBehavior.SequentialAccess> to retrieve large values and binary data. Otherwise, an <xref:System.OutOfMemoryException> might occur and the connection will be closed.

The multiple active result set (MARS) feature allows for multiple actions using the same connection.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand>, and then executes it by passing a string that is a Transact-SQL SELECT statement, and a string to use to connect to the data source. <xref:System.Data.CommandBehavior> is set to <xref:System.Data.CommandBehavior.CloseConnection>.

[!code-csharp[SqlCommand_ExecuteReader2](~/../sqlclient/doc/samples/SqlCommand_ExecuteReader2.cs#1)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteReader>
		<ExecuteReaderAsync name="default">
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" />
				, which sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				and builds a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				. Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).

> [!NOTE]
>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.

]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.ArgumentException">
				An invalid
				<see cref="T:System.Data.CommandBehavior" />
				value.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync" />
				more than once for the same instance before task completion.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteReaderAsync>
		<ExecuteReaderAsync name="CommandBehavior">
			<param name="behavior">
				Options for statement execution and data retrieval.  When is set to
				<see langword="Default" />
				,
				<see cref="M:Microsoft.Data.SqlClient.SqlDataReader.ReadAsync(System.Threading.CancellationToken)" />
				reads the entire row before returning a complete Task.
			</param>
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader(System.Data.CommandBehavior)" />
				, which sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				, and builds a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				. Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.ArgumentException">
				An invalid
				<see cref="T:System.Data.CommandBehavior" />
				value.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync(System.Data.CommandBehavior)" />
				more than once for the same instance before task completion.
				
				-or-
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteReaderAsync>
		<ExecuteReaderAsync name="CancellationToken">
			<param name="cancellationToken">
				The cancellation instruction.
			</param>
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" />
				, which sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				and builds a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				.
				
				The cancellation token can be used to request that the operation be abandoned before the command timeout elapses.  Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown">
					<![CDATA[
					## Remarks
					For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
					]]>
				</format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.ArgumentException">
				An invalid
				<see cref="T:System.Data.CommandBehavior" />
				value.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync(System.Data.CommandBehavior,System.Threading.CancellationToken)" />
				more than once for the same instance before task completion.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteReaderAsync>
		<ExecuteReaderAsync name="commandBehaviorAndCancellationToken">
			<param name="behavior">
				Options for statement execution and data retrieval.  When is set to
				<see langword="Default" />
				,
				<see cref="M:Microsoft.Data.SqlClient.SqlDataReader.ReadAsync(System.Threading.CancellationToken)" />
				reads the entire row before returning a complete Task.
			</param>
			<param name="cancellationToken">
				The cancellation instruction.
			</param>
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader(System.Data.CommandBehavior)" />
				, which sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				, and builds a
				<see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />
				The cancellation token can be used to request that the operation be abandoned before the command timeout elapses.  Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[
				
## Remarks
For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.ArgumentException">
				An invalid
				<see cref="T:System.Data.CommandBehavior" />
				value.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync(System.Data.CommandBehavior,System.Threading.CancellationToken)" />
				more than once for the same instance before task completion.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteReaderAsync>
		<ExecuteScalar>
			<summary>
				Executes the query, and returns the first column of the first row in the result set returned by the query. Additional columns or rows are ignored.
			</summary>
			<returns>
				The first column of the first row in the result set, or a null reference (
				<see langword="Nothing" />
				in Visual Basic) if the result set is empty. Returns a maximum of 2033 characters.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
Use the <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar%2A> method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> method, and then performing the operations that you need to generate the single value using the data returned by a <xref:Microsoft.Data.SqlClient.SqlDataReader>.

A typical <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar%2A> query can be formatted as in the following C# example:

```csharp
cmd.CommandText = "SELECT COUNT(*) FROM dbo.region";
Int32 count = (Int32) cmd.ExecuteScalar();
```

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and then executes it using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar%2A>. The example is passed a string representing a new value to be inserted into a table, and a string to use to connect to the data source. The function returns the new **Identity** column value if a new row was inserted, 0 on failure.

[!code-csharp[SqlCommand.ExecuteScalar#1](~/../sqlclient/doc/samples/SqlCommand_ExecuteScalar.cs#1)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteScalar>
		<ExecuteScalarAsync name="CancellationToken">
			<param name="cancellationToken">
				The cancellation instruction.
			</param>
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar" />
				, which executes the query asynchronously and returns the first column of the first row in the result set returned by the query. Additional columns or rows are ignored.
				
				The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).

> [!NOTE]
>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.

]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalarAsync(System.Threading.CancellationToken)" />
				more than once for the same instance before task completion.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteScalarAsync>
		<ExecuteXmlReader name="default">
			<summary>
				Sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				and builds an
				<see cref="T:System.Xml.XmlReader" />
				object.
			</summary>
			<returns>
				An
				<see cref="T:System.Xml.XmlReader" />
				object.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The **XmlReader** returned by this method does not support asynchronous operations.
The <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, <xref:Microsoft.Data.SqlClient.SqlCommand.CommandText%2A> can also specify a statement that returns `ntext` or `nvarchar` data that contains valid XML, or the contents of a column defined with the `xml` data type.

A typical <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> query can be formatted as in the following Microsoft Visual C# example:

```csharp
SqlCommand command = new SqlCommand("SELECT * FROM dbo.Customers FOR XML AUTO, XMLDATA", SqlConn);
```

This method can also be used to retrieve a single-row, single-column result set that contains XML data. In this case, if more than one row is returned, the <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> method attaches the <xref:System.Xml.XmlReader> to the value on the first row, and discards the rest of the result set.

The multiple active result set (MARS) feature allows for multiple actions using the same connection.

If you use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader%2A> to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> or <xref:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader%2A> to read FOR XML queries.

## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and then executes it using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A>. The example is passed a string that is a Transact-SQL FOR XML SELECT statement, and a string to use to connect to the data source.

[!code-csharp[SqlCommand_ExecuteXmlReader#1](~/../sqlclient/doc/samples/SqlCommand_ExecuteXmlReader.cs#1)]
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.InvalidOperationException">
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteXmlReader>
		<ExecuteXmlReaderAsync name="default">
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" />
				, which sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				and builds an
				<see cref="T:System.Xml.XmlReader" />
				object.
				
				Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The **XmlReader** returned by this method does not support asynchronous operations.
For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).

> [!NOTE]
>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.

]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalarAsync(System.Threading.CancellationToken)" />
				more than once for the same instance before task completion.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteXmlReaderAsync>
		<ExecuteXmlReaderAsync name="CancellationToken">
			<param name="cancellationToken">
				The cancellation instruction.
			</param>
			<summary>
				An asynchronous version of
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" />
				, which sends the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" />
				to the
				<see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" />
				and builds an
				<see cref="T:System.Xml.XmlReader" />
				object.
				
				The cancellation token can be used to request that the operation be abandoned before the command timeout elapses.  Exceptions will be reported via the returned Task object.
			</summary>
			<returns>
				A task representing the asynchronous operation.
			</returns>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The **XmlReader** returned by this method does not support asynchronous operations.
For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
]]></format>
			</remarks>
			<exception cref="T:System.InvalidCastException">
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Binary** or **VarBinary** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.Stream" />
				. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Char**, **NChar**, **NVarChar**, **VarChar**, or  **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.IO.TextReader" />
				.
				
				-or-
				
				A
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" />
				other than **Xml** was used when
				<see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />
				was set to
				<see cref="T:System.Xml.XmlReader" />
				.
			</exception>
			<exception cref="T:System.InvalidOperationException">
				Calling
				<see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalarAsync(System.Threading.CancellationToken)" />
				more than once for the same instance before task completion.
				
				-or-
				
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlConnection" />
				closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:Microsoft.Data.SqlClient.SqlException">
				SQL Server returned an error while executing the command text.
				
				-or-
				
				A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.IO.IOException">
				An error occurred in a
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
			<exception cref="T:System.ObjectDisposedException">
				The
				<see cref="T:System.IO.Stream" />
				,
				<see cref="T:System.Xml.XmlReader" />
				or
				<see cref="T:System.IO.TextReader" />
				object was closed during a streaming operation.  For more information about streaming, see [SqlClient Streaming Support](/sql/connect/ado-net/sqlclient-streaming-support).
			</exception>
		</ExecuteXmlReaderAsync>
		<Notification>
			<summary>
				Gets or sets a value that specifies the
				<see cref="T:Microsoft.Data.Sql.SqlNotificationRequest" />
				object bound to this command.
			</summary>
			<value>
				When set to null (default), no notification should be requested.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
You must set the value for this property before the command is executed for it to take effect.
]]></format>
			</remarks>
		</Notification>
		<RegisterColumnEncryptionKeyStoreProvidersOnCommand>
			<param name="customProviders">Dictionary of custom column encryption key providers</param>
			<summary>Registers the encryption key store providers on the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> instance. If this function has been called, any providers registered using the <see cref="M:Microsoft.Data.SqlClient.SqlConnection.RegisterColumnEncryptionKeyStoreProviders(System.Collections.Generic.IDictionary{System.String,Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider})" /> or
			<see cref="M:Microsoft.Data.SqlClient.SqlConnection.RegisterColumnEncryptionKeyStoreProvidersOnConnection(System.Collections.Generic.IDictionary{System.String,Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider})" /> methods will be ignored. This function can be called more than once. This does shallow copying of the dictionary so that the app cannot alter the custom provider list once it has been set.</summary>
			<exception cref="T:System.ArgumentNullException">
					A null dictionary was provided.

					-or-

					A string key in the dictionary was null or empty.

					-or-

					A <see cref="T:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider" /> value in the dictionary was null.
			</exception>
			<exception cref="T:System.ArgumentException">
				A string key in the dictionary started with "MSSQL_". This prefix is reserved for system providers.
			</exception>
             <remarks>
              <format type="text/markdown"><![CDATA[
## Remarks
Custom master key store providers can be registered with the driver at three different layers. The precedence of the three registrations is as follows:

- The per-command registration will be checked if it is not empty.
- If the per-command registration is empty, the per-connection registration will be checked if it is not empty.
- If the per-connection registration is empty, the global registration will be checked.

Once any key store provider is found at a registration level, the driver will **NOT** fall back to the other registrations to search for a provider. If providers are registered but the proper provider is not found at a level, an exception will be thrown containing only the registered providers in the registration that was checked.

The built-in column master key store providers that are available for the Windows Certificate Store, CNG Store and CSP are pre-registered.

This does shallow copying of the dictionary so that the app cannot alter the custom provider list once it has been set.
]]></format>
			</remarks>
		</RegisterColumnEncryptionKeyStoreProvidersOnCommand>
		<RetryLogicProvider>
			<summary>
				Gets or sets a value that specifies the
				<see cref="T:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider" />
				object bound to this command.
			</summary>
			<value>
				When set to null (default), the default non-retriable provider will be used.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
You must set the value for this property before the command is executed for it to take effect.  

To apply the retry logic, do the following steps before executing the command:
1. Define the configuration parameters by using <xref:Microsoft.Data.SqlClient.SqlRetryLogicOption> type.
2. Create a <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider> by using one of the following static methods of the <xref:Microsoft.Data.SqlClient.SqlConfigurableRetryFactory> class:  
	- <xref:Microsoft.Data.SqlClient.SqlConfigurableRetryFactory.CreateFixedRetryProvider%2A>  
	- <xref:Microsoft.Data.SqlClient.SqlConfigurableRetryFactory.CreateIncrementalRetryProvider%2A>  
	- <xref:Microsoft.Data.SqlClient.SqlConfigurableRetryFactory.CreateExponentialRetryProvider%2A>  
	- <xref:Microsoft.Data.SqlClient.SqlConfigurableRetryFactory.CreateNoneRetryProvider%2A>  
3. Assign the <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider> object to the `RetryLogicProvider` property.

> [!NOTE]
> Detecting retriable exceptions is a vital part of the retry pattern. Before applying retry logic, it is important to investigate exceptions and choose a retry provider that best fits your scenario. First, log your exceptions and find transient faults.  

> [!NOTE]
> The command **timeout** restarts for each execution of a command within the retry logic and after applying the retry time delay. There is no timing overlap between these two actions.

> [!NOTE]
> The default retry logic provider is not enabled unless it is configured in an application configuration file. For more information, see [Configurable retry logic configuration file](/sql/connect/ado-net/configurable-retry-logic-config-file-sqlclient).

> [!CAUTION]
> A command with <xref:System.Data.CommandBehavior.CloseConnection?displayProperty=nameWithType> isn't compatible with the built-in retry logic. The underlying connection is immediately closed after the first execution attempt and is no longer available for subsequent retries.

## Example
The following sample creates a database and establishes an active connection to it. While the database has an active connection, it tries to drop it with a new <xref:Microsoft.Data.SqlClient.SqlConnection> and a <xref:Microsoft.Data.SqlClient.SqlCommand> that uses a <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider>. You should kill the active connection through the database to unblock the second command before exceeding the number of retries.  
The blocking connection simulates a situation like a command still running in the database and unlikely to finish.  

[!code-csharp[SqlConfigurableRetryLogic_SqlCommand#1](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_SqlCommand.cs#1)]

### How to use with synchronous commands

[!code-csharp[SqlConfigurableRetryLogic_SqlCommand#2](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_SqlCommand.cs#2)]

### How to use with asynchoronous commands

[!code-csharp[SqlConfigurableRetryLogic_SqlCommand#3](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_SqlCommand.cs#3)]

### How to use with legacy asynchronous commands
Besides assigning the provider to the command and executing the command, it's possible to run it directly using the following <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider> methods:  
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Execute%60%601(System.Object,System.Func{%60%600})>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.ExecuteAsync(System.Object,System.Func{System.Threading.Tasks.Task},System.Threading.CancellationToken)>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.ExecuteAsync%60%601(System.Object,System.Func{System.Threading.Tasks.Task{%60%600}},System.Threading.CancellationToken)>

[!code-csharp[SqlConfigurableRetryLogic_SqlCommand#4](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_SqlCommand.cs#4)]

> [!NOTE]
> The Asynchronous Programming Model (APM) is a legacy pattern that uses a pair of methods starting with `Begin` and `End`, and an interface called `IAsyncResult`. It's not recommended to use this pattern in new applications. These methods are for backwards compatibility.  

]]></format>
			</remarks>
		</RetryLogicProvider>
		<NotificationAutoEnlist>
			<summary>
				Gets or sets a value indicating whether the application should automatically receive query notifications from a common
				<see cref="T:Microsoft.Data.SqlClient.SqlDependency" />
				object.
			</summary>
			<value>
				<see langword="true" />
				if the application should automatically receive query notifications; otherwise
				<see langword="false" />
				. The default value is
				<see langword="true" />
				.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
This feature is used in ASP.NET applications to receive notifications for all commands executed in an ASP page against SQL Server. This enables ASP.NET to cache the page until the queries used to render the page would produce a different result. Automatic enlistment.

This property applies only to versions of SQL Server that support query notifications. For earlier versions, setting this property to `true` has no effect on the application.
]]></format>
			</remarks>
		</NotificationAutoEnlist>
		<Parameters>
			<summary>
				Gets the
				<see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection" />
				.
			</summary>
			<value>
				The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a SQL Statement or a stored procedure called by a command of `CommandType.Text`. In this case, named parameters must be used. For example:

SELECT * FROM Customers WHERE CustomerID = @CustomerID

> [!NOTE]
> If the parameters in the collection do not match the requirements of the query to be executed, an error may result.

For more information, see [Configuring parameters](/sql/connect/ado-net/configure-parameters).

## Examples
The following example demonstrates how to create a <xref:Microsoft.Data.SqlClient.SqlCommand> and add parameters to the <xref:Microsoft.Data.SqlClient.SqlParameterCollection>.

[!code-csharp[SqlParameterCollection.AddWithValue#1](~/../sqlclient/doc/samples/SqlParameterCollection_AddWithValue.cs#1)]
]]></format>
			</remarks>
		</Parameters>
		<Prepare>
			<summary>
				Creates a prepared version of the command on an instance of SQL Server.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
If <xref:Microsoft.Data.SqlClient.SqlCommand.CommandType%2A> is set to `StoredProcedure`, the call to <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A> should succeed, although it may cause a no-op.

Before you call <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A>, specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A> property to the maximum size needed. <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A> returns an error if these conditions are not met.

> [!NOTE]
> If the database context is changed by executing the Transact-SQL `USE <database>` statement, or by calling the <xref:Microsoft.Data.SqlClient.SqlConnection.ChangeDatabase%2A> method, then <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A> must be called a second time.

If you call an `Execute` method after calling <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A>, any parameter value that is larger than the value specified by the <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A> property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned.

Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A>.

Prior to Visual Studio 2010, <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A> threw an exception.  Beginning in Visual Studio 2010, this method does not throw an exception.

## Examples
The following example demonstrates the use of the <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A> method.

[!code-csharp[SqlCommand.Prepare#1](~/../sqlclient/doc/samples/SqlCommand_Prepare.cs#1)]
]]></format>
			</remarks>
		</Prepare>
		<ResetCommandTimeout>
			<summary> Resets the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property to its default value.
			</summary>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The default value of the <xref:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout%2A> is 30 seconds.
]]></format>
			</remarks>
		</ResetCommandTimeout>
		<StatementCompleted>
			<summary>
				Occurs when the execution of a Transact-SQL statement completes.
			</summary>
			<remarks>
				To be added.
			</remarks>
		</StatementCompleted>
		<CreateParameter>
			<summary>
				Creates a new instance of a <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> object.
			</summary>
			<returns>
				A <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> object.
			</returns>
			<remarks>
				To be added.
			</remarks>
		</CreateParameter>
		<Transaction>
			<summary>
				Gets or sets the
				<see cref="T:Microsoft.Data.SqlClient.SqlTransaction" />
				within which the
				<see cref="T:Microsoft.Data.SqlClient.SqlCommand" />
				executes.
			</summary>
			<value>
				The
				<see cref="T:Microsoft.Data.SqlClient.SqlTransaction" />
				. The default value is
				<see langword="null" />
				.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
You cannot set the <xref:Microsoft.Data.SqlClient.SqlCommand.Transaction%2A> property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to a <xref:Microsoft.Data.SqlClient.SqlTransaction> object that is not connected to the same <xref:Microsoft.Data.SqlClient.SqlConnection> as the <xref:Microsoft.Data.SqlClient.SqlCommand> object, an exception is thrown the next time that you attempt to execute a statement.
]]></format>
			</remarks>
		</Transaction>
		<UpdatedRowSource>
			<summary>
				Gets or sets how command results are applied to the <see cref="T:System.Data.DataRow" /> when used by the **Update** method of the <see cref="T:System.Data.Common.DbDataAdapter" />.
			</summary>
			<value>
				One of the <see cref="T:System.Data.UpdateRowSource" /> values.
			</value>
			<remarks>
				<format type="text/markdown"><![CDATA[

## Remarks
The default <xref:System.Data.UpdateRowSource> value is **Both** unless the command is automatically generated (as in the case of the <xref:Microsoft.Data.SqlClient.SqlCommandBuilder>), in which case the default is **None**.

For more information about using the **UpdatedRowSource** property, see [DataAdapter Parameters](/sql/connect/ado-net/dataadapter-parameters).
]]></format>
			</remarks>
		</UpdatedRowSource>
	</members>
</docs>