SqlCommand.BeginExecuteReader 方法

定义

启动此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行,并从服务器中检索一个或多个结果集。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand, and retrieves one or more result sets from the server.

重载

BeginExecuteReader()

启动此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行,并从服务器中检索一个或多个结果集。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand, and retrieves one or more result sets from the server.

BeginExecuteReader(CommandBehavior)

通过使用 CommandBehavior 值之一,启动此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand using one of the CommandBehavior values.

BeginExecuteReader(AsyncCallback, Object)

在给定回调过程和状态信息的情况下,启动此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行,并从服务器中检索一个或多个结果集。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand and retrieves one or more result sets from the server, given a callback procedure and state information.

BeginExecuteReader(AsyncCallback, Object, CommandBehavior)

在给定回调过程和状态信息的情况下,通过使用 CommandBehavior 值之一并从服务器中检索一个或多个结果集,启动由此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand, using one of the CommandBehavior values, and retrieving one or more result sets from the server, given a callback procedure and state information.

BeginExecuteReader()

启动此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行,并从服务器中检索一个或多个结果集。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand, and retrieves one or more result sets from the server.

public:
 IAsyncResult ^ BeginExecuteReader();
public IAsyncResult BeginExecuteReader ();
member this.BeginExecuteReader : unit -> IAsyncResult
Public Function BeginExecuteReader () As IAsyncResult

返回

IAsyncResult

可用于轮询和/或等待结果的 IAsyncResult;在调用 EndExecuteReader(IAsyncResult) 时,也需要该值。该调用会返回一个可用于检索返回行的 SqlDataReader 实例。An IAsyncResult that can be used to poll or wait for results, or both; this value is also needed when invoking EndExecuteReader(IAsyncResult), which returns a SqlDataReader instance that can be used to retrieve the returned rows.

例外

Value 设置为 Stream 时,使用的是 SqlDbType 而不是 Binary 或 VarBinary。A SqlDbType other than Binary or VarBinary was used when Value was set to Stream. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

- 或 --or-

SqlDbType当设置为时,使用的是不是 CharNCharNVarCharVarCharXml Value TextReaderA SqlDbType other than Char, NChar, NVarChar, VarChar, or Xml was used when Value was set to TextReader.

- 或 --or-

Value 设置为 XmlReader 时,使用的是 SqlDbType 而不是 Xml。A SqlDbType other than Xml was used when Value was set to XmlReader.

执行命令文本时出现的任何错误。Any error that occurred while executing the command text.

- 或 --or-

流式处理操作期间发生了超时。A timeout occurred during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

名称/值对“Asynchronous Processing=true”未包含在为此 SqlCommand 定义连接的连接字符串中。The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this SqlCommand.

- 或 --or-

流式处理操作期间关闭或删除了 SqlConnectionThe SqlConnection closed or dropped during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间在 StreamXmlReaderTextReader 对象中出现了错误。An error occurred in a Stream, XmlReader or TextReader object during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间关闭了 StreamXmlReaderTextReader 对象。The Stream, XmlReader or TextReader object was closed during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

示例

下面的控制台应用程序启动以异步方式检索数据读取器的进程。The following console application starts the process of retrieving a data reader asynchronously. 等待结果时,这个简单的应用程序在循环中,调查 IsCompleted 属性值。While waiting for the results, this simple application sits in a loop, investigating the IsCompleted property value. 完成该过程后,代码会立即检索 SqlDataReader 并显示其内容。As soon as the process has completed, the code retrieves the SqlDataReader and displays its contents.

using System.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 < reader.FieldCount; i++)
                Console.Write("{0} ", 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.

        // If you have not included "Asynchronous Processing=true" in the
        // connection string, the command is not able
        // to execute asynchronously.
        return "Data Source=(local);Integrated Security=true;" +
            "Initial Catalog=AdventureWorks; Asynchronous Processing=true";
    }
}
Imports System.Data.SqlClient

Module Module1
    Sub 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.
        Dim commandText As String = _
         "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()
    End Sub

    Private Sub RunCommandAsynchronously( _
     ByVal commandText As String, ByVal connectionString As String)

        ' 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 connection As New SqlConnection(connectionString)
            Try
                Dim command As New SqlCommand(commandText, connection)

                connection.Open()
                Dim result As IAsyncResult = command.BeginExecuteReader()

                ' 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.
                Dim count As Integer
                While Not 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.
                    Threading.Thread.Sleep(100)
                End While

                ' Once the IAsyncResult object signals that it is done
                ' waiting for results, you can retrieve the results.
                Using reader As SqlDataReader = command.EndExecuteReader(result)
                    DisplayResults(reader)
                End Using
            Catch ex As SqlException
                Console.WriteLine("Error ({0}): {1}", ex.Number, ex.Message)
            Catch ex As InvalidOperationException
                Console.WriteLine("Error: {0}", ex.Message)
            Catch ex As Exception
                ' You might want to pass these errors
                ' back out to the caller.
                Console.WriteLine("Error: {0}", ex.Message)
            End Try
        End Using
    End Sub

    Private Sub DisplayResults(ByVal reader As SqlDataReader)
        ' Display the data within the reader.
        While reader.Read()
            ' Display all the columns.
            For i As Integer = 0 To reader.FieldCount - 1
                Console.Write("{0} ", reader.GetValue(i))
            Next
            Console.WriteLine()
        End While
    End Sub

    Private Function GetConnectionString() As String
        ' To avoid storing the connection string in your code, 
        ' you can retrieve it from a configuration file. 

        ' If you have not included "Asynchronous Processing=true" in the
        ' connection string, the command is not able
        ' to execute asynchronously.
        Return "Data Source=(local);Integrated Security=true;" & _
          "Initial Catalog=AdventureWorks; Asynchronous Processing=true"
    End Function
