SqlCommand.BeginExecuteReader メソッド

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

public:
 IAsyncResult ^ BeginExecuteReader();

public IAsyncResult BeginExecuteReader();

member this.BeginExecuteReader : unit -> IAsyncResult

Public Function BeginExecuteReader () As IAsyncResult

返品

結果またはその両方をポーリングまたは待機するために使用できるIAsyncResult。この値は、返された行を取得するために使用できるEndExecuteReader(IAsyncResult) インスタンスを返すSqlDataReaderを呼び出すときにも必要です。

例外

例

次のコンソール アプリケーションは、データ リーダーを非同期的に取得するプロセスを開始します。 結果を待っている間、この単純なアプリケーションはループ内にあり、 IsCompleted プロパティ値を調査します。 プロセスが完了するとすぐに、コードは SqlDataReader を取得し、その内容を表示します。

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 < 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";
    }
}

注釈

BeginExecuteReader() メソッドは、行を返す Transact-SQL ステートメントまたはストアド プロシージャを非同期的に実行するプロセスを開始し、ステートメントの実行中に他のタスクを同時に実行できるようにします。 ステートメントが完了したら、開発者は EndExecuteReader(IAsyncResult) メソッドを呼び出して操作を完了し、コマンドによって返された SqlDataReader を取得する必要があります。 BeginExecuteReader() メソッドはすぐに戻りますが、コードが対応するEndExecuteReader(IAsyncResult) メソッド呼び出しを実行するまで、同じSqlCommand オブジェクトに対して同期または非同期の実行を開始する他の呼び出しを実行してはなりません。 コマンドの実行が完了する前に EndExecuteReader(IAsyncResult) を呼び出すと、 SqlCommand オブジェクトは実行が完了するまでブロックされます。

コマンド テキストとパラメーターがサーバーに同期的に送信されることに注意してください。 大きなコマンドまたは多数のパラメーターが送信された場合、このメソッドは書き込み中にブロックされる可能性があります。 コマンドの送信後、メソッドはサーバーからの応答を待たずにすぐに戻ります。つまり、読み取りは非同期です。 コマンドの実行は非同期ですが、値のフェッチは引き続き同期的です。 つまり、より多くのデータが必要で、基になるネットワークの読み取り操作がブロックされると、 Read() の呼び出しがブロックされる可能性があります。

このオーバーロードはコールバック プロシージャをサポートしていないため、開発者は、IsCompleted メソッドによって返されたIAsyncResultのBeginExecuteReader() プロパティを使用して、コマンドが完了したかどうかを判断するためにポーリングするか、返されたAsyncWaitHandleのIAsyncResult プロパティを使用して 1 つ以上のコマンドが完了するのを待つ必要があります。

ExecuteReader()またはBeginExecuteReader()を使用して XML データにアクセスする場合、SQL Server は長さが 2,033 文字を超える XML 結果を、それぞれ 2,033 文字の複数行で返します。 この動作を回避するには、 ExecuteXmlReader() または BeginExecuteXmlReader() を使用して FOR XML クエリを読み取ります。

このメソッドは、 CommandTimeout プロパティを無視します。

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

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

パラメーター

返品

ポーリング、結果の待機、またはその両方に使用できるIAsyncResult。この値は、返された行を取得するために使用できるEndExecuteReader(IAsyncResult) インスタンスを返すSqlDataReaderを呼び出すときにも必要です。

例外

例

次のコンソール アプリケーションは、データ リーダーを非同期的に取得するプロセスを開始します。 結果を待っている間、この単純なアプリケーションはループ内にあり、 IsCompleted プロパティ値を調査します。 プロセスが完了すると、コードは SqlDataReader を取得し、その内容を表示します。

この例では、動作パラメーターに CloseConnection 値と SingleRow 値も渡し、返された SqlDataReader を閉じて接続を閉じ、1 行の結果を最適化します。

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 < 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.
        return "Data Source=(local);Integrated Security=true;" +
               "Initial Catalog=AdventureWorks";
    }
}

注釈

BeginExecuteReader() メソッドは、行を返す Transact-SQL ステートメントまたはストアド プロシージャを非同期的に実行するプロセスを開始し、ステートメントの実行中に他のタスクを同時に実行できるようにします。 ステートメントが完了したら、開発者は EndExecuteReader(IAsyncResult) メソッドを呼び出して操作を完了し、コマンドによって返された SqlDataReader を取得する必要があります。 BeginExecuteReader() メソッドはすぐに戻りますが、コードが対応するEndExecuteReader(IAsyncResult) メソッド呼び出しを実行するまで、同じSqlCommand オブジェクトに対して同期または非同期の実行を開始する他の呼び出しを実行してはなりません。 コマンドの実行が完了する前に EndExecuteReader(IAsyncResult) を呼び出すと、 SqlCommand オブジェクトは実行が完了するまでブロックされます。

