SqlCommand.BeginExecuteXmlReader メソッド

public:
 IAsyncResult ^ BeginExecuteXmlReader();

public IAsyncResult BeginExecuteXmlReader ();

member this.BeginExecuteXmlReader : unit -> IAsyncResult

Public Function BeginExecuteXmlReader () As IAsyncResult

戻り値

IAsyncResult結果をポーリングまたは待機するために使用できる 。この値は、 を呼び出すときにも必要です。EndExecuteXmlReader は、単一の XML 値を返します。

例外

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

例

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

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

注釈

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

プロパティは CommandText 通常、有効な FOR XML 句を持つ Transact-SQL ステートメントを指定します。 ただし、 CommandText 有効な XML を含むデータを ntext 返すステートメントを指定することもできます。

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

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

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

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

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

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

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

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

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

public IAsyncResult BeginExecuteXmlReader (AsyncCallback callback, object stateObject);

member this.BeginExecuteXmlReader : AsyncCallback * obj -> IAsyncResult

Public Function BeginExecuteXmlReader (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できるため、コードは へのBeginExecuteXmlReader最初の呼び出しに対応する メソッドを呼び出EndExecuteXmlReaderすことができます。

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

この例を設定するには、新しい Windows アプリケーションを作成します。 フォームに Button コントロール、 ListBox コントロール、およびコントロールを 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;
using System.Xml;

namespace Microsoft.AdoDotNet.CodeSamples
{
    public partial class Form1 : Form
    {
        // Hook up the form's Load event handler and then add 
        // this code to the form's class:
        // You need these delegates in order to display text from a thread
        // other than the form's thread. See the HandleCallback
        // procedure for more information.
        private delegate void DisplayInfoDelegate(string Text);
        private delegate void DisplayReaderDelegate(XmlReader reader);

        private bool isExecuting;

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

        public Form1()
        {
            InitializeComponent();
        }

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

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

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

        private void ClearProductInfo()
        {
            // Clear the list box.
            this.listBox1.Items.Clear();
        }

        private void DisplayProductInfo(XmlReader reader)
        {
            // Display the data within the reader.
            while (reader.Read())
            {
                // Skip past items that are not from the correct table.
                if (reader.LocalName.ToString() == "Production.Product")
                {
                    this.listBox1.Items.Add(String.Format("{0}: {1:C}",
                        reader["Name"], Convert.ToDecimal(reader["ListPrice"])));
                }
            }
            DisplayStatus("Ready");
        }

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

        private void button1_Click(object sender, System.EventArgs e)
        {
            if (isExecuting)
            {
                MessageBox.Show(this,
                    "Already executing. Please wait until the current query " +
                    "has completed.");
            }
            else
            {
                SqlCommand command = null;
                try
                {
                    ClearProductInfo();
                    DisplayStatus("Connecting...");
                    connection = new SqlConnection(GetConnectionString());

                    // To emulate a long-running query, wait for 
                    // a few seconds before working with the data.
                    string commandText =
                        "WAITFOR DELAY '00:00:03';" +
                        "SELECT Name, ListPrice FROM Production.Product " +
                        "WHERE ListPrice < 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 取得できます。

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

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

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

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

こちらもご覧ください

• EndExecuteXmlReader(IAsyncResult)
• ExecuteXmlReader()