End Module

注解

BeginExecuteReader方法启动异步执行 transact-sql 语句或返回行的存储过程的过程,以便在执行语句时可以同时运行其他任务。The 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. 完成语句后,开发人员必须调用 EndExecuteReader 方法以完成操作并检索 SqlDataReader 命令返回的。When the statement has completed, developers must call the EndExecuteReader method to finish the operation and retrieve the SqlDataReader returned by the command. BeginExecuteReader方法会立即返回,但在代码执行相应的 EndExecuteReader 方法调用之前,不能执行对同一对象启动同步或异步执行的任何其他调用 SqlCommandThe BeginExecuteReader method returns immediately, but until the code executes the corresponding EndExecuteReader method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same SqlCommand object. EndExecuteReader 命令的执行完成之前调用,将导致 SqlCommand 对象被阻止,直到执行完成。Calling the EndExecuteReader before the command's execution is completed causes the SqlCommand object to block until the execution is finished.

请注意,命令文本和参数同步发送到服务器。Note that the command text and parameters are sent to the server synchronously. 如果发送了大命令或多个参数,则此方法可能会在写入过程中被阻止。If a large command or many parameters are sent, this method may block during writes. 发送命令后,该方法立即返回,而不会等待来自服务器的应答,也就是说,读取是异步的。After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. 尽管命令执行是异步的,但值提取仍同步。Although command execution is asynchronous, value fetching is still synchronous. 这意味着, Read 如果需要更多的数据和基础网络的读取操作,则对的调用可能会阻止。This means that calls to Read may block if more data is required and the underlying network's read operation blocks.

由于此重载不支持回调过程,因此开发人员必须轮询以确定命令是否已完成,使用 IsCompleted 由方法返回的的属性 IAsyncResult BeginExecuteReader ; 或等待使用返回的的属性的一个或多个命令的完成 AsyncWaitHandle IAsyncResultBecause this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the IsCompleted property of the IAsyncResult returned by the BeginExecuteReader method; or wait for the completion of one or more commands using the AsyncWaitHandle property of the returned IAsyncResult.

如果使用 ExecuteReaderBeginExecuteReader 访问 XML 数据,SQL Server 将返回长度超过2033个字符的任何 XML 结果,其中每个行的长度为2033个字符。If you use ExecuteReader or 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. 若要避免此行为,请使用 ExecuteXmlReaderBeginExecuteXmlReader 来读取 FOR XML 查询。To avoid this behavior, use ExecuteXmlReader or BeginExecuteXmlReader to read FOR XML queries.

此方法将忽略 CommandTimeout 属性。This method ignores the CommandTimeout property.

适用于

BeginExecuteReader(CommandBehavior)

通过使用 CommandBehavior 值之一,启动此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand using one of the CommandBehavior values.

public:
 IAsyncResult ^ BeginExecuteReader(System::Data::CommandBehavior behavior);
public IAsyncResult BeginExecuteReader (System.Data.CommandBehavior behavior);
member this.BeginExecuteReader : System.Data.CommandBehavior -> IAsyncResult
Public Function BeginExecuteReader (behavior As CommandBehavior) As IAsyncResult

参数

behavior
CommandBehavior

CommandBehavior 值之一,指示用于语句执行和数据检索的选项。One of the CommandBehavior values, indicating options for statement execution and data retrieval.

返回

IAsyncResult

可用于轮询和/或等待结果的 IAsyncResult;当调用会返回一个可用于检索返回行的 SqlDataReader 实例的 EndExecuteReader(IAsyncResult) 时,也需要该值。An IAsyncResult that can be used to poll, wait for results, or both; this value is also needed when invoking EndExecuteReader(IAsyncResult), which returns a SqlDataReader instance that can be used to retrieve the returned rows.

例外

Value 设置为 Stream 时,使用的是 SqlDbType 而不是 Binary 或 VarBinary。A SqlDbType other than Binary or VarBinary was used when Value was set to Stream. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

- 或 --or-

SqlDbType当设置为时,使用的是不是 CharNCharNVarCharVarCharXml Value TextReaderA SqlDbType other than Char, NChar, NVarChar, VarChar, or Xml was used when Value was set to TextReader.

- 或 --or-

Value 设置为 XmlReader 时,使用的是 SqlDbType 而不是 Xml。A SqlDbType other than Xml was used when Value was set to XmlReader.

执行命令文本时出现的任何错误。Any error that occurred while executing the command text.

- 或 --or-

流式处理操作期间发生了超时。A timeout occurred during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

名称/值对“Asynchronous Processing=true”未包含在为此 SqlCommand 定义连接的连接字符串中。The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this SqlCommand.

