SqlCommand.BeginExecuteXmlReader Metoda
Definicja
Ważne
Niektóre informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany przed wydaniem. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.
Przeciążenia
| BeginExecuteXmlReader() |
Inicjuje asynchroniczne wykonywanie instrukcji Transact-SQL lub procedury składowanej opisanej w tym temacie SqlCommand i zwraca wyniki jako XmlReader obiekt. |
| BeginExecuteXmlReader(AsyncCallback, Object) |
Inicjuje asynchroniczne wykonywanie instrukcji Transact-SQL lub procedury składowanej opisanej w tym SqlCommand temacie i zwraca wyniki jako XmlReader obiekt przy użyciu procedury wywołania zwrotnego. |
BeginExecuteXmlReader()
Inicjuje asynchroniczne wykonywanie instrukcji Transact-SQL lub procedury składowanej opisanej w tym temacie SqlCommand i zwraca wyniki jako XmlReader obiekt.
public:
IAsyncResult ^ BeginExecuteXmlReader();public IAsyncResult BeginExecuteXmlReader ();member this.BeginExecuteXmlReader : unit -> IAsyncResultPublic Function BeginExecuteXmlReader () As IAsyncResultZwraca
Element IAsyncResult , który może służyć do sondowania lub oczekiwania na wyniki albo obu tych wyników. Ta wartość jest również potrzebna podczas wywoływaniaEndExecuteXmlReader , która zwraca pojedynczą wartość XML.
Wyjątki
Użyto SqlDbType innego elementu niż Binary lub VarBinary , gdy Value ustawiono wartość Stream . Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
-lub-
Użyto SqlDbType innego niż Char, NChar, NVarChar, VarChar lub Xml, gdy Value ustawiono wartość TextReader .
-lub-
Inny SqlDbType niż Xml był używany, gdy Value ustawiono wartość XmlReader .
Wszelkie błędy, które wystąpiły podczas wykonywania tekstu polecenia.
-lub-
Wystąpił limit czasu podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
Zamknięty SqlConnection lub porzucony podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
- 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.
Wystąpił błąd w StreamXmlReader obiekcie lub TextReader podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
XmlReader Obiekt Stream lub TextReader został zamknięty podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
Przykłady
Poniższa aplikacja konsolowa uruchamia proces pobierania danych XML asynchronicznie. Czekając na wyniki, ta prosta aplikacja znajduje się w pętli, badając IsCompleted wartość właściwości. Po zakończeniu procesu kod pobiera kod XML i wyświetla jego zawartość.
[!code-csharp[SqlCommand_BeginExecuteXmlReader#1]((~/.). /sqlclient/doc/samples/SqlCommand_BeginExecuteXmlReader.cs)]
Uwagi
Metoda BeginExecuteXmlReader uruchamia proces asynchronicznego wykonywania instrukcji Języka Transact-SQL zwracającej wiersze jako XML, dzięki czemu inne zadania mogą być uruchamiane współbieżnie podczas wykonywania instrukcji. Po zakończeniu instrukcji deweloperzy muszą wywołać metodę EndExecuteXmlReader , aby zakończyć operację i pobrać kod XML zwrócony przez polecenie . Metoda BeginExecuteXmlReader jest zwracana natychmiast, ale dopóki kod nie wykona odpowiedniego EndExecuteXmlReader wywołania metody, nie może wykonać żadnych innych wywołań, które rozpoczynają wykonywanie synchroniczne lub asynchroniczne względem tego samego SqlCommand obiektu. EndExecuteXmlReader Wywołanie polecenia przed wykonaniem polecenia powoduje SqlCommand zablokowanie obiektu do momentu zakończenia wykonywania.
Właściwość CommandText zwykle określa instrukcję Transact-SQL z prawidłową klauzulą FOR XML. CommandText Można jednak również określić instrukcję zwracającą dane zawierające ntext prawidłowy kod XML.
Typowe BeginExecuteXmlReader zapytanie można sformatować tak, jak w poniższym przykładzie języka C#:
SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM dbo.Contact FOR XML AUTO, XMLDATA", SqlConn);
Ta metoda może również służyć do pobierania zestawu wyników z jednym wierszem, jednokolumna kolumna. W takim przypadku, jeśli zostanie zwrócony więcej niż jeden wiersz, EndExecuteXmlReader metoda dołącza XmlReader wartość do wartości w pierwszym wierszu i odrzuca resztę zestawu wyników.
Funkcja wielu aktywnych zestawów wyników (MARS) umożliwia korzystanie z tego samego połączenia przez wiele akcji.
Należy pamiętać, że tekst polecenia i parametry są wysyłane do serwera synchronicznie. Jeśli jest wysyłane duże polecenie lub wiele parametrów, ta metoda może blokować podczas zapisu. Po wysłaniu polecenia metoda zwraca natychmiast bez oczekiwania na odpowiedź z serwera — czyli odczyty są asynchroniczne. Mimo że wykonywanie poleceń jest asynchroniczne, pobieranie wartości jest nadal synchroniczne.
Ponieważ to przeciążenie nie obsługuje procedury wywołania zwrotnego, deweloperzy muszą sondować, czy polecenie zostało ukończone, używając właściwości zwracanej przez BeginExecuteXmlReader metodę, lub poczekać na ukończenie co najmniej jednego polecenia przy użyciu AsyncWaitHandleIsCompleted właściwości zwróconej IAsyncResult.IAsyncResult
Jeśli używasz ExecuteReader danych XML lub BeginExecuteReader uzyskujesz dostęp do nich, SQL Server zwraca wyniki XML większe niż 2033 znaki w wielu wierszach o długości 2033 znaków. Aby uniknąć tego zachowania, użyj ExecuteXmlReader polecenia lub BeginExecuteXmlReader odczytu dla zapytań XML.
Ta metoda ignoruje CommandTimeout właściwość .
Dotyczy
BeginExecuteXmlReader(AsyncCallback, Object)
Inicjuje asynchroniczne wykonywanie instrukcji Transact-SQL lub procedury składowanej opisanej w tym SqlCommand temacie i zwraca wyniki jako XmlReader obiekt przy użyciu procedury wywołania zwrotnego.
public:
IAsyncResult ^ BeginExecuteXmlReader(AsyncCallback ^ callback, System::Object ^ stateObject);public IAsyncResult BeginExecuteXmlReader (AsyncCallback callback, object stateObject);member this.BeginExecuteXmlReader : AsyncCallback * obj -> IAsyncResultPublic Function BeginExecuteXmlReader (callback As AsyncCallback, stateObject As Object) As IAsyncResultParametry
- callback
- AsyncCallback
Delegat AsyncCallback wywoływany po zakończeniu wykonywania polecenia. Zdanenull ( Nothing w programie Microsoft Visual Basic) w celu wskazania, że nie jest wymagane wywołanie zwrotne.
- stateObject
- Object
Obiekt stanu zdefiniowany przez użytkownika przekazywany do procedury wywołania zwrotnego. Pobierz ten obiekt z procedury wywołania zwrotnego przy użyciu AsyncState właściwości .
Zwraca
Element IAsyncResult , który może służyć do sondowania, oczekiwania na wyniki lub obu. Ta wartość jest również potrzebna, gdy EndExecuteXmlReader(IAsyncResult) jest wywoływana, co zwraca wyniki polecenia jako XML.
Wyjątki
Użyto SqlDbType innego elementu niż Binary lub VarBinary , gdy Value ustawiono wartość Stream . Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
-lub-
Użyto SqlDbType innego niż Char, NChar, NVarChar, VarChar lub Xml, gdy Value ustawiono wartość TextReader .
-lub-
Inny SqlDbType niż Xml był używany, gdy Value ustawiono wartość XmlReader .
Wszelkie błędy, które wystąpiły podczas wykonywania tekstu polecenia.
-lub-
Wystąpił limit czasu podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
Zamknięty SqlConnection lub porzucony podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
- 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.
Wystąpił błąd w StreamXmlReader obiekcie lub TextReader podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
XmlReader Obiekt Stream lub TextReader został zamknięty podczas operacji przesyłania strumieniowego. Aby uzyskać więcej informacji na temat przesyłania strumieniowego, zobacz Obsługa przesyłania strumieniowego sqlClient.
Przykłady
Poniższa aplikacja systemu Windows demonstruje użycie BeginExecuteXmlReader metody , wykonując instrukcję Języka Transact-SQL, która zawiera opóźnienie kilku sekund (emulując długotrwałe polecenie). Ten przykład przekazuje obiekt wykonujący SqlCommand jako stateObject parametr, dzięki czemu można łatwo pobrać SqlCommand obiekt z procedury wywołania zwrotnego, dzięki czemu kod może wywołać metodę odpowiadającą początkowemu wywołaniu EndExecuteXmlReader .BeginExecuteXmlReader
W tym przykładzie pokazano wiele ważnych technik. Obejmuje to wywołanie metody, która wchodzi w interakcję z formularzem z oddzielnego wątku. Ponadto w tym przykładzie pokazano, jak należy zablokować użytkownikom wykonywanie polecenia wiele razy jednocześnie i jak należy się upewnić, że formularz nie jest zamykany przed wywołaniem procedury wywołania zwrotnego.
Aby skonfigurować ten przykład, utwórz nową aplikację systemu Windows. Umieść kontrolkę, kontrolkę ButtonListBox i kontrolkę Label w formularzu (akceptując domyślną nazwę dla każdej kontrolki). Dodaj następujący kod do klasy formularza, modyfikując parametry połączenia zgodnie z potrzebami dla danego środowiska.
// <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>
Uwagi
Metoda BeginExecuteXmlReader uruchamia proces asynchronicznego wykonywania instrukcji Języka Transact-SQL lub procedury składowanej zwracającej wiersze jako XML, dzięki czemu inne zadania mogą być uruchamiane współbieżnie podczas wykonywania instrukcji. Po zakończeniu instrukcji deweloperzy muszą wywołać metodę EndExecuteXmlReader , aby zakończyć operację i pobrać żądane dane XML. Metoda BeginExecuteXmlReader jest zwracana natychmiast, ale dopóki kod nie wykona odpowiedniego EndExecuteXmlReader wywołania metody, nie może wykonać żadnych innych wywołań, które rozpoczynają wykonywanie synchroniczne lub asynchroniczne względem tego samego SqlCommand obiektu. EndExecuteXmlReader Wywołanie polecenia przed wykonaniem polecenia powoduje SqlCommand zablokowanie obiektu do momentu zakończenia wykonywania.
Właściwość CommandText zwykle określa instrukcję Transact-SQL z prawidłową klauzulą FOR XML. CommandText Można jednak również określić instrukcję zwracającą dane zawierające prawidłowy kod XML. Ta metoda może również służyć do pobierania zestawu wyników z jednym wierszem, jednokolumna kolumna. W takim przypadku, jeśli zostanie zwrócony więcej niż jeden wiersz, EndExecuteXmlReader metoda dołącza XmlReader wartość do wartości w pierwszym wierszu i odrzuca resztę zestawu wyników.
Typowe BeginExecuteXmlReader zapytanie można sformatować tak, jak w poniższym przykładzie języka C#:
SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM Contact FOR XML AUTO, XMLDATA", SqlConn);
Ta metoda może również służyć do pobierania zestawu wyników z jednym wierszem, jednokolumna kolumna. W takim przypadku, jeśli zostanie zwrócony więcej niż jeden wiersz, EndExecuteXmlReader metoda dołącza XmlReader wartość do wartości w pierwszym wierszu i odrzuca resztę zestawu wyników.
Funkcja wielu aktywnych zestawów wyników (MARS) umożliwia korzystanie z tego samego połączenia przez wiele akcji.
Parametr callback umożliwia określenie delegata AsyncCallback , który jest wywoływany po zakończeniu instrukcji. Możesz wywołać metodę EndExecuteXmlReader z tej procedury delegata lub z dowolnej innej lokalizacji w aplikacji. Ponadto można przekazać dowolny obiekt w parametrze stateObject , a procedura wywołania zwrotnego może pobrać te informacje przy użyciu AsyncState właściwości .
Należy pamiętać, że tekst polecenia i parametry są wysyłane do serwera synchronicznie. Jeśli jest wysyłane duże polecenie lub wiele parametrów, ta metoda może blokować podczas zapisu. Po wysłaniu polecenia metoda zwraca natychmiast bez oczekiwania na odpowiedź z serwera — czyli odczyty są asynchroniczne.
Wszystkie błędy występujące podczas wykonywania operacji są zgłaszane jako wyjątki w procedurze wywołania zwrotnego. Należy obsłużyć wyjątek w procedurze wywołania zwrotnego, a nie w aplikacji głównej. Zobacz przykład w tym temacie, aby uzyskać dodatkowe informacje na temat obsługi wyjątków w procedurze wywołania zwrotnego.
Jeśli używasz ExecuteReader lub BeginExecuteReader uzyskujesz dostęp do danych XML, SQL Server zwróci wszystkie wyniki XML większe niż 2033 znaki w wielu wierszach o długości 2033 znaków. Aby uniknąć tego zachowania, użyj ExecuteXmlReader polecenia lub BeginExecuteXmlReader odczytu dla zapytań XML.
Ta metoda ignoruje CommandTimeout właściwość .