SqlCommand.BeginExecuteNonQuery メソッド

public:
 IAsyncResult ^ BeginExecuteNonQuery();

public IAsyncResult BeginExecuteNonQuery ();

member this.BeginExecuteNonQuery : unit -> IAsyncResult

Public Function BeginExecuteNonQuery () As IAsyncResult

戻り値

IAsyncResult結果のポーリングまたは待機に使用できる 。この値は、 を呼び出すときにも必要です。この値は、影響をEndExecuteNonQuery(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.

例

次のコンソール アプリケーションは、 AdventureWorks サンプル データベース内に更新データを作成し、その処理を非同期的に実行します。 この例では、実行時間の長いプロセスをエミュレートする目的で、コマンド テキストに WAITFOR ステートメントを挿入します。 通常、コマンドの実行速度を低下させる作業は行いませんが、この場合は非同期動作を簡単に示すことができます。

// <Snippet1>
using System;
using System.Data;
using Microsoft.Data.SqlClient;

class Class1
{
    static void Main()
    {
        // This is a simple example that demonstrates the usage of the 
        // BeginExecuteNonQuery functionality.
        // The WAITFOR statement simply adds enough time to prove the 
        // asynchronous nature of the command.

        string commandText =
            "UPDATE Production.Product SET ReorderPoint = ReorderPoint + 1 " +
            "WHERE ReorderPoint Is Not Null;" +
            "WAITFOR DELAY '0:0:3';" +
            "UPDATE Production.Product SET ReorderPoint = ReorderPoint - 1 " +
            "WHERE ReorderPoint Is Not Null";

        RunCommandAsynchronously(commandText, GetConnectionString());

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

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

                IAsyncResult result = command.BeginExecuteNonQuery();
                while (!result.IsCompleted)
                {
                    Console.WriteLine("Waiting ({0})", count++);
                    // Wait for 1/10 second, so the counter
                    // does not consume all available resources 
                    // on the main thread.
                    System.Threading.Thread.Sleep(100);
                }
                Console.WriteLine("Command complete. Affected {0} rows.",
                    command.EndExecuteNonQuery(result));
            }
            catch (SqlException ex)
            {
                Console.WriteLine("Error ({0}): {1}", ex.Number, ex.Message);
            }
            catch (InvalidOperationException ex)
            {
                Console.WriteLine("Error: {0}", ex.Message);
            }
            catch (Exception ex)
            {
                // You might want to pass these errors
                // back out to the caller.
                Console.WriteLine("Error: {0}", ex.Message);
            }
        }
    }

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

        return "Data Source=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}
// </Snippet1>

注釈

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

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

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

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

public:
 IAsyncResult ^ BeginExecuteNonQuery(AsyncCallback ^ callback, System::Object ^ stateObject);

public IAsyncResult BeginExecuteNonQuery (AsyncCallback callback, object stateObject);

member this.BeginExecuteNonQuery : AsyncCallback * obj -> IAsyncResult

Public Function BeginExecuteNonQuery (callback As AsyncCallback, stateObject As Object) As IAsyncResult

パラメーター

戻り値