- 或 --or-

流式处理操作期间关闭或删除了 SqlConnectionThe SqlConnection closed or dropped during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间在 StreamXmlReaderTextReader 对象中出现了错误。An error occurred in a Stream, XmlReader or TextReader object during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间关闭了 StreamXmlReaderTextReader 对象。The Stream, XmlReader or TextReader object was closed during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

示例

下面的控制台应用程序启动以异步方式检索数据读取器的进程。The following console application starts the process of retrieving a data reader asynchronously. 等待结果时,这个简单的应用程序在循环中,调查 IsCompleted 属性值。While waiting for the results, this simple application sits in a loop, investigating the IsCompleted property value. 完成此过程后,代码会检索 SqlDataReader 并显示其内容。Once the process has completed, the code retrieves the SqlDataReader and displays its contents.

此示例还 CommandBehavior.CloseConnection CommandBehavior.SingleRow 在行为参数中传递和值,导致在返回的关闭时关闭连接 SqlDataReader ,并针对单个行结果进行优化。This example also passes the CommandBehavior.CloseConnection and CommandBehavior.SingleRow values in the behavior parameter, causing the connection to be closed with the returned SqlDataReader is closed, and to optimize for a single row result.

using System.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 < 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 < 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.

        // If you have not included "Asynchronous Processing=true" in the
        // connection string, the command is not able
        // to execute asynchronously.
        return "Data Source=(local);Integrated Security=true;" +
            "Initial Catalog=AdventureWorks; Asynchronous Processing=true";
    }
}
Imports System.Data.SqlClient

Module Module1
    Sub 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.
        Dim commandText As String = _
         "WAITFOR DELAY '00:00:03';" & _
         "SELECT ProductID, Name FROM Production.Product WHERE ListPrice < 100"

        RunCommandAsynchronously(commandText, GetConnectionString())

        Console.WriteLine("Press ENTER to continue.")
        Console.ReadLine()
    End Sub

    Private Sub RunCommandAsynchronously( _
     ByVal commandText As String, ByVal connectionString As String)

        ' 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. 
            Dim connection As New SqlConnection(connectionString)
            Dim command As New SqlCommand(commandText, connection)

            connection.Open()
            Dim result As IAsyncResult = _
              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.
            Dim count As Integer = 0
            While Not 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.
                Threading.Thread.Sleep(100)
            End While

            ' The "using" statement closes the SqlDataReader when it is 
            ' done executing.
            Using reader As SqlDataReader = command.EndExecuteReader(result)
                DisplayResults(reader)
            End Using
        Catch ex As SqlException
            Console.WriteLine("Error ({0}): {1}", ex.Number, ex.Message)
        Catch ex As InvalidOperationException
            Console.WriteLine("Error: {0}", ex.Message)
        Catch ex As Exception
            ' You might want to pass these errors
            ' back out to the caller.
            Console.WriteLine("Error: {0}", ex.Message)
        End Try
    End Sub

    Private Sub DisplayResults(ByVal reader As SqlDataReader)
        ' Display the data within the reader.
        While reader.Read()
            ' Display all the columns. 
            For i As Integer = 0 To reader.FieldCount - 1
                Console.Write("{0} ", reader.GetValue(i))
            Next
            Console.WriteLine()
        End While
    End Sub

    Private Function GetConnectionString() As String
        ' To avoid storing the connection string in your code,            
        ' you can retrieve it from a configuration file. 

        ' If you have not included "Asynchronous Processing=true" in the
        ' connection string, the command is not able
        ' to execute asynchronously.
        Return "Data Source=(local);Integrated Security=true;" & _
          "Initial Catalog=AdventureWorks; Asynchronous Processing=true"
    End Function
End Module

注解

BeginExecuteReader方法启动异步执行 transact-sql 语句或返回行的存储过程的过程,以便在执行语句时可以同时运行其他任务。The 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. 完成语句后,开发人员必须调用 EndExecuteReader 方法以完成操作并检索 SqlDataReader 命令返回的。When the statement has completed, developers must call the EndExecuteReader method to finish the operation and retrieve the SqlDataReader returned by the command. BeginExecuteReader方法会立即返回,但在代码执行相应的 EndExecuteReader 方法调用之前,不能执行对同一对象启动同步或异步执行的任何其他调用 SqlCommandThe BeginExecuteReader method returns immediately, but until the code executes the corresponding EndExecuteReader method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same SqlCommand object. EndExecuteReader 命令的执行完成之前调用,将导致 SqlCommand 对象被阻止,直到执行完成。Calling the EndExecuteReader before the command's execution is completed causes the SqlCommand object to block until the execution is finished.

