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>
        <para>
          The base constructor initializes all fields to their default values. The following table shows initial property values for an instance of <see cref="T:Microsoft.Data.SqlClient.SqlCommand" />.
        </para>
        <para>
          <list type="table">
            <listheader>
              <term>Properties</term>
              <description>Initial value</description>
            </listheader>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /></term>
              <description>empty string ("")</description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /></term>
              <description>30</description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /></term>
              <description><see cref="F:System.Data.CommandType.Text" /></description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" /></term>
              <description><see langword="null" /></description>
            </item>
          </list>
        </para>
        <para>
          You can change the value for any of these properties through a separate call to the property.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and sets the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
        <!-- IDbCommand_CommandTimeout -->
        <code language="c#">
          using System;
          using System.Xml;
          using System.Data;
          using System.Data.Common;
          using System.Windows.Forms;
          using Microsoft.Data.SqlClient;

          public class Form1 : Form
          {
              protected DataSet DataSet1;
              protected DataGrid dataGrid1;

              public void CreateSqlCommand()
              {
                  SqlCommand command = new SqlCommand();
                  command.CommandTimeout = 15;
                  command.CommandType = CommandType.Text;
              }
          }
        </code>
      </example>
    </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>
        <para>
          When an instance of <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> is created, the following read/write properties are set to initial values.
        </para>
        <para>
          <list type="table">
            <listheader>
              <term>Properties</term>
              <description>Initial value</description>
            </listheader>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /></term>
              <description><paramref name="cmdText" /></description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /></term>
              <description>30</description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /></term>
              <description><see cref="F:System.Data.CommandType.Text" /></description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" /></term>
              <description><see langword="null" /></description>
            </item>
          </list>
        </para>
        <para>
          You can change the value for any of these properties through a separate call to the property.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" />, passing in the command text.
        </para>
        <!-- SqlCommand_SqlCommand1 -->
        <code language="c#">
          using System;
          using System.Xml;
          using System.Data;
          using System.Data.Common;
          using System.Windows.Forms;
          using Microsoft.Data.SqlClient;

          public class Form1 : Form
          {
              protected DataSet DataSet1;
              protected DataGrid dataGrid1;

              public void CreateCommand()
              {
                  string queryString = "SELECT * FROM Categories ORDER BY CategoryID";
                  SqlCommand command = new SqlCommand(queryString);
                  command.CommandTimeout = 15;
                  command.CommandType = CommandType.Text;
              }
          }
        </code>
      </example>
    </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>
        <para>
          The following table shows initial property values for an instance of <see cref="T:Microsoft.Data.SqlClient.SqlCommand" />.
        </para>
        <para>
          <list type="table">
            <listheader>
              <term>Properties</term>
              <description>Initial value</description>
            </listheader>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /></term>
              <description><c>cmdText</c></description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /></term>
              <description>30</description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /></term>
              <description><see cref="F:System.Data.CommandType.Text" /></description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" /></term>
              <description>
                A new <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> that is the value for the <paramref name="connection" /> parameter.
              </description>
            </item>
          </list>
        </para>
        <para>
          You can change the value for any of these parameters by setting the related property.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and sets some of its properties.
        </para>
        <!-- SqlCommand_SqlCommand2 -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;

          namespace SqlCommandCS
          {
              class Program
              {
                  static void Main()
                  {
                      string str = "Data Source=(local);Initial Catalog=Northwind;"
                          + "Integrated Security=SSPI";
                      string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
                      CreateCommand(qs, str);

                  }

                  private static void CreateCommand(string queryString, string connectionString)
                  {
                      using (SqlConnection connection = new SqlConnection(connectionString))
                      {
                          SqlCommand command = new SqlCommand(queryString, connection);
                          connection.Open();
                          SqlDataReader reader = command.ExecuteReader();
                          while (reader.Read())
                          {
                              Console.WriteLine(String.Format("{0}, {1}", reader[0], reader[1]));
                          }
                      }
                  }
              }
          }
        </code>
      </example>
    </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>
        <para>
          The following table shows initial property values for an instance of <see cref="T:Microsoft.Data.SqlClient.SqlCommand" />.
        </para>
        <para>
          <list type="table">
            <listheader>
              <term>Properties</term>
              <description>Initial value</description>
            </listheader>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /></term>
              <description><c>cmdText</c></description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /></term>
              <description>30</description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /></term>
              <description><see cref="F:System.Data.CommandType.Text" /></description>
            </item>
            <item>
              <term><see cref="P:Microsoft.Data.SqlClient.SqlCommand.Connection" /></term>
              <description>
                A new <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> that is the value for the <paramref name="connection" /> parameter.
              </description>
            </item>
          </list>
        </para>
        <para>
          You can change the value for any of these parameters by setting the related property.
        </para>
      </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 <see href='https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine'>Always Encrypted</see>.
      </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>
    </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> method to finish the operation. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> before the command's execution is completed causes the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          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.
        </para>
        <para>
          Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the <see cref="P:System.IAsyncResult.IsCompleted" /> property of the <see cref="T:System.IAsyncResult" /> returned by the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> method; or wait for the completion of one or more commands using the <see cref="P:System.IAsyncResult.AsyncWaitHandle" /> property of the returned <see cref="T:System.IAsyncResult" />.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          The following console application creates updates data within the <b>AdventureWorks</b> sample database, doing its work asynchronously. In order to emulate a long-running process, this example inserts a <c>WAITFOR</c> 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.
        </para>
        <!-- SqlCommand_BeginExecuteNonQuery -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          class Class1
          {
              static void Main()
              {
                  // This is a simple example that demonstrates the usage of the 
                  // BeginExecuteNonQuery functionality.
                  // The WAITFOR statement simply adds enough time to prove the 
                  // asynchronous nature of the command.
          
                  string commandText =
                      "UPDATE Production.Product SET ReorderPoint = ReorderPoint + 1 " +
                      "WHERE ReorderPoint Is Not Null;" +
                      "WAITFOR DELAY '0:0:3';" +
                      "UPDATE Production.Product SET ReorderPoint = ReorderPoint - 1 " +
                      "WHERE ReorderPoint Is Not Null";
          
                  RunCommandAsynchronously(commandText, GetConnectionString());
          
                  Console.WriteLine("Press ENTER to continue.");
                  Console.ReadLine();
              }
          
              private static void RunCommandAsynchronously(string commandText, string connectionString)
              {
                  // Given command text and connection string, asynchronously execute
                  // the specified command against the connection. For this example,
                  // the code displays an indicator as it is working, verifying the 
                  // asynchronous behavior. 
                  using (SqlConnection connection = new SqlConnection(connectionString))
                  {
                      try
                      {
                          int count = 0;
                          SqlCommand command = new SqlCommand(commandText, connection);
                          connection.Open();
          
                          IAsyncResult result = command.BeginExecuteNonQuery();
                          while (!result.IsCompleted)
                          {
                              Console.WriteLine("Waiting ({0})", count++);
                              // Wait for 1/10 second, so the counter
                              // does not consume all available resources 
                              // on the main thread.
                              System.Threading.Thread.Sleep(100);
                          }
                        
                          Console.WriteLine("Command complete. Affected {0} rows.",
                              command.EndExecuteNonQuery(result));
                      }
                      catch (SqlException ex)
                      {
                          Console.WriteLine("Error ({0}): {1}", ex.Number, ex.Message);
                      }
                      catch (InvalidOperationException ex)
                      {
                          Console.WriteLine("Error: {0}", ex.Message);
                      }
                      catch (Exception ex)
                      {
                          // You might want to pass these errors
                          // back out to the caller.
                          Console.WriteLine("Error: {0}", ex.Message);
                      }
                  }
              }
          
              private static string GetConnectionString()
              {
                  // To avoid storing the connection string in your code,            
                  // you can retrieve it from a configuration file. 
                  return "Data Source=(local);Integrated Security=SSPI;" +
                         "Initial Catalog=AdventureWorks";
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            Any error that occurred while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> method to finish the operation. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> before the command's execution is completed causes the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          The <paramref name="callback" /> parameter lets you specify an <see cref="T:System.AsyncCallback" /> delegate that is called when the statement has completed. You can call the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the <paramref name="stateObject" /> parameter, and your callback procedure can retrieve this information using the <see cref="P:System.IAsyncResult.AsyncState" /> property.
        </para>
        <para>
          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.
        </para>
        <para>
          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.
        </para>
        <para>
          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.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          The following Windows application demonstrates the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> method, executing a Transact-SQL statement that includes a delay of several seconds (emulating a long-running command).
        </para>
        <para>
          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.
        </para>
        <para>
          To set up this example, create a new Windows application. Put a <see cref="T:System.Windows.Forms.Button" /> control and a <see cref="T: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.
        </para>
        <!-- SqlCommand_BeginExecuteNonQueryForm -->
        <code language="c#">
          using System;
          using System.Collections.Generic;
          using System.ComponentModel;
          using System.Data;
          using System.Drawing;
          using System.Text;
          using System.Windows.Forms;
          using Microsoft.Data.SqlClient;
          
          namespace Microsoft.AdoDotNet.CodeSamples
          {
              public partial class Form1 : Form
              {
                  public Form1()
                  {
                      InitializeComponent();
                  }
          
                  // Hook up the form's Load event handler (you can double-click on 
                  // the form's design surface in Visual Studio), and then add 
                  // this code to the form's class:
                  private void Form1_Load(object sender, EventArgs e)
                  {
                      this.button1.Click += new System.EventHandler(this.button1_Click);
                      this.FormClosing += new System.Windows.Forms.
                          FormClosingEventHandler(this.Form1_FormClosing);
                  }
          
                  // You need this delegate in order to display text from a thread
                  // other than the form's thread. See the HandleCallback
                  // procedure for more information.
                  // This same delegate matches both the DisplayStatus 
                  // and DisplayResults methods.
                  private delegate void DisplayInfoDelegate(string Text);
          
                  // This flag ensures that the user does not attempt
                  // to restart the command or close the form while the 
                  // asynchronous command is executing.
                  private bool isExecuting;
          
                  // This example maintains the connection object 
                  // externally, so that it is available for closing.
                  private SqlConnection connection;
          
                  private static string GetConnectionString()
                  {
                      // To avoid storing the connection string in your code,            
                      // you can retrieve it from a configuration file.
                      return "Data Source=(local);Integrated Security=true;" +
                             "Initial Catalog=AdventureWorks";
                  }
          
                  private void DisplayStatus(string Text)
                  {
                      this.label1.Text = Text;
                  }
          
                  private void DisplayResults(string Text)
                  {
                      this.label1.Text = Text;
                      DisplayStatus("Ready");
                  }
          
                  private void Form1_FormClosing(object sender, System.Windows.Forms.FormClosingEventArgs e)
                  {
                      if (isExecuting)
                      {
                          MessageBox.Show(this, "Cannot close the form until " +
                              "the pending asynchronous command has completed. Please wait...");
                          e.Cancel = true;
                      }
                  }
          
                  private void button1_Click(object sender, System.EventArgs e)
                  {
                      if (isExecuting)
                      {
                          MessageBox.Show(this,
                              "Already executing. Please wait until the current query " +
                              "has completed.");
                      }
                      else
                      {
                          SqlCommand command = null;
                          try
                          {
                              DisplayResults("");
                              DisplayStatus("Connecting...");
                              connection = new SqlConnection(GetConnectionString());
                              // To emulate a long-running query, wait for 
                              // a few seconds before working with the data.
                              // This command does not do much, but that's the point--
                              // it does not change your data, in the long run.
                              string commandText =
                                  "WAITFOR DELAY '0:0:05';" +
                                  "UPDATE Production.Product SET ReorderPoint = ReorderPoint + 1 " +
                                  "WHERE ReorderPoint Is Not Null;" +
                                  "UPDATE Production.Product SET ReorderPoint = ReorderPoint - 1 " +
                                  "WHERE ReorderPoint Is Not Null";
          
                              command = new SqlCommand(commandText, connection);
                              connection.Open();
          
                              DisplayStatus("Executing...");
                              isExecuting = true;
                              // Although it is not required that you pass the 
                              // SqlCommand object as the second parameter in the 
                              // BeginExecuteNonQuery call, doing so makes it easier
                              // to call EndExecuteNonQuery in the callback procedure.
                              AsyncCallback callback = new AsyncCallback(HandleCallback);
                              command.BeginExecuteNonQuery(callback, command);
          
                          }
                          catch (Exception ex)
                          {
                              isExecuting = false;
                              DisplayStatus(string.Format("Ready (last error: {0})", ex.Message));
                              if (connection != null)
                              {
                                  connection.Close();
                              }
                          }
                      }
                  }
          
                  private void HandleCallback(IAsyncResult result)
                  {
                      try
                      {
                          // Retrieve the original command object, passed
                          // to this procedure in the AsyncState property
                          // of the IAsyncResult parameter.
                          SqlCommand command = (SqlCommand)result.AsyncState;
                          int rowCount = command.EndExecuteNonQuery(result);
                          string rowText = " rows affected.";
                          if (rowCount == 1)
                          {
                              rowText = " row affected.";
                          }
                        
                          rowText = rowCount + rowText;
          
                          // You may not interact with the form and its contents
                          // from a different thread, and this callback procedure
                          // is all but guaranteed to be running from a different thread
                          // than the form. Therefore you cannot simply call code that 
                          // displays the results, like this:
                          // DisplayResults(rowText)
          
                          // Instead, you must call the procedure from the form's thread.
                          // One simple way to accomplish this is to call the Invoke
                          // method of the form, which calls the delegate you supply
                          // from the form's thread. 
                          DisplayInfoDelegate del = new DisplayInfoDelegate(DisplayResults);
                          this.Invoke(del, rowText);
          
                      }
                      catch (Exception ex)
                      {
                          // Because you are now running code in a separate thread, 
                          // if you do not handle the exception here, none of your other
                          // code catches the exception. Because none of 
                          // your code is on the call stack in this thread, there is nothing
                          // higher up the stack to catch the exception if you do not 
                          // handle it here. You can either log the exception or 
                          // invoke a delegate (as in the non-error case in this 
                          // example) to display the error on the form. In no case
                          // can you simply display the error without executing a delegate
                          // as in the try block here. 
          
                          // You can create the delegate instance as you 
                          // invoke it, like this:
                          this.Invoke(new DisplayInfoDelegate(DisplayStatus),
                              String.Format("Ready(last error: {0}", ex.Message));
                      }
                      finally
                      {
                          isExecuting = false;
                          if (connection != null)
                          {
                              connection.Close();
                          }
                      }
                  }
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            Any error that occurred while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method to finish the operation and retrieve the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> returned by the command. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> before the command's execution is completed causes the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          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 <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> may block if more data is required and the underlying network's read operation blocks.
        </para>
        <para>
          Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the <see cref="P:System.IAsyncResult.IsCompleted" /> property of the <see cref="T:System.IAsyncResult" /> returned by the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> method; or wait for the completion of one or more commands using the <see cref="P:System.IAsyncResult.AsyncWaitHandle" /> property of the returned <see cref="T:System.IAsyncResult" />.
        </para>
        <para>
          If you use <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to read FOR XML queries.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          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 <see cref="P:System.IAsyncResult.IsCompleted" /> property value. As soon as the process has completed, the code retrieves the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> and displays its contents.
        </para>
        <!-- SqlCommand_BeginExecuteReader -->
        <code language="c#">
          using System;
          using Microsoft.Data.SqlClient;

          class Class1
          {
              static void Main()
              {
                  // This is a simple example that demonstrates the usage of the
                  // BeginExecuteReader functionality
                  // The WAITFOR statement simply adds enough time to prove the
                  // asynchronous nature of the command.
                  string commandText =
                      "WAITFOR DELAY '00:00:03';" +
                      "SELECT LastName, FirstName FROM Person.Contact " +
                      "WHERE LastName LIKE 'M%'";

                  RunCommandAsynchronously(commandText, GetConnectionString());

                  Console.WriteLine("Press ENTER to continue.");
                  Console.ReadLine();
              }

              private static void RunCommandAsynchronously(
                  string commandText, string connectionString)
              {
                  // Given command text and connection string, asynchronously execute
                  // the specified command against the connection. For this example,
                  // the code displays an indicator as it is working, verifying the
                  // asynchronous behavior.
                  using (SqlConnection connection = new SqlConnection(connectionString))
                  {
                      try
                      {
                          SqlCommand command = new SqlCommand(commandText, connection);

                          connection.Open();
                          IAsyncResult result = command.BeginExecuteReader();

                          // Although it is not necessary, the following code
                          // displays a counter in the console window, indicating that
                          // the main thread is not blocked while awaiting the command
                          // results.
                          int count = 0;
                          while (!result.IsCompleted)
                          {
                              count += 1;
                              Console.WriteLine("Waiting ({0})", count);
                              // Wait for 1/10 second, so the counter
                              // does not consume all available resources
                              // on the main thread.
                              System.Threading.Thread.Sleep(100);
                          }

                          using (SqlDataReader reader = command.EndExecuteReader(result))
                          {
                              DisplayResults(reader);
                          }
                      }
                      catch (SqlException ex)
                      {
                          Console.WriteLine("Error ({0}): {1}", ex.Number, ex.Message);
                      }
                      catch (InvalidOperationException ex)
                      {
                          Console.WriteLine("Error: {0}", ex.Message);
                      }
                      catch (Exception ex)
                      {
                          // You might want to pass these errors
                          // back out to the caller.
                          Console.WriteLine("Error: {0}", ex.Message);
                      }
                  }
              }

              private static void DisplayResults(SqlDataReader reader)
              {
                  // Display the data within the reader.
                  while (reader.Read())
                  {
                      // Display all the columns. 
                      for (int i = 0; i &lt; reader.FieldCount; i++)
                      {
                          Console.Write("{0}\t", reader.GetValue(i));
                      }
                      Console.WriteLine();
                  }
              }

              private static string GetConnectionString()
              {
                  // To avoid storing the connection string in your code,            
                  // you can retrieve it from a configuration file. 

                  return "Data Source=(local);Integrated Security=true;" +
                      "Initial Catalog=AdventureWorks";
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            Any error that occurred while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method to finish the operation and retrieve the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> returned by the command. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> before the command's execution is completed causes the <see cref="M:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          The <c>behavior</c> parameter lets you specify options that control the behavior of the command and its connection. These values can be combined (using the programming language's <c>OR</c> operator); generally, developers use the <c>CommandBehavior.CloseConnection</c> value to make sure that the connection is closed by the runtime when the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed.
        </para>
        <para>
          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 <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> may block if more data is required and the underlying network's read operation blocks.
        </para>
        <para>
          Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the <see cref="P:System.IAsyncResult.IsCompleted" /> property of the <see cref="T:System.IAsyncResult" /> returned by the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> method; or wait for the completion of one or more commands using the <see cref="P:System.IAsyncResult.AsyncWaitHandle" /> property of the returned <see cref="T:System.IAsyncResult" />.
        </para>
        <para>
          If you use <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to read FOR XML queries.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          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 <see cref="P:System.IAsyncResult.IsCompleted" /> property value. Once the process has completed, the code retrieves the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> and displays its contents.
        </para>
        <para>
          This example also passes the <see cref="F:System.Data.CommandBehavior.CloseConnection" /> and <see cref="F:System.Data.CommandBehavior.SingleRow" /> values in the behavior parameter, causing the connection to be closed with the returned <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed, and to optimize for a single row result.
        </para>
        <!-- SqlCommand_BeginExecuteReaderAsyncSimple -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          class Class1
          {
              static void Main()
              {
                  // This example is not terribly useful, but it proves a point.
                  // The WAITFOR statement simply adds enough time to prove the 
                  // asynchronous nature of the command.
                  string commandText = "WAITFOR DELAY '00:00:03';" +
                      "SELECT ProductID, Name FROM Production.Product WHERE ListPrice &lt; 100";
          
                  RunCommandAsynchronously(commandText, GetConnectionString());
          
                  Console.WriteLine("Press ENTER to continue.");
                  Console.ReadLine();
              }
          
              private static void RunCommandAsynchronously(string commandText, string connectionString)
              {
                  // Given command text and connection string, asynchronously execute
                  // the specified command against the connection. For this example,
                  // the code displays an indicator as it is working, verifying the 
                  // asynchronous behavior. 
                  try
                  {
                      // The code does not need to handle closing the connection explicitly--
                      // the use of the CommandBehavior.CloseConnection option takes care
                      // of that for you. 
                      SqlConnection connection = new SqlConnection(connectionString);
                      SqlCommand command = new SqlCommand(commandText, connection);
          
                      connection.Open();
                      IAsyncResult result = command.BeginExecuteReader(CommandBehavior.CloseConnection);
          
                      // Although it is not necessary, the following code
                      // displays a counter in the console window, indicating that 
                      // the main thread is not blocked while awaiting the command 
                      // results.
                      int count = 0;
                      while (!result.IsCompleted)
                      {
                          Console.WriteLine("Waiting ({0})", count++);
                          // Wait for 1/10 second, so the counter
                          // does not consume all available resources 
                          // on the main thread.
                          System.Threading.Thread.Sleep(100);
                      }
          
                      using (SqlDataReader reader = command.EndExecuteReader(result))
                      {
                          DisplayResults(reader);
                      }
                  }
                  catch (SqlException ex)
                  {
                      Console.WriteLine("Error ({0}): {1}", ex.Number, ex.Message);
                  }
                  catch (InvalidOperationException ex)
                  {
                      Console.WriteLine("Error: {0}", ex.Message);
                  }
                  catch (Exception ex)
                  {
                      // You might want to pass these errors
                      // back out to the caller.
                      Console.WriteLine("Error: {0}", ex.Message);
                  }
              }
          
              private static void DisplayResults(SqlDataReader reader)
              {
                  // Display the data within the reader.
                  while (reader.Read())
                  {
                      // Display all the columns. 
                      for (int i = 0; i &lt; reader.FieldCount; i++)
                      {
                          Console.Write("{0}\t", reader.GetValue(i));
                      }
                    
                      Console.WriteLine();
                  }
              }
          
              private static string GetConnectionString()
              {
                  // To avoid storing the connection string in your code,            
                  // you can retrieve it from a configuration file. 
                  return "Data Source=(local);Integrated Security=true;" +
                         "Initial Catalog=AdventureWorks";
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            Any error that occurred while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method to finish the operation and retrieve the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> returned by the command. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> before the command's execution is completed cause the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          The <paramref name="callback" /> parameter lets you specify an <see cref="T:System.AsyncCallback" /> delegate that is called when the statement has completed. You can call the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the <paramref name="stateObject" /> parameter, and your callback procedure can retrieve this information using the <see cref="P:System.IAsyncResult.AsyncState" /> property.
        </para>
        <para>
          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 <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> may block if more data is required and the underlying network's read operation blocks.
        </para>
        <para>
          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.
        </para>
        <para>
          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.
        </para>
        <para>
          If you use <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to read FOR XML queries.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          The following Windows application demonstrates the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object as the <paramref name="stateObject" /> parameter; doing so makes it simple to retrieve the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object from within the callback procedure, so that the code can call the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method corresponding to the initial call to <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" />.
        </para>
        <para>
          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.
        </para>
        <para>
          To set up this example, create a new Windows application. Put a <see cref="T:System.Windows.Forms.Button" /> control, a <see cref="T:System.Windows.Forms.DataGridView" /> control, and a <see cref="T: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.
        </para>
        <!-- SqlCommand_BeginExecuteReaderAsync -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          class Class1
          {
              static void Main()
              {
                  // This example is not terribly useful, but it proves a point.
                  // The WAITFOR statement simply adds enough time to prove the 
                  // asynchronous nature of the command.
                  string commandText = "WAITFOR DELAY '00:00:03';" +
                      "SELECT ProductID, Name FROM Production.Product WHERE ListPrice &lt; 100";
          
                  RunCommandAsynchronously(commandText, GetConnectionString());
          
                  Console.WriteLine("Press ENTER to continue.");
                  Console.ReadLine();
              }
          
              private static void RunCommandAsynchronously(string commandText, string connectionString)
              {
                  // Given command text and connection string, asynchronously execute
                  // the specified command against the connection. For this example,
                  // the code displays an indicator as it is working, verifying the 
                  // asynchronous behavior. 
                  try
                  {
                      // The code does not need to handle closing the connection explicitly--
                      // the use of the CommandBehavior.CloseConnection option takes care
                      // of that for you. 
                      SqlConnection connection = new SqlConnection(connectionString);
                      SqlCommand command = new SqlCommand(commandText, connection);
          
                      connection.Open();
                      IAsyncResult result = command.BeginExecuteReader(CommandBehavior.CloseConnection);
          
                      // Although it is not necessary, the following code
                      // displays a counter in the console window, indicating that 
                      // the main thread is not blocked while awaiting the command 
                      // results.
                      int count = 0;
                      while (!result.IsCompleted)
                      {
                          Console.WriteLine("Waiting ({0})", count++);
                          // Wait for 1/10 second, so the counter
                          // does not consume all available resources 
                          // on the main thread.
                          System.Threading.Thread.Sleep(100);
                      }
          
                      using (SqlDataReader reader = command.EndExecuteReader(result))
                      {
                          DisplayResults(reader);
                      }
                  }
                  catch (SqlException ex)
                  {
                      Console.WriteLine("Error ({0}): {1}", ex.Number, ex.Message);
                  }
                  catch (InvalidOperationException ex)
                  {
                      Console.WriteLine("Error: {0}", ex.Message);
                  }
                  catch (Exception ex)
                  {
                      // You might want to pass these errors
                      // back out to the caller.
                      Console.WriteLine("Error: {0}", ex.Message);
                  }
              }
          
              private static void DisplayResults(SqlDataReader reader)
              {
                  // Display the data within the reader.
                  while (reader.Read())
                  {
                      // Display all the columns. 
                      for (int i = 0; i &lt; reader.FieldCount; i++)
                      {
                          Console.Write("{0}\t", reader.GetValue(i));
                      }
                    
                      Console.WriteLine();
                  }
              }
          
              private static string GetConnectionString()
              {
                  // To avoid storing the connection string in your code,            
                  // you can retrieve it from a configuration file. 
                  return "Data Source=(local);Integrated Security=true;" +
                         "Initial Catalog=AdventureWorks";
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>Any error that occurred while executing the command text.</description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method to finish the operation and retrieve the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> returned by the command. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> before the command's execution is completed causes the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          The <paramref name="callback" /> parameter lets you specify an <see cref="T:System.AsyncCallback" /> delegate that is called when the statement has completed. You can call the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the <c>stateObject</c> parameter, and your callback procedure can retrieve this information using the <see cref="P:System.IAsyncResult.AsyncState" /> property.
        </para>
        <para>
          The <paramref name="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 <c>Or</c> operator); generally, developers use the <c>CloseConnection</c> value to make sure that the connection is closed by the runtime when the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed. Developers can also optimize the behavior of the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> by specifying the <c>SingleRow</c> value when it is known in advance that the Transact-SQL statement or stored procedure only returns a single row.
        </para>
        <para>
          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 <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> may block if more data is required and the underlying network's read operation blocks.
        </para>
        <para>
          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.
        </para>
        <para>
          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.
        </para>
        <para>
          If you use <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to read FOR XML queries.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          The following Windows application demonstrates the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object as the <c>stateObject</c> parameter; doing so makes it simple to retrieve the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object from within the callback procedure, so that the code can call the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method corresponding to the initial call to <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" />.
        </para>
        <para>
          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.
        </para>
        <para>
          To set up this example, create a new Windows application. Put a <see cref="T:System.Windows.Forms.Button" /> control, a <see cref="T:System.Windows.Forms.DataGridView" /> control, and a <see cref="T: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.
        </para>
        <para>
          This example passes the <see cref="F:System.Data.CommandBehavior.CloseConnection" /> value in the <paramref name="behavior" /> parameter, causing the returned <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> to automatically close its connection when it is closed.
        </para>
        <!-- SqlCommand_BeginExecuteReaderAsyncBehavior -->
        <code language="c#">
          using System;
          using System.Collections.Generic;
          using System.ComponentModel;
          using System.Data;
          using System.Drawing;
          using System.Text;
          using System.Windows.Forms;
          using Microsoft.Data.SqlClient;
          
          namespace Microsoft.AdoDotNet.CodeSamples
          {
              public partial class Form1 : Form
              {
                  public Form1()
                  {
                      InitializeComponent();
                  }
                
                  // Hook up the form's Load event handler (you can double-click on 
                  // the form's design surface in Visual Studio), and then add 
                  // this code to the form's class:
                  // You need this delegate in order to fill the grid from
                  // a thread other than the form's thread. See the HandleCallback
                  // procedure for more information.
                  private delegate void FillGridDelegate(SqlDataReader reader);
          
                  // You need this delegate to update the status bar.
                  private delegate void DisplayStatusDelegate(string Text);
          
                  // This flag ensures that the user does not attempt
                  // to restart the command or close the form while the 
                  // asynchronous command is executing.
                  private bool isExecuting;
          
                  private void DisplayStatus(string Text)
                  {
                      this.label1.Text = Text;
                  }
          
                  private void FillGrid(SqlDataReader reader)
                  {
                      try
                      {
                          DataTable table = new DataTable();
                          table.Load(reader);
                          this.dataGridView1.DataSource = table;
                          DisplayStatus("Ready");
                      }
                      catch (Exception ex)
                      {
                          // Because you are guaranteed this procedure
                          // is running from within the form's thread,
                          // it can directly interact with members of the form.
                          DisplayStatus(string.Format("Ready (last attempt failed: {0})", ex.Message));
                      }
                      finally
                      {
                          // Closing the reader also closes the connection,
                          // because this reader was created using the 
                          // CommandBehavior.CloseConnection value.
                          if (reader != null)
                          {
                              reader.Close();
                          }
                      }
                  }
          
                  private void HandleCallback(IAsyncResult result)
                  {
                      try
                      {
                          // Retrieve the original command object, passed
                          // to this procedure in the AsyncState property
                          // of the IAsyncResult parameter.
                          SqlCommand command = (SqlCommand)result.AsyncState;
                          SqlDataReader reader = command.EndExecuteReader(result);
                        
                          // You may not interact with the form and its contents
                          // from a different thread, and this callback procedure
                          // is all but guaranteed to be running from a different thread
                          // than the form. Therefore you cannot simply call code that 
                          // fills the grid, like this:
                          // FillGrid(reader);
                          // Instead, you must call the procedure from the form's thread.
                          // One simple way to accomplish this is to call the Invoke
                          // method of the form, which calls the delegate you supply
                          // from the form's thread. 
                          FillGridDelegate del = new FillGridDelegate(FillGrid);
                          this.Invoke(del, reader);
                        
                          // Do not close the reader here, because it is being used in 
                          // a separate thread. Instead, have the procedure you have
                          // called close the reader once it is done with it.
                      }
                      catch (Exception ex)
                      {
                          // Because you are now running code in a separate thread, 
                          // if you do not handle the exception here, none of your other
                          // code catches the exception. Because there is none of 
                          // your code on the call stack in this thread, there is nothing
                          // higher up the stack to catch the exception if you do not 
                          // handle it here. You can either log the exception or 
                          // invoke a delegate (as in the non-error case in this 
                          // example) to display the error on the form. In no case
                          // can you simply display the error without executing a delegate
                          // as in the try block here. 
                          // You can create the delegate instance as you 
                          // invoke it, like this:
                          this.Invoke(new DisplayStatusDelegate(DisplayStatus), "Error: " + ex.Message);
                      }
                      finally
                      {
                          isExecuting = false;
                      }
                  }
          
                  private string GetConnectionString()
                  {
                      // To avoid storing the connection string in your code, 
                      // you can retrieve it from a configuration file. 
                      return "Data Source=(local);Integrated Security=true;" +
                             "Initial Catalog=AdventureWorks";
                  }
          
                  private void button1_Click(object sender, System.EventArgs e)
                  {
                      if (isExecuting)
                      {
                          MessageBox.Show(this,
                              "Already executing. Please wait until the current query " +
                              "has completed.");
                      }
                      else
                      {
                          SqlCommand command = null;
                          SqlConnection connection = null;
                          try
                          {
                              DisplayStatus("Connecting...");
                              connection = new SqlConnection(GetConnectionString());
                              // To emulate a long-running query, wait for 
                              // a few seconds before retrieving the real data.
                              command = new SqlCommand("WAITFOR DELAY '0:0:5';" +
                                  "SELECT ProductID, Name, ListPrice, Weight FROM Production.Product",
                                  connection);
                              connection.Open();
          
                              DisplayStatus("Executing...");
                              isExecuting = true;
                              // Although it is not required that you pass the 
                              // SqlCommand object as the second parameter in the 
                              // BeginExecuteReader call, doing so makes it easier
                              // to call EndExecuteReader in the callback procedure.
                              AsyncCallback callback = new AsyncCallback(HandleCallback);
                              command.BeginExecuteReader(callback, command,
                                  CommandBehavior.CloseConnection);
                          }
                          catch (Exception ex)
                          {
                              DisplayStatus("Error: " + ex.Message);
                              if (connection != null)
                              {
                                  connection.Close();
                              }
                          }
                      }
                  }
          
                  private void Form1_Load(object sender, System.EventArgs e)
                  {
                      this.button1.Click += new System.EventHandler(this.button1_Click);
                      this.FormClosing += new FormClosingEventHandler(Form1_FormClosing);
                  }
          
                  void Form1_FormClosing(object sender, FormClosingEventArgs e)
                  {
                      if (isExecuting)
                      {
                          MessageBox.Show(this, "Cannot close the form until " +
                              "the pending asynchronous command has completed. Please wait...");
                          e.Cancel = true;
                      }
                  }
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            Any error that occurred while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method to finish the operation and retrieve the XML returned by the command. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <c>EndExecuteXmlReader</c> before the command's execution is completed causes the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          The <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /> property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, <c>CommandText</c> can also specify a statement that returns <c>ntext</c> data that contains valid XML.
        </para>
        <para>
          A typical <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> query can be formatted as in the following C# example:
        </para>
        <para>
          <code language="c#">
            SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM dbo.Contact FOR XML AUTO, XMLDATA", SqlConn);
          </code>
        </para>
        <para>
          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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method attaches the <see cref="T:System.Xml.XmlReader" /> to the value on the first row, and discards the rest of the result set.
        </para>
        <para>
          The multiple active result set (MARS) feature lets multiple actions use the same connection.
        </para>
        <para>
          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.
        </para>
        <para>
          Because this overload does not support a callback procedure, developers need to either poll to determine whether the command has completed, using the <see cref="P:System.IAsyncResult.IsCompleted" /> property of the <see cref="T:System.IAsyncResult" /> returned by the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> method; or wait for the completion of one or more commands using the <see cref="P:System.IAsyncResult.AsyncWaitHandle" /> property of the returned <see cref="T:System.IAsyncResult" />.
        </para>
        <para>
          If you use <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to read FOR XML queries.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          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 <see cref="P:System.IAsyncResult.IsCompleted" /> property value. Once the process has completed, the code retrieves the XML and displays its contents.
        </para>
        <!-- SqlCommand_BeginExecuteXmlReader -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          using System.Xml;
          
          class Class1
          {
              static void Main()
              {
                  // This example is not terribly effective, but it proves a point.
                  // The WAITFOR statement simply adds enough time to prove the 
                  // asynchronous nature of the command.
                  string commandText =
                      "WAITFOR DELAY '00:00:03';" +
                      "SELECT Name, ListPrice FROM Production.Product " +
                      "WHERE ListPrice &lt; 100 " +
                      "FOR XML AUTO, XMLDATA";
          
                  RunCommandAsynchronously(commandText, GetConnectionString());
          
                  Console.WriteLine("Press ENTER to continue.");
                  Console.ReadLine();
              }
          
              private static void RunCommandAsynchronously(string commandText, string connectionString)
              {
                  // Given command text and connection string, asynchronously execute
                  // the specified command against the connection. For this example,
                  // the code displays an indicator as it is working, verifying the 
                  // asynchronous behavior. 
                  using (SqlConnection connection = new SqlConnection(connectionString))
                  {
                      SqlCommand command = new SqlCommand(commandText, connection);
          
                      connection.Open();
                      IAsyncResult result = command.BeginExecuteXmlReader();
          
                      // Although it is not necessary, the following procedure
                      // displays a counter in the console window, indicating that 
                      // the main thread is not blocked while awaiting the command 
                      // results.
                      int count = 0;
                      while (!result.IsCompleted)
                      {
                          Console.WriteLine("Waiting ({0})", count++);
                          // Wait for 1/10 second, so the counter
                          // does not consume all available resources 
                          // on the main thread.
                          System.Threading.Thread.Sleep(100);
                      }
          
                      XmlReader reader = command.EndExecuteXmlReader(result);
                      DisplayProductInfo(reader);
                  }
              }
          
              private static void DisplayProductInfo(XmlReader reader)
              {
                  // Display the data within the reader.
                  while (reader.Read())
                  {
                      // Skip past items that are not from the correct table.
                      if (reader.LocalName.ToString() == "Production.Product")
                      {
                          Console.WriteLine("{0}: {1:C}",
                              reader["Name"], Convert.ToSingle(reader["ListPrice"]));
                      }
                  }
              }
          
              private static string GetConnectionString()
              {
                  // To avoid storing the connection string in your code,            
                  // you can retrieve it from a configuration file. 
                  return "Data Source=(local);Integrated Security=true;" +
                         "Initial Catalog=AdventureWorks";
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            Any error that occurred while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method to finish the operation and retrieve the requested XML data. The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> method returns immediately, but until the code executes the corresponding <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object. Calling the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> before the command's execution is completed causes the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object to block until the execution is finished.
        </para>
        <para>
          The <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /> property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, <see cref="P:Microsoft.Data.SqlClient.SqlCommand.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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method attaches the <see cref="T:System.Xml.XmlReader" /> to the value on the first row, and discards the rest of the result set.
        </para>
        <para>
          A typical <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> query can be formatted as in the following C# example:
        </para>
        <para>
          <code language="c#">
            SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM Contact FOR XML AUTO, XMLDATA", SqlConn);
          </code>
        </para>
        <para>
          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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method attaches the <see cref="T:System.Xml.XmlReader" /> to the value on the first row, and discards the rest of the result set.
        </para>
        <para>
          The multiple active result set (MARS) feature lets multiple actions use the same connection.
        </para>
        <para>
          The <paramref name="callback" /> parameter lets you specify an <see cref="P:System.AsyncCallback" /> delegate that is called when the statement has completed. You can call the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the <c>stateObject</c> parameter, and your callback procedure can retrieve this information using the <see cref="T:System.IAsyncResult.AsyncState" /> property.
        </para>
        <para>
          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.
        </para>
        <para>
          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.
        </para>
        <para>
          If you use <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to read FOR XML queries.
        </para>
        <para>
          This method ignores the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> property.
        </para>
      </remarks>
      <example>
        <para>
          The following Windows application demonstrates the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). This example passes the executing <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object as the <paramref name="stateObject" /> parameter--doing so makes it simple to retrieve the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object from within the callback procedure, so that the code can call the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method corresponding to the initial call to <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" />.
        </para>
        <para>
          To set up this example, create a new Windows application. Put a <see cref="T:System.Windows.Forms.Button" /> control, a <see cref="T:System.Windows.Forms.ListBox" /> control, and a <see cref="T: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.
        </para>
        <code language="c#">
          using System;
          using System.Collections.Generic;
          using System.ComponentModel;
          using System.Data;
          using System.Drawing;
          using System.Text;
          using System.Windows.Forms;
          using System.Xml;
          using Microsoft.Data.SqlClient;
          
          namespace Microsoft.AdoDotNet.CodeSamples
          {
              public partial class Form1 : Form
              {
                  // Hook up the form's Load event handler and then add 
                  // this code to the form's class:
                  // You need these delegates in order to display text from a thread
                  // other than the form's thread. See the HandleCallback
                  // procedure for more information.
                  private delegate void DisplayInfoDelegate(string Text);
                  private delegate void DisplayReaderDelegate(XmlReader reader);
          
                  private bool isExecuting;
          
                  // This example maintains the connection object 
                  // externally, so that it is available for closing.
                  private SqlConnection connection;
          
                  public Form1()
                  {
                      InitializeComponent();
                  }
          
                  private string GetConnectionString()
                  {
                      // To avoid storing the connection string in your code, 
                      // you can retrieve it from a configuration file. 
                      return "Data Source=(local);Integrated Security=true;" +
                             "Initial Catalog=AdventureWorks";
                  }
          
                  private void DisplayStatus(string Text)
                  {
                      this.label1.Text = Text;
                  }
          
                  private void ClearProductInfo()
                  {
                      // Clear the list box.
                      this.listBox1.Items.Clear();
                  }
          
                  private void DisplayProductInfo(XmlReader reader)
                  {
                      // Display the data within the reader.
                      while (reader.Read())
                      {
                          // Skip past items that are not from the correct table.
                          if (reader.LocalName.ToString() == "Production.Product")
                          {
                              this.listBox1.Items.Add(String.Format("{0}: {1:C}",
                                  reader["Name"], Convert.ToDecimal(reader["ListPrice"])));
                          }
                      }
                      DisplayStatus("Ready");
                  }
          
                  private void Form1_FormClosing(object sender,
                      System.Windows.Forms.FormClosingEventArgs e)
                  {
                      if (isExecuting)
                      {
                          MessageBox.Show(this, "Cannot close the form until " +
                              "the pending asynchronous command has completed. Please wait...");
                          e.Cancel = true;
                      }
                  }
          
                  private void button1_Click(object sender, System.EventArgs e)
                  {
                      if (isExecuting)
                      {
                          MessageBox.Show(this,
                              "Already executing. Please wait until the current query " +
                              "has completed.");
                      }
                      else
                      {
                          SqlCommand command = null;
                          try
                          {
                              ClearProductInfo();
                              DisplayStatus("Connecting...");
                              connection = new SqlConnection(GetConnectionString());
          
                              // To emulate a long-running query, wait for 
                              // a few seconds before working with the data.
                              string commandText =
                                  "WAITFOR DELAY '00:00:03';" +
                                  "SELECT Name, ListPrice FROM Production.Product " +
                                  "WHERE ListPrice &lt; 100 " +
                                  "FOR XML AUTO, XMLDATA";
          
                              command = new SqlCommand(commandText, connection);
                              connection.Open();
          
                              DisplayStatus("Executing...");
                              isExecuting = true;
                              // Although it is not required that you pass the 
                              // SqlCommand object as the second parameter in the 
                              // BeginExecuteXmlReader call, doing so makes it easier
                              // to call EndExecuteXmlReader in the callback procedure.
                              AsyncCallback callback = new AsyncCallback(HandleCallback);
                              command.BeginExecuteXmlReader(callback, command);
          
                          }
                          catch (Exception ex)
                          {
                              isExecuting = false;
                              DisplayStatus(string.Format("Ready (last error: {0})", ex.Message));
                              if (connection != null)
                              {
                                  connection.Close();
                              }
                          }
                      }
                  }
          
                  private void HandleCallback(IAsyncResult result)
                  {
                      try
                      {
                          // Retrieve the original command object, passed
                          // to this procedure in the AsyncState property
                          // of the IAsyncResult parameter.
                          SqlCommand command = (SqlCommand)result.AsyncState;
                          XmlReader reader = command.EndExecuteXmlReader(result);
          
                          // You may not interact with the form and its contents
                          // from a different thread, and this callback procedure
                          // is all but guaranteed to be running from a different thread
                          // than the form. 
          
                          // Instead, you must call the procedure from the form's thread.
                          // One simple way to accomplish this is to call the Invoke
                          // method of the form, which calls the delegate you supply
                          // from the form's thread. 
                          DisplayReaderDelegate del = new DisplayReaderDelegate(DisplayProductInfo);
                          this.Invoke(del, reader);
          
                      }
                      catch (Exception ex)
                      {
                          // Because you are now running code in a separate thread, 
                          // if you do not handle the exception here, none of your other
                          // code catches the exception. Because none of 
                          // your code is on the call stack in this thread, there is nothing
                          // higher up the stack to catch the exception if you do not 
                          // handle it here. You can either log the exception or 
                          // invoke a delegate (as in the non-error case in this 
                          // example) to display the error on the form. In no case
                          // can you simply display the error without executing a delegate
                          // as in the try block here. 
          
                          // You can create the delegate instance as you 
                          // invoke it, like this:
                          this.Invoke(new DisplayInfoDelegate(DisplayStatus),
                          String.Format("Ready(last error: {0}", ex.Message));
                      }
                      finally
                      {
                          isExecuting = false;
                          if (connection != null)
                          {
                              connection.Close();
                          }
                      }
                  }
          
                  private void Form1_Load(object sender, System.EventArgs e)
                  {
                      this.button1.Click += new System.EventHandler(this.button1_Click);
                      this.FormClosing += new System.Windows.Forms.
                          FormClosingEventHandler(this.Form1_FormClosing);
                  }
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            Any error that occurred while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            <see cref="P:Microsoft.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.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </exception>
      <seealso cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" />
      <seealso 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>
        <para>
          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.
        </para>
        <para>
          In some rare cases, if you call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" />, then call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Close" /> (implicitly or explicitly) before calling <see cref="M:Microsoft.Data.SqlClient.SqlCommand.Cancel" />, and then call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.Cancel" />, the cancel command will not be sent to SQL Server and the result set can continue to stream after you call <see cref="M:Microsoft.Data.SqlClient.SqlConnection.Close" />. To avoid this, make sure that you call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.Cancel" /> before closing the reader or connection.
        </para>
      </remarks>
      <example>
        <para>
          The following example demonstrates the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.Cancel" /> method.
        </para>
        <code language="c#">
          using System;
          using System.Data;
          using System.Threading;
          using Microsoft.Data.SqlClient;
          
          class Program
          {
              private static SqlCommand m_rCommand;
          
              public static SqlCommand Command
              {
                  get { return m_rCommand; }
                  set { m_rCommand = value; }
              }
          
              public static void Thread_Cancel()
              {
                  Command.Cancel();
              }
          
              static void Main()
              {
                  string connectionString = GetConnectionString();
                  try
                  {
                      using (SqlConnection connection = new SqlConnection(connectionString))
                      {
                          connection.Open();
          
                          Command = connection.CreateCommand();
                          Command.CommandText = "DROP TABLE TestCancel";
                          try
                          {
                              Command.ExecuteNonQuery();
                          }
                          catch { }
          
                          Command.CommandText = "CREATE TABLE TestCancel(co1 int, co2 char(10))";
                          Command.ExecuteNonQuery();
                          Command.CommandText = "INSERT INTO TestCancel VALUES (1, '1')";
                          Command.ExecuteNonQuery();
          
                          Command.CommandText = "SELECT * FROM TestCancel";
                          SqlDataReader reader = Command.ExecuteReader();
          
                          Thread rThread2 = new Thread(new ThreadStart(Thread_Cancel));
                          rThread2.Start();
                          rThread2.Join();
          
                          reader.Read();
                          System.Console.WriteLine(reader.FieldCount);
                          reader.Close();
                      }
                  }
                  catch (Exception ex)
                  {
                      Console.WriteLine(ex.Message);
                  }
              }
              static private string GetConnectionString()
              {
                  // To avoid storing the connection string in your code, 
                  // you can retrieve it from a configuration file.
                  return "Data Source=(local);Initial Catalog=AdventureWorks;"
                       + "Integrated Security=SSPI";
              }
          }
        </code>
      </example>
    </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>
    </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>
        <para>
          When the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /> property is set to <see cref="F:System.Data.CommandType.StoredProcedure" />, the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /> 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 <c>Execute*</c> methods.
        </para>
        <para>
          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 <see cref="F:System.Data.CommandType.Text" />. In this case, named parameters must be used. For example:
        </para>
        <para>
          <code language="sql">
            SELECT * FROM dbo.Customers WHERE CustomerID = @CustomerID
          </code>
        </para>
        <para>
          For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/configure-parameters">Configuring parameters</see>.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and sets some of its properties.
        </para>
        <!-- SqlCommand_CommandText -->
        <code language="c#">
          using System;
          using System.Data;
          using System.Data.Common;
          using System.Windows.Forms;
          using System.Xml;
          using Microsoft.Data.SqlClient;

          public class Form1 : Form
          {
              protected DataSet DataSet1;
              protected DataGrid dataGrid1;

              public void CreateCommand()
              {
                  SqlCommand command = new SqlCommand();
                  command.CommandText = "SELECT * FROM Categories ORDER BY CategoryID";
                  command.CommandTimeout = 15;
                  command.CommandType = CommandType.Text;
              }
          }
        </code>
      </example>
    </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>
        <para>
          When you set the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /> property to <see cref="F:System.Data.CommandType.StoredProcedure" />, you should set the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /> property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods.
        </para>
        <para>
          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 <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandType" /> of <see cref="F:System.Data.CommandType.Text" />. In this case, named parameters must be used. For example:
        </para>
        <code language="sql">
          SELECT * FROM Customers WHERE CustomerID = @CustomerID
        </code>
        <para>
          For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/configure-parameters">Configuring parameters</see>.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and sets some of its properties.
        </para>
        <!-- IDbCommand_CommandTimeout -->
        <code language="c#">
          using System;
          using System.Xml;
          using System.Data;
          using System.Data.Common;
          using System.Windows.Forms;
          using Microsoft.Data.SqlClient;

          public class Form1 : Form
          {
              protected DataSet DataSet1;
              protected DataGrid dataGrid1;

              public void CreateSqlCommand()
              {
                  SqlCommand command = new SqlCommand();
                  command.CommandTimeout = 15;
                  command.CommandType = CommandType.Text;
              }
          }
        </code>
      </example>
    </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>
        <para>
          If the command is enlisted in an existing transaction, and the connection is changed, trying to execute the command will throw an <see cref="T:System.InvalidOperationException" />.
        </para>
        <para>
          If the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Transaction" /> property is not null and the transaction has already been committed or rolled back, <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Transaction" /> is set to null.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and sets some of its properties.
        </para>
        <!-- SqlCommand_Connection -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;


          namespace SqlCommandCS
          {
              class Program
              {
                  static void Main()
                  {
                      string str = "Data Source=(local);Initial Catalog=Northwind;"
                                 + "Integrated Security=SSPI";
                      string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
                      CreateCommand(qs, str);
                  }

                  private static void CreateCommand(string queryString, string connectionString)
                  {
                      using (SqlConnection connection = new SqlConnection(
                                 connectionString))
                      {
                          SqlCommand command = new SqlCommand();
                          command.Connection = connection;
                          command.CommandTimeout = 15;
                          command.CommandType = CommandType.Text;
                          command.CommandText = queryString;

                          connection.Open();
                          SqlDataReader reader = command.ExecuteReader();
                          while (reader.Read())
                          {
                              Console.WriteLine(String.Format("{0}, {1}",
                                  reader[0], reader[1]));
                          }
                      }
                  }
              }
          }
        </code>
      </example>
      <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>
        The <see cref="M:Microsoft.Data.SqlClient.SqlCommand.CreateParameter" /> method is a strongly-typed version of <see cref="M:System.Data.IDbCommand.CreateParameter" />.
      </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>
    </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>
    </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="F:System.Data.CommandType.Text"/> otherwise it is ignored.
      </summary>
      <value>
        A value indicating whether the command object should optimize parameter performance by disabling Output and InputOutput 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>
        When you call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> to execute a Transact-SQL statement, you must call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> 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 <see cref="T:System.IAsyncResult" /> instance returned by the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" /> method. If a callback procedure was specified in the call to <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" />, this method must be called.
      </remarks>
      <example>
        For examples demonstrating the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteNonQuery(System.IAsyncResult)" /> method, see <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteNonQuery" />.
      </example>
      <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">
        <list type="bullet">
          <item><description>
            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.
          </description></item>
          <item><description>
            In some situations, <see cref="T:System.IAsyncResult" /> can set <see cref="P:System.IAsyncResult.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.
          </description></item>
        </list>
      </exception>
    </EndExecuteNonQuery>
    <EndExecuteReader name="IAsyncResult">
      <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>
        When you call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> to execute a Transact-SQL statement, you must call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> 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 <see cref="T:System.IAsyncResult" /> instance returned by the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> method. If a callback procedure was specified in the call to <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" />, this method must be called.
      </remarks>
      <example>
        For examples demonstrating the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteReader(System.IAsyncResult)" /> method, see <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" />.
      </example>
      <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>
        When you call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to execute a Transact-SQL statement, you must call <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> 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 <see cref="T:System.IAsyncResult" /> instance returned by the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> method. If a callback procedure was specified in the call to <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" />, this method must be called.
      </remarks>
      <example>
        For examples demonstrating the use of the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.EndExecuteXmlReader(System.IAsyncResult)" /> method, see <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" />.
      </example>
      <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>
        <para>
          You can use the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery" /> 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 <see cref="T:System.Data.DataSet" /> by executing UPDATE, INSERT, or DELETE statements.
        </para>
        <para>
          Although the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery" /> returns no rows, any output parameters or return values mapped to parameters are populated with data.
        </para>
        <para>
          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. 
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and then executes it using <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery" />. 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.
        </para>
        <!-- SqlCommand_ExecuteNonQuery -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          namespace SqlCommandCS
          {
              class Program
              {
                  static void Main()
                  {
                      string str = "Data Source=(local);Initial Catalog=Northwind;"
                                 + "Integrated Security=SSPI";
                      string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
                      CreateCommand(qs, str);
                  }
                  private static void CreateCommand(string queryString,
                      string connectionString)
                  {
                      using (SqlConnection connection = new SqlConnection(
                                 connectionString))
                      {
                          SqlCommand command = new SqlCommand(queryString, connection);
                          command.Connection.Open();
                          command.ExecuteNonQuery();
                      }
                  }
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            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.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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](https://learn.microsoft.com/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">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            Calling <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQueryAsync(System.Threading.CancellationToken)" /> more than once for the same instance before task completion.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            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.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            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" />.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
      <example>
        <para>
          The following example creates a <see cref="T: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. <see cref="T:System.Data.CommandBehavior" /> is set to <see cref="F:System.Data.CommandBehavior.CloseConnection" />.
        </para>
        <!-- SqlCommand_ExecuteReader2 -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          class Program
          {
              static void Main()
              {
                  string str = "Data Source=(local);Initial Catalog=Northwind;"
                             + "Integrated Security=SSPI";
                  string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
                  CreateCommand(qs, str);
              }
          
              private static void CreateCommand(string queryString, string connectionString)
              {
                  using (SqlConnection connection = new SqlConnection(connectionString))
                  {
                      SqlCommand command = new SqlCommand(queryString, connection);
                      connection.Open();
                      SqlDataReader reader = command.ExecuteReader(CommandBehavior.CloseConnection);
                      while (reader.Read())
                      {
                          Console.WriteLine(String.Format("{0}", reader[0]));
                      }
                  }
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type-="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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](https://learn.microsoft.com/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">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.ArgumentException">
        An invalid <see cref="T:System.Data.CommandBehavior" /> value.
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            Calling <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync" /> more than once for the same instance before task completion.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see <see href="https://learn.microsoft.com/sql/connect/ado-net/asynchronous-programming">Asynchronous Programming</see>.
      </remarks>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.ArgumentException">
        An invalid <see cref="T:System.Data.CommandBehavior" /> value.
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            Calling <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync(System.Data.CommandBehavior)" /> more than once for the same instance before task completion.
          </description></item>
          <item><description>
            <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see <see href="https://learn.microsoft.com/sql/connect/ado-net/asynchronous-programming">Asynchronous Programming</see>.
      </remarks>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.ArgumentException">
        An invalid <see cref="T:System.Data.CommandBehavior" /> value.
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            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.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see <see href="https://learn.microsoft.com/sql/connect/ado-net/asynchronous-programming">Asynchronous Programming</see>.
      </remarks>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.ArgumentException">
        An invalid <see cref="T:System.Data.CommandBehavior" /> value.
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            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.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          Use the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar" /> method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> method, and then performing the operations that you need to generate the single value using the data returned by a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
        </para>
      </remarks>
      <example>
        <para>
          A typical <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar" /> query can be formatted as in the following C# example:
        </para>
        <code language="c#">
          cmd.CommandText = "SELECT COUNT(*) FROM dbo.region";
          Int32 count = (Int32) cmd.ExecuteScalar();
        </code>
      </example>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and then executes it using <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar" />. 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 <b>Identity</b> column value if a new row was inserted, 0 on failure. >
        </para>
        <!-- SqlCommand_ExecuteScalar -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          public class Sample
          {
              public void CreateSqlCommand(string queryString, SqlConnection connection)
              {
                  SqlCommand command = new SqlCommand(queryString, connection);
                  command.Connection.Open();
                  command.ExecuteScalar();
                  connection.Close();
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            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.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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](https://learn.microsoft.com/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">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            Calling <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalarAsync(System.Threading.CancellationToken)" /> more than once for the same instance before task completion.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        <para>
          The <see cref="T:System.Xml.XmlReader" /> returned by this method does not support asynchronous operations. The <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /> property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandText" /> can also specify a statement that returns <c>ntext</c> or <c>nvarchar</c> data that contains valid XML, or the contents of a column defined with the <c>xml</c> data type.
        </para>
        <para>
          A typical <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> query can be formatted as in the following Microsoft Visual C# example:
        </para>
        <code language="c#">
          SqlCommand command = new SqlCommand("SELECT * FROM dbo.Customers FOR XML AUTO, XMLDATA", SqlConn);
        </code>
        <para>
          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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> method attaches the <see cref="T:System.Xml.XmlReader" /> to the value on the first row, and discards the rest of the result set.
        </para>
        <para>
          The multiple active result set (MARS) feature allows for multiple actions using the same connection.
        </para>
        <para>
          If you use <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteReader" /> 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 <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" /> or <see cref="M:Microsoft.Data.SqlClient.SqlCommand.BeginExecuteXmlReader" /> to read FOR XML queries.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and then executes it using <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader" />. 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.
        </para>
        <!-- SqlCommand_ExecuteXmlReader -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          private static void CreateXMLReader(string queryString, string connectionString)
          {
              using (SqlConnection connection = new SqlConnection(connectionString))
              {
                  connection.Open();
                  SqlCommand command = new SqlCommand(queryString, connection);
                  System.Xml.XmlReader reader = command.ExecuteXmlReader();
              }
          }
        </code>
      </example>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            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.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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](https://learn.microsoft.com/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">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            Calling <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalarAsync(System.Threading.CancellationToken)" /> more than once for the same instance before task completion.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        The <see cref="T:System.Xml.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 <see href="https://learn.microsoft.com/sql/connect/ado-net/asynchronous-programming">Asynchronous Programming</see>.
      </remarks>
      <exception cref="T:System.InvalidCastException">
        <list type="bullet">
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Binary</c> or <c>VarBinary</c> 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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Char</c>, <c>NChar</c>, <c>NVarChar</c>, <c>VarChar</c>, or <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.IO.TextReader" />.
          </description></item>
          <item><description>
            A <see cref="P:Microsoft.Data.SqlClient.SqlParameter.SqlDbType" /> other than <c>Xml</c> was used when <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> was set to <see cref="T:System.Xml.XmlReader" />.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>
            Calling <see cref="M:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalarAsync(System.Threading.CancellationToken)" /> more than once for the same instance before task completion.
          </description></item>
          <item><description>
            The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> closed or dropped during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        <list type="bullet">
          <item><description>
            SQL Server returned an error while executing the command text.
          </description></item>
          <item><description>
            A timeout occurred during a streaming operation. For more information about streaming, see <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
          </description></item>
        </list>
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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 <see href='https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support'>SqlClient Streaming Support</see>.
      </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>
        You must set the value for this property before the command is executed for it to take effect.
      </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>
      <remarks>
        <para>
          Custom master key store providers can be registered with the driver at three different layers. The precedence of the three registrations is as follows:
        </para>
        <list type="bullet">
          <item><description>The per-command registration will be checked if it is not empty.</description></item>
          <item><description>If the per-command registration is empty, the per-connection registration will be checked if it is not empty.</description></item>
          <item><description>If the per-connection registration is empty, the global registration will be checked.</description></item>
        </list>
        <para>
          Once any key store provider is found at a registration level, the driver will <b>NOT</b> 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.
        </para>
        <para>
          The built-in column master key store providers that are available for the Windows Certificate Store, CNG Store and CSP are pre-registered.
        </para>
        <para>
          This does shallow copying of the dictionary so that the app cannot alter the custom provider list once it has been set.
        </para>
      </remarks>
      <exception cref="T:System.ArgumentNullException">
        <list type="bullet">
          <item><description>A null dictionary was provided.</description></item>
          <item><description>A string key in the dictionary was null or empty.</description></item>
          <item><description>
            A <see cref="T:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider" /> value in the dictionary was null.
          </description></item>
        </list>
      </exception>
      <exception cref="T:System.ArgumentException">
        A string key in the dictionary started with "MSSQL_". This prefix is reserved for system providers.
      </exception>
    </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-retryable 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](https://learn.microsoft.com/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``1(System.Object,System.Func{``0})>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.ExecuteAsync(System.Object,System.Func{System.Threading.Tasks.Task},System.Threading.CancellationToken)>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.ExecuteAsync``1(System.Object,System.Func{System.Threading.Tasks.Task{``0}},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>
        <para>
          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.
        </para>
        <para>
          This property applies only to versions of SQL Server that support query notifications. For earlier versions, setting this property to <see langword="true" /> has no effect on the application.
        </para>
      </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](https://learn.microsoft.com/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>
      <example>
        <para>
          The following example demonstrates how to create a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> and add parameters to the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection" />.
        </para>
        <!-- SqlParameterCollection_AddWithValue -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          class Program
          {
              static void Main()
              {
                  string connectionString = GetConnectionString();
                  string demo = @"&lt;StoreSurvey xmlns=""http://schemas.microsoft.com/sqlserver/2004/07/adventure-works/StoreSurvey""&gt;&lt;AnnualSales&gt;1500000&lt;/AnnualSales&gt;&lt;AnnualRevenue&gt;150000&lt;/AnnualRevenue&gt;&lt;BankName&gt;Primary International&lt;/BankName&gt;&lt;BusinessType&gt;OS&lt;/BusinessType&gt;&lt;YearOpened&gt;1974&lt;/YearOpened&gt;&lt;Specialty&gt;Road&lt;/Specialty&gt;&lt;SquareFeet&lt;38000&lt;/SquareFeet&gt;&lt;Brands&gt;3&lt;/Brands&gt;&lt;Internet&gt;DSL&lt;/Internet&gt;&lt;NumberEmployees&gt;40&lt;/NumberEmployees&gt;&lt;/StoreSurvey&gt;";
                  Int32 id = 3;
                  UpdateDemographics(id, demo, connectionString);
                  Console.ReadLine();
              }
              private static void UpdateDemographics(Int32 customerID,
                  string demoXml, string connectionString)
              {
                  // Update the demographics for a store, which is stored 
                  // in an xml column. 
                  string commandText = "UPDATE Sales.Store SET Demographics = @demographics "
                      + "WHERE CustomerID = @ID;";
          
                  using (SqlConnection connection = new SqlConnection(connectionString))
                  {
                      SqlCommand command = new SqlCommand(commandText, connection);
                      command.Parameters.Add("@ID", SqlDbType.Int);
                      command.Parameters["@ID"].Value = customerID;
          
                      // Use AddWithValue to assign Demographics.
                      // SQL Server will implicitly convert strings into XML.
                      command.Parameters.AddWithValue("@demographics", demoXml);
          
                      try
                      {
                          connection.Open();
                          Int32 rowsAffected = command.ExecuteNonQuery();
                          Console.WriteLine("RowsAffected: {0}", rowsAffected);
                      }
                      catch (Exception ex)
                      {
                          Console.WriteLine(ex.Message);
                      }
                  }
              }

              static private string GetConnectionString()
              {
                  // To avoid storing the connection string in your code, 
                  // you can retrieve it from a configuration file.
                  return "Data Source=(local);Initial Catalog=AdventureWorks;"
                       + "Integrated Security=SSPI";
              }
          }
        </code>
      </example>
    </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 except vector, you must also specify the maximum <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A>.

For vector data types, the <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A> property is ignored. The size of the vector is inferred from the <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of type <xref:Microsoft.Data.SqlTypes.SqlVector%601>.

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>
        The default value of the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> is 30 seconds.
      </remarks>
    </ResetCommandTimeout>
    <StatementCompleted>
      <summary>
        Occurs when the execution of a Transact-SQL statement completes.
      </summary>
    </StatementCompleted>
    <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>
        You cannot set the <see cref="P:Microsoft.Data.SqlClient.SqlCommand.Transaction" /> 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 <see cref="T:Microsoft.Data.SqlClient.SqlTransaction" /> object that is not connected to the same <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> as the <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> object, an exception is thrown the next time that you attempt to execute a statement.
      </remarks>
    </Transaction>
    <UpdatedRowSource>
      <summary>
        Gets or sets how command results are applied to the <see cref="T:System.Data.DataRow" /> when used by the <c>Update</c> method of the <see cref="T:System.Data.Common.DbDataAdapter" />.
      </summary>
      <value>
        One of the <see cref="T:System.Data.UpdateRowSource" /> values.
      </value>
      <remarks>
        <para>
          The default <see cref="T:System.Data.UpdateRowSource" /> value is <see cref="F:System.Data.UpdateRowSource.Both" /> unless the command is automatically generated (as in the case of the <see cref="T:Microsoft.Data.SqlClient.SqlCommandBuilder" />), in which case the default is <see cref="F:System.Data.UpdateRowSource.None" />.
        </para>
        <para>
          For more information about using the <b>UpdatedRowSource</b> property, see <see href="https://learn.microsoft.com/sql/connect/ado-net/dataadapter-parameters">DataAdapter Parameters</see>.
        </para>
      </remarks>
    </UpdatedRowSource>
  </members>
</docs>