IAsyncResult結果のポーリングまたは待機に使用できる 。この値は、 を呼び出すときにも必要です。この値は、影響をEndExecuteNonQuery(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 アプリケーションは、 メソッドを使用して、数秒の遅延 (実行時間の BeginExecuteNonQuery 長いコマンドをエミュレート) を含む Transact-SQL ステートメントを実行する方法を示しています。

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

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

// <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 Microsoft.AdoDotNet.CodeSamples
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        // Hook up the form's Load event handler (you can double-click on 
        // the form's design surface in Visual Studio), and then add 
        // this code to the form's class:
        private void Form1_Load(object sender, EventArgs e)
        {
            this.button1.Click += new System.EventHandler(this.button1_Click);
            this.FormClosing += new System.Windows.Forms.
                FormClosingEventHandler(this.Form1_FormClosing);

        }

        // You need this delegate in order to display text from a thread
        // other than the form's thread. See the HandleCallback
        // procedure for more information.
        // This same delegate matches both the DisplayStatus 
        // and DisplayResults methods.
        private delegate void DisplayInfoDelegate(string Text);

        // This flag ensures that the user does not attempt
        // to restart the command or close the form while the 
        // asynchronous command is executing.
        private bool isExecuting;

        // This example maintains the connection object 
        // externally, so that it is available for closing.
        private SqlConnection connection;

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

            return "Data Source=(local);Integrated Security=true;" +
                "Initial Catalog=AdventureWorks";
        }

        private void DisplayStatus(string Text)
        {
            this.label1.Text = Text;
        }

        private void DisplayResults(string Text)
        {
            this.label1.Text = Text;
            DisplayStatus("Ready");
        }

        private void Form1_FormClosing(object sender,
            System.Windows.Forms.FormClosingEventArgs e)
        {
            if (isExecuting)
            {
                MessageBox.Show(this, "Cannot close the form until " +
                    "the pending asynchronous command has completed. Please wait...");
                e.Cancel = true;
            }
        }

        private void button1_Click(object sender, System.EventArgs e)
        {
            if (isExecuting)
            {
                MessageBox.Show(this,
                    "Already executing. Please wait until the current query " +
                    "has completed.");
            }
            else
            {
                SqlCommand command = null;
                try
                {
                    DisplayResults("");
                    DisplayStatus("Connecting...");
                    connection = new SqlConnection(GetConnectionString());
                    // To emulate a long-running query, wait for 
                    // a few seconds before working with the data.
                    // This command does not do much, but that's the point--
                    // it does not change your data, in the long run.
                    string commandText =
                        "WAITFOR DELAY '0:0:05';" +
                        "UPDATE Production.Product SET ReorderPoint = ReorderPoint + 1 " +
                        "WHERE ReorderPoint Is Not Null;" +
                        "UPDATE Production.Product SET ReorderPoint = ReorderPoint - 1 " +
                        "WHERE ReorderPoint Is Not Null";

                    command = new SqlCommand(commandText, connection);
                    connection.Open();

                    DisplayStatus("Executing...");
                    isExecuting = true;
                    // Although it is not required that you pass the 
                    // SqlCommand object as the second parameter in the 
                    // BeginExecuteNonQuery call, doing so makes it easier
                    // to call EndExecuteNonQuery in the callback procedure.
                    AsyncCallback callback = new AsyncCallback(HandleCallback);
                    command.BeginExecuteNonQuery(callback, command);

                }
                catch (Exception ex)
                {
                    isExecuting = false;
                    DisplayStatus(string.Format("Ready (last error: {0})", ex.Message));
                    if (connection != null)
                    {
                        connection.Close();
                    }
                }
            }
        }

        private void HandleCallback(IAsyncResult result)
        {
            try
            {
                // Retrieve the original command object, passed
                // to this procedure in the AsyncState property
                // of the IAsyncResult parameter.
                SqlCommand command = (SqlCommand)result.AsyncState;
                int rowCount = command.EndExecuteNonQuery(result);
                string rowText = " rows affected.";
                if (rowCount == 1)
                {
                    rowText = " row affected.";
                }
                rowText = rowCount + rowText;

                // You may not interact with the form and its contents
                // from a different thread, and this callback procedure
                // is all but guaranteed to be running from a different thread
                // than the form. Therefore you cannot simply call code that 
                // displays the results, like this:
                // DisplayResults(rowText)

                // Instead, you must call the procedure from the form's thread.
                // One simple way to accomplish this is to call the Invoke
                // method of the form, which calls the delegate you supply
                // from the form's thread. 
                DisplayInfoDelegate del = new DisplayInfoDelegate(DisplayResults);
                this.Invoke(del, rowText);

            }
            catch (Exception ex)
            {
                // Because you are now running code in a separate thread, 
                // if you do not handle the exception here, none of your other
                // code catches the exception. Because none of 
                // your code is on the call stack in this thread, there is nothing
                // higher up the stack to catch the exception if you do not 
                // handle it here. You can either log the exception or 
                // invoke a delegate (as in the non-error case in this 
                // example) to display the error on the form. In no case
                // can you simply display the error without executing a delegate
                // as in the try block here. 

                // You can create the delegate instance as you 
                // invoke it, like this:
                this.Invoke(new DisplayInfoDelegate(DisplayStatus),
                    String.Format("Ready(last error: {0}", ex.Message));
            }
            finally
            {
                isExecuting = false;
                if (connection != null)
                {
                    connection.Close();
                }
            }
        }
    }
}
// </Snippet1>

注釈

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

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

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

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

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

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