behavior パラメーターを使用すると、コマンドとその接続の動作を制御するオプションを指定できます。 これらの値は (プログラミング言語の OR 演算子を使用して) 組み合わせることができます。通常、開発者は CommandBehavior.CloseConnection 値を使用して、 SqlDataReader が閉じられたときにランタイムによって接続が閉じられているようにします。

コマンド テキストとパラメーターがサーバーに同期的に送信されることに注意してください。 大きなコマンドまたは多数のパラメーターが送信された場合、このメソッドは書き込み中にブロックされる可能性があります。 コマンドの送信後、メソッドはサーバーからの応答を待たずにすぐに戻ります。つまり、読み取りは非同期です。 コマンドの実行は非同期ですが、値のフェッチは引き続き同期的です。 つまり、より多くのデータが必要で、基になるネットワークの読み取り操作がブロックされると、 Read() の呼び出しがブロックされる可能性があります。

このオーバーロードはコールバック プロシージャをサポートしていないため、開発者は、IsCompleted メソッドによって返されたIAsyncResultのBeginExecuteNonQuery() プロパティを使用して、コマンドが完了したかどうかを判断するためにポーリングするか、返されたAsyncWaitHandleのIAsyncResult プロパティを使用して 1 つ以上のコマンドが完了するのを待つ必要があります。

またはを使用して XML データにアクセスする場合、SQL Server は長さが 2,033 文字を超える XML 結果をそれぞれ 2,033 文字の複数行で返します。 この動作を回避するには、 ExecuteXmlReader() または BeginExecuteXmlReader() を使用して FOR XML クエリを読み取ります。

このメソッドは、 CommandTimeout プロパティを無視します。

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

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

パラメーター

返品

ポーリング、結果の待機、またはその両方に使用できる IAsyncResult 。この値は、コマンドの結果を XML として返す EndExecuteXmlReader(IAsyncResult) が呼び出されたときにも必要です。

例外

- or -

<xref data-throw-if-not-resolved="true" uid="Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding"></xref>
is set to true and a parameter with direction Output or InputOutput has been added to the <xref data-throw-if-not-resolved="true" uid="Microsoft.Data.SqlClient.SqlCommand.Parameters"></xref> collection.

例

次の Windows アプリケーションは、BeginExecuteXmlReader メソッドを使用して、数秒の遅延を含む Transact-SQL ステートメントを実行する方法 (実行時間の長いコマンドのエミュレーション) を示しています。 この例では、実行中のSqlCommand オブジェクトを stateObject パラメーターとして渡します。そのため、コールバック プロシージャ内からSqlCommand オブジェクトを簡単に取得できるため、コードは、EndExecuteXmlReaderの最初の呼び出しに対応するBeginExecuteXmlReader メソッドを呼び出すことができます。

この例では、多くの重要な手法を示します。 これには、別のスレッドからフォームと対話するメソッドの呼び出しが含まれます。 さらに、この例では、ユーザーがコマンドを複数回同時に実行できないようにする方法と、コールバック プロシージャが呼び出される前にフォームが閉じないようにする方法を示します。

この例を設定するには、新しい Windows アプリケーションを作成します。 フォームに Button コントロール、 ListBox コントロール、および Label コントロールを配置します (各コントロールの既定の名前を受け入れます)。 次のコードをフォームのクラスに追加し、環境に合わせて接続文字列を変更します。

/* This does not compile, as multiple methods are missing.
// <Snippet1>
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;
using System.Xml;

namespace SqlCommand_BeginExecuteXmlReaderAsync
{
    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 < 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);
        }
    }
}
// </Snippet1>
*/

注釈

BeginExecuteXmlReader メソッドは、行を XML として返す Transact-SQL ステートメントまたはストアド プロシージャを非同期的に実行するプロセスを開始します。そのため、ステートメントの実行中に他のタスクを同時に実行できます。 ステートメントが完了したら、開発者は EndExecuteXmlReader メソッドを呼び出して操作を完了し、要求された XML データを取得する必要があります。 BeginExecuteXmlReader メソッドはすぐに戻りますが、コードが対応するEndExecuteXmlReader メソッド呼び出しを実行するまで、同じSqlCommand オブジェクトに対して同期または非同期の実行を開始する他の呼び出しを実行してはなりません。 コマンドの実行が完了する前に EndExecuteXmlReader を呼び出すと、 SqlCommand オブジェクトは実行が完了するまでブロックされます。