behavior参数使你可以指定控制命令的行为及其连接的选项。The behavior parameter lets you specify options that control the behavior of the command and its connection. 使用编程语言的运算符) ,这些值可以组合在一起 (OR ; 通常情况下,开发人员使用 CommandBehavior.CloseConnection 该值以确保在关闭时,运行时关闭连接 SqlDataReaderThese values can be combined together (using the programming language's OR operator); generally, developers use the CommandBehavior.CloseConnection value to make sure that the connection is closed by the runtime when the SqlDataReader is closed.

请注意,命令文本和参数同步发送到服务器。Note that the command text and parameters are sent to the server synchronously. 如果发送了大命令或多个参数,则此方法可能会在写入过程中被阻止。If a large command or many parameters are sent, this method may block during writes. 发送命令后,该方法立即返回,而不会等待来自服务器的应答,也就是说,读取是异步的。After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. 尽管命令执行是异步的,但值提取仍同步。Although command execution is asynchronous, value fetching is still synchronous. 这意味着, Read 如果需要更多的数据和基础网络的读取操作,则对的调用可能会阻止。This means that calls to Read may block if more data is required and the underlying network's read operation blocks.

由于此重载不支持回调过程,因此开发人员必须轮询以确定命令是否已完成,使用 IsCompleted 由方法返回的的属性 IAsyncResult BeginExecuteNonQuery ; 或等待使用返回的的属性的一个或多个命令的完成 AsyncWaitHandle IAsyncResultBecause this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the IsCompleted property of the IAsyncResult returned by the BeginExecuteNonQuery method; or wait for the completion of one or more commands using the AsyncWaitHandle property of the returned IAsyncResult.

如果使用 ExecuteReaderBeginExecuteReader 访问 XML 数据,SQL Server 将返回长度超过2033个字符的任何 XML 结果,其中每个行的长度为2033个字符。If you use ExecuteReader or 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. 若要避免此行为,请使用 ExecuteXmlReaderBeginExecuteXmlReader 来读取 FOR XML 查询。To avoid this behavior, use ExecuteXmlReader or BeginExecuteXmlReader to read FOR XML queries.

此方法将忽略 CommandTimeout 属性。This method ignores the CommandTimeout property.

适用于

BeginExecuteReader(AsyncCallback, Object)

在给定回调过程和状态信息的情况下,启动此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行,并从服务器中检索一个或多个结果集。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand and retrieves one or more result sets from the server, given a callback procedure and state information.

public:
 IAsyncResult ^ BeginExecuteReader(AsyncCallback ^ callback, System::Object ^ stateObject);
public IAsyncResult BeginExecuteReader (AsyncCallback callback, object stateObject);
member this.BeginExecuteReader : AsyncCallback * obj -> IAsyncResult
Public Function BeginExecuteReader (callback As AsyncCallback, stateObject As Object) As IAsyncResult

参数

callback
AsyncCallback

命令执行完成时调用的 AsyncCallback 委托。An AsyncCallback delegate that is invoked when the command's execution has completed. 传递 null(在 Microsoft Visual Basic 中为 Nothing)以指示不需要回调。Pass null (Nothing in Microsoft Visual Basic) to indicate that no callback is required.

stateObject
Object

传递到回调过程的用户定义的状态对象。A user-defined state object that is passed to the callback procedure. 使用 AsyncState 属性从回调过程内检索此对象。Retrieve this object from within the callback procedure using the AsyncState property.

返回

IAsyncResult

可用于轮询和/或等待结果的 IAsyncResult;当调用会返回可用于检索返回行的 SqlDataReader 实例的 EndExecuteReader(IAsyncResult) 时,也需要该值。An IAsyncResult that can be used to poll, wait for results, or both; this value is also needed when invoking EndExecuteReader(IAsyncResult), which returns a SqlDataReader instance which can be used to retrieve the returned rows.

例外

Value 设置为 Stream 时,使用的是 SqlDbType 而不是 Binary 或 VarBinary。A SqlDbType other than Binary or VarBinary was used when Value was set to Stream. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

- 或 --or-

SqlDbType当设置为时,使用的是不是 CharNCharNVarCharVarCharXml Value TextReaderA SqlDbType other than Char, NChar, NVarChar, VarChar, or Xml was used when Value was set to TextReader.

- 或 --or-

Value 设置为 XmlReader 时,使用的是 SqlDbType 而不是 Xml。A SqlDbType other than Xml was used when Value was set to XmlReader.

执行命令文本时出现的任何错误。Any error that occurred while executing the command text.

- 或 --or-

流式处理操作期间发生了超时。A timeout occurred during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

名称/值对“Asynchronous Processing=true”未包含在为此 SqlCommand 定义连接的连接字符串中。The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this SqlCommand.

- 或 --or-

流式处理操作期间关闭或删除了 SqlConnectionThe SqlConnection closed or dropped during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间在 StreamXmlReaderTextReader 对象中出现了错误。An error occurred in a Stream, XmlReader or TextReader object during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间关闭了 StreamXmlReaderTextReader 对象。The Stream, XmlReader or TextReader object was closed during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

示例

以下 Windows 应用程序演示如何使用 BeginExecuteReader 方法,以执行包含几秒钟延迟(模拟长时间运行的命令)的 Transact-SQL 语句。The following Windows application demonstrates the use of the 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. 此示例将执行的 SqlCommand 对象作为 stateObject 参数传递; 这样做可以简化 SqlCommand 从回调过程内检索对象的过程,从而使代码可以调用 EndExecuteReader 对应于的初始调用的方法 BeginExecuteReaderThis example passes the executing SqlCommand object as the stateObject parameter; doing so makes it simple to retrieve the SqlCommand object from within the callback procedure, so that the code can call the EndExecuteReader method corresponding to the initial call to BeginExecuteReader.

此示例演示了许多重要的方法。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.

若要设置此示例,请创建新的 Windows 应用程序。To set up this example, create a new Windows application. Button DataGridView 在窗体上放置控件、控件和 Label 控件 (接受每个控件) 的默认名称。Put a Button control, a DataGridView control, and a 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.

using System.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 = false;

        // Because the overloaded version of BeginExecuteReader
        // demonstrated here does not allow you to have the connection
        // closed automatically, this example maintains the
        // connection object externally, so that it is available for closing.
        private SqlConnection connection = null;

        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
            {
                // Do not forget to close the connection, as well.
                if (reader != null)
                {
                    reader.Close();
                }
                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;
                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.

            // If you do not include the Asynchronous Processing=true name/value pair,
            // you wo not be able to execute the command asynchronously.
            return "Data Source=(local);Integrated Security=true;" +
                "Initial Catalog=AdventureWorks; Asynchronous Processing=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
                {
                    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);
                }
                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;
            }
        }
    }
}
Imports System.Data.SqlClient

Public Class Form1
    ' 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 Sub FillGridDelegate(ByVal reader As SqlDataReader)

    ' You need this delegate to update the status bar.
    Private Delegate Sub DisplayStatusDelegate(ByVal Text As String)

    ' This flag ensures that the user does not attempt
    ' to restart the command or close the form while the 
    ' asynchronous command is executing.
    Private isExecuting As Boolean

    ' Because the overloaded version of BeginExecuteReader
    ' demonstrated here does not allow you to have the connection
    ' closed automatically, this example maintains the 
    ' connection object externally, so that it is available for closing.
    Private connection As SqlConnection

    Private Sub DisplayStatus(ByVal Text As String)
        Me.Label1.Text = Text
    End Sub

    Private Sub FillGrid(ByVal reader As SqlDataReader)
        Try
            Dim table As New DataTable
            table.Load(reader)
            Me.DataGridView1.DataSource = table
            DisplayStatus("Ready")

        Catch ex As Exception
            ' 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
            ' Do not forget to close the connection, as well.
            If Not reader Is Nothing Then
                reader.Close()
            End If
            If Not connection Is Nothing Then
                connection.Close()
            End If
        End Try
    End Sub

    Private Sub HandleCallback(ByVal result As IAsyncResult)
        Try
            ' Retrieve the original command object, passed
            ' to this procedure in the AsyncState property
            ' of the IAsyncResult parameter.
            Dim command As SqlCommand = CType(result.AsyncState, SqlCommand)
            Dim reader As SqlDataReader = 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. 
            Dim del As New FillGridDelegate(AddressOf FillGrid)
            Me.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 ex As Exception
            ' 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:
            Me.Invoke(New DisplayStatusDelegate(AddressOf DisplayStatus), _
             "Error: " & ex.Message)
        Finally
            isExecuting = False
        End Try
    End Sub

    Private Function GetConnectionString() As String
        ' To avoid storing the connection string in your code,
        ' you can retrieve it from a configuration file. 

        ' If you do not include the Asynchronous Processing=true name/value pair,
        ' you wo not be able to execute the command asynchronously.

        Return "Data Source=(local);Integrated Security=true;" & _
        "Initial Catalog=AdventureWorks; Asynchronous Processing=true"
    End Function

    Private Sub Button1_Click(ByVal sender As System.Object, _
        ByVal e As System.EventArgs) Handles Button1.Click
        If isExecuting Then
            MessageBox.Show(Me, _
                "Already executing. Please wait until the current query " & _
                "has completed.")
        Else
            Dim command As SqlCommand
            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.
                Dim callback As New AsyncCallback(AddressOf HandleCallback)
                command.BeginExecuteReader(callback, command)

            Catch ex As Exception
                DisplayStatus("Error: " & ex.Message)
                If connection IsNot Nothing Then
                    connection.Close()
                End If
            End Try
        End If
    End Sub

    Private Sub Form1_FormClosing(ByVal sender As Object, _
        ByVal e As System.Windows.Forms.FormClosingEventArgs) _
        Handles Me.FormClosing
        If isExecuting Then
            MessageBox.Show(Me, "Cannot close the form until " & _
              "the pending asynchronous command has completed. Please wait...")
            e.Cancel = True
        End If
    End Sub
End Class

注解

BeginExecuteReader方法启动异步执行 transact-sql 语句或返回行的存储过程的过程,以便在执行语句时可以同时运行其他任务。The 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. 完成语句后,开发人员必须调用 EndExecuteReader 方法以完成操作并检索 SqlDataReader 命令返回的。When the statement has completed, developers must call the EndExecuteReader method to finish the operation and retrieve the SqlDataReader returned by the command. BeginExecuteReader方法会立即返回,但在代码执行相应的 EndExecuteReader 方法调用之前,不能执行对同一对象启动同步或异步执行的任何其他调用 SqlCommandThe BeginExecuteReader method returns immediately, but until the code executes the corresponding EndExecuteReader method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same SqlCommand object. EndExecuteReader 命令的执行完成之前调用,导致 SqlCommand 对象被阻止,直到完成执行为止。Calling the EndExecuteReader before the command's execution is completed cause the SqlCommand object to block until the execution is finished.