CommandText プロパティは、通常、有効な FOR XML 句を持つ Transact-SQL ステートメントを指定します。 ただし、 CommandText は、有効な XML を含むデータを返すステートメントを指定することもできます。 このメソッドを使用して、単一行の単一列の結果セットを取得することもできます。 この場合、複数の行が返された場合、 EndExecuteXmlReader メソッドは最初の行の値に XmlReader をアタッチし、結果セットの残りの部分を破棄します。

一般的な BeginExecuteXmlReader クエリは、次の C# の例のように書式設定できます。

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

このメソッドを使用して、単一行の単一列の結果セットを取得することもできます。 この場合、複数の行が返された場合、 EndExecuteXmlReader メソッドは最初の行の値に XmlReader をアタッチし、結果セットの残りの部分を破棄します。

複数のアクティブな結果セット (MARS) 機能を使用すると、複数のアクションで同じ接続を使用できます。

callback パラメーターを使用すると、ステートメントの完了時に呼び出されるAsyncCallbackデリゲートを指定できます。 EndExecuteXmlReader メソッドは、このデリゲート プロシージャ内から、またはアプリケーション内の他の任意の場所から呼び出すことができます。 さらに、 stateObject パラメーターに任意のオブジェクトを渡すことができます。コールバック プロシージャは、 AsyncState プロパティを使用してこの情報を取得できます。

コマンド テキストとパラメーターがサーバーに同期的に送信されることに注意してください。 大きなコマンドまたは多数のパラメーターが送信された場合、このメソッドは書き込み中にブロックされる可能性があります。 コマンドが送信されると、メソッドはサーバーからの応答を待たずにすぐに戻ります。つまり、読み取りは非同期です。

操作の実行中に発生するすべてのエラーは、コールバック プロシージャの例外としてスローされます。 メイン アプリケーションではなく、コールバック プロシージャで例外を処理する必要があります。 コールバック プロシージャの例外処理の詳細については、このトピックの例を参照してください。

ExecuteReaderまたはBeginExecuteReaderを使用して XML データにアクセスする場合、SQL Server は長さが 2,033 文字を超える XML 結果を、それぞれ 2,033 文字の複数行で返します。 この動作を回避するには、 ExecuteXmlReader または BeginExecuteXmlReader を使用して FOR XML クエリを読み取ります。

このメソッドは、 CommandTimeout プロパティを無視します。

こちらもご覧ください

• EndExecuteXmlReader(IAsyncResult)
• ExecuteXmlReader()

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

ソース:

SqlCommand.cs

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

パラメーター

返品

結果またはその両方をポーリングまたは待機するために使用できるIAsyncResult。この値は、返された行を取得するために使用できるSqlDataReader インスタンスを返すEndExecuteReader(IAsyncResult)を呼び出すときにも必要です。

例外

- or -

<xref data-throw-if-not-resolved="true" uid="Microssoft.Data.SqlClient.SqlCommand.EnableOptimizedParameterBinding"></xref>
is set to true and a parameter with direction Output or InputOutput has been added to the <xref data-throw-if-not-resolved="true" uid="Microsoft.Data.SqlClient.SqlCommand.Parameters"></xref> collection.

例

次の Windows アプリケーションは、BeginExecuteReader メソッドを使用して、数秒の遅延を含む Transact-SQL ステートメントを実行する方法 (実行時間の長いコマンドのエミュレーション) を示しています。 サンプルはコマンドを非同期的に実行するため、結果を待機している間もフォームの応答性は維持されます。 この例では、実行中のSqlCommand オブジェクトを stateObject パラメーターとして渡します。これにより、コールバック プロシージャ内からSqlCommand オブジェクトを簡単に取得できるため、コードはEndExecuteReaderの最初の呼び出しに対応するBeginExecuteReader メソッドを呼び出すことができます。

この例では、多くの重要な手法を示します。 これには、別のスレッドからフォームと対話するメソッドの呼び出しが含まれます。 さらに、この例では、ユーザーがコマンドを複数回同時に実行できないようにする方法と、コールバック プロシージャが呼び出される前にフォームが閉じないようにする方法を示します。