使用 callback 参数可以指定在 AsyncCallback 语句完成时调用的委托。The callback parameter lets you specify an AsyncCallback delegate that is called when the statement has completed. 你可以 EndExecuteReader 从该委托过程或应用程序中的任何其他位置调用此方法。You can call the EndExecuteReader method from within this delegate procedure, or from any other location within your application. 此外,可以传递参数中的任何对象 stateObject ,并且回调过程可以使用属性检索此信息 AsyncStateIn addition, you can pass any object in the stateObject parameter, and your callback procedure can retrieve this information using the AsyncState property.

请注意,命令文本和参数同步发送到服务器。Note that the command text and parameters are sent to the server synchronously. 如果发送了大命令或多个参数,则此方法可能会在写入过程中被阻止。If a large command or many parameters are sent, this method may block during writes. 发送命令后,该方法立即返回,而不会等待来自服务器的应答,也就是说,读取是异步的。After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. 尽管命令执行是异步的,但值提取仍同步。Although command execution is asynchronous, value fetching is still synchronous. 这意味着, Read 如果需要更多的数据和基础网络的读取操作,则对的调用可能会阻止。This means that calls to Read may block if more data is required and the underlying network's read operation blocks.

由于回调过程是从 Microsoft .NET 运行时提供的后台线程中执行的,因此,必须采用一种严格的方法来处理应用程序内的跨线程交互。Because the callback procedure executes from within a background thread supplied by the Microsoft .NET runtime, it is very important that you take a rigorous approach to handling cross-thread interactions from within your applications. 例如,您不能在回调过程中与窗体内容交互;如果必须更新窗体,必须切换回窗体的线程才能完成工作。For example, you must not interact with a form's contents from within your callback procedure; should you have to update the form, you must switch back to the form's thread in order to do your work. 本主题中的示例演示了此行为。The example in this topic demonstrates this behavior.

在执行操作过程中发生的所有错误都作为回调过程中的异常引发。All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. 必须在回调过程中处理异常,而不是在主应用程序中处理。You must handle the exception in the callback procedure, not in the main application. 请参阅本主题中的示例,了解有关在回调过程中处理异常的其他信息。See the example in this topic for additional information on handling exceptions in the callback procedure.

如果使用 ExecuteReaderBeginExecuteReader 访问 XML 数据,SQL Server 将返回长度超过2033个字符的任何 XML 结果,其中每个行的长度为2033个字符。If you use ExecuteReader or 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. 若要避免此行为,请使用 ExecuteXmlReaderBeginExecuteXmlReader 来读取 FOR XML 查询。To avoid this behavior, use ExecuteXmlReader or BeginExecuteXmlReader to read FOR XML queries.

此方法将忽略 CommandTimeout 属性。This method ignores the CommandTimeout property.

适用于

BeginExecuteReader(AsyncCallback, Object, CommandBehavior)

在给定回调过程和状态信息的情况下,通过使用 CommandBehavior 值之一并从服务器中检索一个或多个结果集,启动由此 SqlCommand 描述的 Transact-SQL 语句或存储过程的异步执行。Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this SqlCommand, using one of the CommandBehavior values, and retrieving one or more result sets from the server, given a callback procedure and state information.

public:
 IAsyncResult ^ BeginExecuteReader(AsyncCallback ^ callback, System::Object ^ stateObject, System::Data::CommandBehavior behavior);
public IAsyncResult BeginExecuteReader (AsyncCallback callback, object stateObject, System.Data.CommandBehavior behavior);
member this.BeginExecuteReader : AsyncCallback * obj * System.Data.CommandBehavior -> IAsyncResult
Public Function BeginExecuteReader (callback As AsyncCallback, stateObject As Object, behavior As CommandBehavior) As IAsyncResult

参数

callback
AsyncCallback

命令执行完成时调用的 AsyncCallback 委托。An AsyncCallback delegate that is invoked when the command's execution has completed. 传递 null(在 Microsoft Visual Basic 中为 Nothing)以指示不需要回调。Pass null (Nothing in Microsoft Visual Basic) to indicate that no callback is required.

stateObject
Object

传递到回调过程的用户定义的状态对象。A user-defined state object that is passed to the callback procedure. 使用 AsyncState 属性从回调过程内检索此对象。Retrieve this object from within the callback procedure using the AsyncState property.

behavior
CommandBehavior

CommandBehavior 值之一,指示用于语句执行和数据检索的选项。One of the CommandBehavior values, indicating options for statement execution and data retrieval.

返回

IAsyncResult

可用于轮询和/或等待结果的 IAsyncResult;在调用 EndExecuteReader(IAsyncResult) 时,也需要该值。该调用会返回一个可用于检索返回行的 SqlDataReader 实例。An IAsyncResult that can be used to poll or wait for results, or both; this value is also needed when invoking EndExecuteReader(IAsyncResult), which returns a SqlDataReader instance which can be used to retrieve the returned rows.

例外

Value 设置为 Stream 时,使用的是 SqlDbType 而不是 Binary 或 VarBinary。A SqlDbType other than Binary or VarBinary was used when Value was set to Stream. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

- 或 --or-

SqlDbType当设置为时,使用的是不是 CharNCharNVarCharVarCharXml Value TextReaderA SqlDbType other than Char, NChar, NVarChar, VarChar, or Xml was used when Value was set to TextReader.

- 或 --or-

Value 设置为 XmlReader 时,使用的是 SqlDbType 而不是 Xml。A SqlDbType other than Xml was used when Value was set to XmlReader.

执行命令文本时出现的任何错误。Any error that occurred while executing the command text.

- 或 --or-

流式处理操作期间发生了超时。A timeout occurred during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

名称/值对“Asynchronous Processing=true”未包含在为此 SqlCommand 定义连接的连接字符串中。The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this SqlCommand.

- 或 --or-

流式处理操作期间关闭或删除了 SqlConnectionThe SqlConnection closed or dropped during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间在 StreamXmlReaderTextReader 对象中出现了错误。An error occurred in a Stream, XmlReader or TextReader object during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

流式处理操作期间关闭了 StreamXmlReaderTextReader 对象。The Stream, XmlReader or TextReader object was closed during a streaming operation. 有关流式处理的详细信息,请参阅 SqlClient 流支持For more information about streaming, see SqlClient Streaming Support.

示例

以下 Windows 应用程序演示如何使用 BeginExecuteReader 方法,以执行包含几秒钟延迟(模拟长时间运行的命令)的 Transact-SQL 语句。The following Windows application demonstrates the use of the 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. 此示例将执行的 SqlCommand 对象作为 stateObject 参数传递; 这样做可以简化 SqlCommand 从回调过程内检索对象的过程,从而使代码可以调用 EndExecuteReader 对应于的初始调用的方法 BeginExecuteReaderThis example passes the executing SqlCommand object as the stateObject parameter; doing so makes it simple to retrieve the SqlCommand object from within the callback procedure, so that the code can call the EndExecuteReader method corresponding to the initial call to BeginExecuteReader.

此示例演示了许多重要的方法。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.

若要设置此示例,请创建新的 Windows 应用程序。To set up this example, create a new Windows application. Button DataGridView 在窗体上放置控件、控件和 Label 控件 (接受每个控件) 的默认名称。Put a Button control, a DataGridView control, and a 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.

此示例 CommandBehavior.CloseConnection 在参数中传递值 behavior ,导致返回的在 SqlDataReader 关闭时自动关闭其连接。This example passes the CommandBehavior.CloseConnection value in the behavior parameter, causing the returned SqlDataReader to automatically close its connection when it is closed.

using System.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.

            // If you do not include the Asynchronous Processing=true name/value pair,
            // you wo not be able to execute the command asynchronously.
            return "Data Source=(local);Integrated Security=true;" +
                "Initial Catalog=AdventureWorks; Asynchronous Processing=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;
                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;
            }
        }
    }
}
Imports System.Data.SqlClient

Public Class Form1
    ' Add this code to the form's class:
    ' You 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 Sub FillGridDelegate(ByVal reader As SqlDataReader)

    ' You need this delegate to update the status bar.
    Private Delegate Sub DisplayStatusDelegate(ByVal Text As String)

    ' This flag ensures that the user does not attempt
    ' to restart the command or close the form while the 
    ' asynchronous command is executing.
    Private isExecuting As Boolean

    Private Sub DisplayStatus(ByVal Text As String)
        Me.Label1.Text = Text
    End Sub

    Private Sub FillGrid(ByVal reader As SqlDataReader)
        Try
            Dim table As New DataTable
            table.Load(reader)
            Me.DataGridView1.DataSource = table
            DisplayStatus("Ready")

        Catch ex As Exception
            ' 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 IsNot Nothing Then
                reader.Close()
            End If
        End Try
    End Sub

    Private Sub HandleCallback(ByVal result As IAsyncResult)
        Try
            ' Retrieve the original command object, passed
            ' to this procedure in the AsyncState property
            ' of the IAsyncResult parameter.
            Dim command As SqlCommand = CType(result.AsyncState, SqlCommand)
            Dim reader As SqlDataReader = 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. 
            Dim del As New FillGridDelegate(AddressOf FillGrid)
            Me.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 ex As Exception
            ' 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:
            Me.Invoke(New DisplayStatusDelegate(AddressOf DisplayStatus), _
             "Error: " & ex.Message)
        Finally
            isExecuting = False
        End Try
    End Sub

    Private Function GetConnectionString() As String
        ' To avoid storing the connection string in your code,
        ' you can retrieve it from a configuration file. 

        ' If you do not include the Asynchronous Processing=true name/value pair,
        ' you wo not be able to execute the command asynchronously.

        Return "Data Source=(local);Integrated Security=true;" & _
        "Initial Catalog=AdventureWorks; Asynchronous Processing=true"
    End Function

    Private Sub Button1_Click(ByVal sender As System.Object, _
        ByVal e As System.EventArgs) Handles Button1.Click
        If isExecuting Then
            MessageBox.Show(Me, "Already executing. Please wait until the current query " & _
             "has completed.")
        Else
            Dim connection As SqlConnection
            Dim command As SqlCommand
            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.
                Dim callback As New AsyncCallback(AddressOf HandleCallback)
                command.BeginExecuteReader(callback, command, _
                  CommandBehavior.CloseConnection)

            Catch ex As Exception
                DisplayStatus("Error: " & ex.Message)
                If connection IsNot Nothing Then
                    connection.Close()
                End If
            End Try
        End If
    End Sub

    Private Sub Form1_FormClosing(ByVal sender As Object, _
        ByVal e As System.Windows.Forms.FormClosingEventArgs) Handles Me.FormClosing
        If isExecuting Then
            MessageBox.Show(Me, "Cannot close the form until " & _
             "the pending asynchronous command has completed. Please wait...")
            e.Cancel = True
        End If
    End Sub