この例を設定するには、新しい Windows アプリケーションを作成します。 フォームに Button コントロール、 DataGridView コントロール、および Label コントロールを配置します (各コントロールの既定の名前を受け入れます)。 次のコードをフォームのクラスに追加し、環境に合わせて接続文字列を変更します。

次の使用例は、CommandBehavior.CloseConnection パラメーターにbehavior値を渡し、返されたSqlDataReaderが閉じられたときに接続を自動的に閉じます。

#if NETFRAMEWORK
#nullable enable

// <Snippet1>
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 SqlCommand_BeginExecuteReaderAsyncBehavior
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            this.label1 = new Label();
            this.dataGridView1 = new DataGridView();
            this.button1 = new Button();
        }

        private void 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 Label label1 { get; set; }

        private DataGridView dataGridView1 { get; set; }

        private Button button1 { get; set; }

        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;
            }
        }
    }
}
// </Snippet1>
#endif

注釈

BeginExecuteReader メソッドは、行を返す Transact-SQL ステートメントまたはストアド プロシージャを非同期的に実行するプロセスを開始し、ステートメントの実行中に他のタスクを同時に実行できるようにします。 ステートメントが完了したら、開発者は EndExecuteReader メソッドを呼び出して操作を完了し、コマンドによって返された SqlDataReader を取得する必要があります。 BeginExecuteReader メソッドはすぐに戻りますが、コードが対応するEndExecuteReader メソッド呼び出しを実行するまで、同じSqlCommand オブジェクトに対して同期または非同期の実行を開始する他の呼び出しを実行してはなりません。 コマンドの実行が完了する前に EndExecuteReader を呼び出すと、 SqlCommand オブジェクトは実行が完了するまでブロックされます。

callback パラメーターを使用すると、ステートメントの完了時に呼び出されるAsyncCallbackデリゲートを指定できます。 EndExecuteReader メソッドは、このデリゲート プロシージャ内から、またはアプリケーション内の他の任意の場所から呼び出すことができます。 さらに、 stateObject パラメーターに任意のオブジェクトを渡すことができます。コールバック プロシージャは、 AsyncState プロパティを使用してこの情報を取得できます。

behavior パラメーターを使用すると、コマンドとその接続の動作を制御するオプションを指定できます。 これらの値は (プログラミング言語の Or 演算子を使用して) 組み合わせることができます。通常、開発者は CloseConnection 値を使用して、 SqlDataReader が閉じられたときにランタイムによって接続が閉じられているようにします。 開発者は、Transact-SQL ステートメントまたはストアド プロシージャが単一の行のみを返すことがわかっている場合にSqlDataReader値を指定することで、SingleRowの動作を最適化することもできます。

コマンド テキストとパラメーターがサーバーに同期的に送信されることに注意してください。 大きなコマンドまたは多数のパラメーターが送信された場合、このメソッドは書き込み中にブロックされる可能性があります。 コマンドが送信されると、メソッドはサーバーからの応答を待たずにすぐに戻ります。つまり、読み取りは非同期です。 コマンドの実行は非同期ですが、値のフェッチは引き続き同期的です。 つまり、より多くのデータが必要で、基になるネットワークの読み取り操作がブロックされると、 Read の呼び出しがブロックされる可能性があります。

コールバック プロシージャは、Microsoft .NET 共通言語ランタイムによって提供されるバックグラウンド スレッド内から実行されるため、アプリケーション内からスレッド間の相互作用を処理するための厳密なアプローチを採用することが非常に重要です。 たとえば、コールバック プロシージャ内からフォームの内容を操作することはできません。フォームを更新する必要がある場合は、作業を行うためにフォームのスレッドに戻す必要があります。 このトピックの例では、この動作を示します。

操作の実行中に発生するすべてのエラーは、コールバック プロシージャの例外としてスローされます。 メイン アプリケーションではなく、コールバック プロシージャで例外を処理する必要があります。 コールバック プロシージャの例外処理の詳細については、このトピックの例を参照してください。

ExecuteReaderまたはBeginExecuteReaderを使用して XML データにアクセスする場合、SQL Server は長さが 2,033 文字を超える XML 結果を、それぞれ 2,033 文字の複数行で返します。 この動作を回避するには、 ExecuteXmlReader または BeginExecuteXmlReader を使用して FOR XML クエリを読み取ります。

このメソッドは、 CommandTimeout プロパティを無視します。