End Class

注解

BeginExecuteReader方法启动异步执行 transact-sql 语句或返回行的存储过程的过程,以便在执行语句时可以同时运行其他任务。The 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. 完成语句后,开发人员必须调用 EndExecuteReader 方法以完成操作并检索 SqlDataReader 命令返回的。When the statement has completed, developers must call the EndExecuteReader method to finish the operation and retrieve the SqlDataReader returned by the command. BeginExecuteReader方法会立即返回,但在代码执行相应的 EndExecuteReader 方法调用之前,不能执行对同一对象启动同步或异步执行的任何其他调用 SqlCommandThe BeginExecuteReader method returns immediately, but until the code executes the corresponding EndExecuteReader method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same SqlCommand object. EndExecuteReader 命令的执行完成之前调用,将导致 SqlCommand 对象被阻止,直到执行完成。Calling the EndExecuteReader before the command's execution is completed causes the SqlCommand object to block until the execution is finished.

使用 callback 参数可以指定在 AsyncCallback 语句完成时调用的委托。The callback parameter lets you specify an AsyncCallback delegate that is called when the statement has completed. 你可以 EndExecuteReader 从该委托过程或应用程序中的任何其他位置调用此方法。You can call the EndExecuteReader method from within this delegate procedure, or from any other location within your application. 此外,可以传递参数中的任何对象 stateObject ,并且回调过程可以使用属性检索此信息 AsyncStateIn addition, you can pass any object in the stateObject parameter, and your callback procedure can retrieve this information using the AsyncState property.

behavior参数使你可以指定控制命令的行为及其连接的选项。The behavior parameter lets you specify options that control the behavior of the command and its connection. 使用编程语言的运算符) ,这些值可以组合在一起 (Or ; 通常情况下,开发人员使用 CloseConnection 该值以确保在关闭时,运行时关闭连接 SqlDataReaderThese values can be combined together (using the programming language's Or operator); generally, developers use the CloseConnection value to make sure that the connection is closed by the runtime when the SqlDataReader is closed. 开发人员还可以 SqlDataReader 通过在 SingleRow 事先知道 transact-sql 语句或存储过程只返回单个行时指定值来优化的行为。Developers can also optimize the behavior of the SqlDataReader by specifying the SingleRow value when it is known in advance that the Transact-SQL statement or stored procedure only returns a single row.

请注意,命令文本和参数同步发送到服务器。Note that the command text and parameters are sent to the server synchronously. 如果发送了大命令或多个参数,则此方法可能会在写入过程中被阻止。If a large command or many parameters are sent, this method may block during writes. 发送命令后,该方法立即返回,而不会等待来自服务器的应答,也就是说,读取是异步的。After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. 尽管命令执行是异步的,但值提取仍同步。Although command execution is asynchronous, value fetching is still synchronous. 这意味着, Read 如果需要更多的数据和基础网络的读取操作,则对的调用可能会阻止。This means that calls to Read may block if more data is required and the underlying network's read operation blocks.

由于回调过程是从 Microsoft .NET 公共语言运行时提供的后台线程中执行的,因此,必须采用一种严格的方法来处理应用程序内的跨线程交互。Because the callback procedure executes from within a background thread supplied by the Microsoft .NET common language runtime, it is very important that you take a rigorous approach to handling cross-thread interactions from within your applications. 例如,你不能在回调过程中与窗体内容交互,如果必须更新窗体,则必须切换回窗体的线程才能执行你的工作。For example, you must not interact with a form's contents from within your callback procedure--should you have to update the form, you must switch back to the form's thread in order to do your work. 本主题中的示例演示了此行为。The example in this topic demonstrates this behavior.

在执行操作过程中发生的所有错误都作为回调过程中的异常引发。All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. 必须在回调过程中处理异常,而不是在主应用程序中处理。You must handle the exception in the callback procedure, not in the main application. 请参阅本主题中的示例,了解有关在回调过程中处理异常的其他信息。See the example in this topic for additional information on handling exceptions in the callback procedure.

如果使用 ExecuteReaderBeginExecuteReader 访问 XML 数据,SQL Server 将返回长度超过2033个字符的任何 XML 结果,其中每个行的长度为2033个字符。If you use ExecuteReader or 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. 若要避免此行为,请使用 ExecuteXmlReaderBeginExecuteXmlReader 来读取 FOR XML 查询。To avoid this behavior, use ExecuteXmlReader or BeginExecuteXmlReader to read FOR XML queries.

此方法将忽略 CommandTimeout 属性。This method ignores the CommandTimeout property.

适用于