Artikel
03/30/2012

sp_xml_preparedocument (Transact-SQL)

Liest den als Eingabe bereitgestellten XML-Text, analysiert diesen mit dem MSXML-Parser (Msxmlsql.dll) und stellt das analysierte Dokument für die Verwendung bereit. Das analysierte Dokument ist eine strukturierte Darstellung der verschiedenen Knoten im XML-Dokument: Elemente, Attribute, Text, Kommentare usw.

sp_xml_preparedocument gibt ein Handle zurück, das für den Zugriff auf die neu erstellte interne Darstellung des XML-Dokuments verwendet werden kann. Dieses Handle ist für die Dauer der Sitzung oder so lange gültig, bis das Handle durch Ausführen von sp_xml_removedocument für ungültig erklärt wird.

Hinweis
Ein analysiertes Dokument wird im internen Cache von SQL Server gespeichert. Der MSXML-Parser verwendet ein Achtel des gesamten für SQL Server verfügbaren Arbeitsspeichers. Führen Sie sp_xml_removedocument aus, um den Arbeitsspeicher freizugeben, damit immer ausreichend Arbeitsspeicher zur Verfügung steht.

Hinweis
Aus Gründen der Abwärtskompatibilität reduziert sp_xml_preparedocument die CR (char(13))- und LF (char(10))-Zeichen in Attributen auch dann, wenn diese Zeichen in Entitäten geändert sind.

Hinweis
Der von sp_xml_preparedocument aufgerufene XML-Parser ermöglicht die Analyse interner DTDs und Entitätsdeklarationen. Da mit böswilligen Absichten erstellte DTDs und Entitätsdeklarationen zum Ausführen eines Denial-of-Service-Angriffs verwendet werden können, wird dringend empfohlen, dass Benutzer XML-Dokumente aus nicht vertrauenswürdigen Quellen nicht direkt an sp_xml_preparedocument übergeben. Zur Verringerung des Risikos von Angriffen durch rekursive Entitätserweiterung wird von sp_xml_preparedocument die Anzahl von Entitäten, die unterhalb einer einzelnen Entität auf der obersten Ebene eines Dokuments erweitert werden können, auf 10.000 begrenzt. Diese Grenze gilt nicht für Zeichen- oder numerische Entitäten. Die Grenze ermöglicht die Speicherung von Dokumenten mit zahlreichen Entitätsverweisen, verhindert jedoch die rekursive Erweiterung einer Entität in eine Kette von mehr als 10.000 Erweiterungen.

Der von sp_xml_preparedocument aufgerufene XML-Parser ermöglicht die Analyse interner DTDs und Entitätsdeklarationen. Da mit böswilligen Absichten erstellte DTDs und Entitätsdeklarationen zum Ausführen eines Denial-of-Service-Angriffs verwendet werden können, wird dringend empfohlen, dass Benutzer XML-Dokumente aus nicht vertrauenswürdigen Quellen nicht direkt an sp_xml_preparedocument übergeben.

Zur Verringerung des Risikos von Angriffen durch rekursive Entitätserweiterung wird von sp_xml_preparedocument die Anzahl von Entitäten, die unterhalb einer einzelnen Entität auf der obersten Ebene eines Dokuments erweitert werden können, auf 10.000 begrenzt. Diese Grenze gilt nicht für Zeichen- oder numerische Entitäten. Die Grenze ermöglicht die Speicherung von Dokumenten mit zahlreichen Entitätsverweisen, verhindert jedoch die rekursive Erweiterung einer Entität in eine Kette von mehr als 10.000 Erweiterungen.

Hinweis
sp_xml_preparedocument begrenzt die Anzahl von gleichzeitig geöffneten Elementen auf 256.

Themenlink (Symbol) Transact-SQL-Syntaxkonventionen

Syntax

sp_xml_preparedocument
hdoc 
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ]

Argumente

hdoc
Das Handle für das neu erstellte Dokument. hdoc ist eine ganze Zahl.

[ xmltext ]
Das ursprüngliche XML-Dokument. Dieses XML-Dokument wird vom MSXML-Parser analysiert. xmltext ist ein Textparameter: char, nchar, varchar, nvarchar, text, ntext oder xml. Der Standardwert ist NULL; in diesem Fall wird eine interne Darstellung eines leeren XML-Dokuments erstellt.

Hinweis
sp_xml_preparedocument kann nur Text oder nicht typisiertes XML verarbeiten. Falls ein Instanzwert, der als Eingabewert verwendet werden soll, bereits ein typisierter XML-Wert ist, müssen Sie ihn zunächst in eine neue nicht typisierte XML-Instanz oder eine Zeichenfolge konvertieren und anschließend diesen Wert als Eingabewert übergeben. Weitere Informationen finden Sie unter Typisiertes XML im Vergleich zu nicht typisiertem XML.

sp_xml_preparedocument kann nur Text oder nicht typisiertes XML verarbeiten. Falls ein Instanzwert, der als Eingabewert verwendet werden soll, bereits ein typisierter XML-Wert ist, müssen Sie ihn zunächst in eine neue nicht typisierte XML-Instanz oder eine Zeichenfolge konvertieren und anschließend diesen Wert als Eingabewert übergeben. Weitere Informationen finden Sie unter Typisiertes XML im Vergleich zu nicht typisiertem XML.

[ xpath_namespaces ]
Gibt die Deklarationen des Namespaces an, die in XPath-Ausdrücken für Zeilen und Spalten in OPENXML verwendet werden. xpath_namespaces ist ein Textparameter: char, nchar, varchar, nvarchar, text, ntext oder xml.

Der Standardwert ist <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces stellt die Namespace-URIs für die in den XPath-Ausdrücken in OPENXML verwendeten Präfixe in einem wohlgeformten XML-Dokument bereit. xpath_namespaces deklariert das Präfix, das verwendet werden muss, um auf den Namespace urn:schemas-microsoft-com:xml-metaprop zu verweisen, der Metadaten für die analysierten XML-Elemente bereitstellt. Obwohl Sie das Namespacepräfix für den Namespace der Metaeigenschaften mit diesem Verfahren neu definieren können, geht dieser Namespace nicht verloren. Das Präfix mp ist für urn:schemas-microsoft-com:xml-metaprop weiterhin gültig, auch wenn xpath_namespaces keine derartige Deklaration enthält.

Rückgabecodewerte

0 (Erfolg) oder >0 (Fehler)

Berechtigungen

Erfordert die Mitgliedschaft in der public-Rolle.

Beispiele

A. Erstellen einer internen Darstellung für ein wohlgeformtes XML-Dokument

Im folgenden Beispiel wird ein Handle für die neu erstellte interne Darstellung des als Eingabe bereitgestellten XML-Dokuments zurückgegeben. Im Aufruf von sp_xml_preparedocument wird die Standardzuordnung für das Namespacepräfix verwendet.

DECLARE @hdoc int
DECLARE @doc varchar(1000)
SET @doc ='
<ROOT>
<Customer CustomerID="VINET" ContactName="Paul Henriot">
   <Order CustomerID="VINET" EmployeeID="5" OrderDate="1996-07-04T00:00:00">
      <OrderDetail OrderID="10248" ProductID="11" Quantity="12"/>
      <OrderDetail OrderID="10248" ProductID="42" Quantity="10"/>
   </Order>
</Customer>
<Customer CustomerID="LILAS" ContactName="Carlos Gonzlez">
   <Order CustomerID="LILAS" EmployeeID="3" OrderDate="1996-08-16T00:00:00">
      <OrderDetail OrderID="10283" ProductID="72" Quantity="3"/>
   </Order>
</Customer>
</ROOT>'
--Create an internal representation of the XML document.
EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc
-- Remove the internal representation.
exec sp_xml_removedocument @hdoc

B. Erstellen einer internen Darstellung für ein wohlgeformtes XML-Dokument mit einer DTD

Im folgenden Beispiel wird ein Handle für die neu erstellte interne Darstellung des als Eingabe bereitgestellten XML-Dokuments zurückgegeben. Die gespeicherte Prozedur überprüft das geladene Dokument in Bezug auf die im Dokument enthaltene DTD. Im Aufruf von sp_xml_preparedocument wird die Standardzuordnung für das Namespacepräfix verwendet.

DECLARE @hdoc int
DECLARE @doc varchar(2000)
SET @doc = '
<?xml version="1.0" encoding="UTF-8" ?> 
<!DOCTYPE root 
[<!ELEMENT root (Customers)*>
<!ELEMENT Customers EMPTY>
<!ATTLIST Customers CustomerID CDATA #IMPLIED ContactName CDATA #IMPLIED>]>
<root>
<Customers CustomerID="ALFKI" ContactName="Maria Anders"/>
</root>'

EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc

C. Angeben eines Namespace-URIs

Im folgenden Beispiel wird ein Handle für die neu erstellte interne Darstellung des als Eingabe bereitgestellten XML-Dokuments zurückgegeben. Beim Aufruf von sp_xml_preparedocument wird mp als Präfix für die Namespacezuordnung der Metaeigenschaften beibehalten und das Zuordnungspräfix xyz dem Namespace urn:MyNamespace hinzugefügt.

DECLARE @hdoc int
DECLARE @doc varchar(1000)
SET @doc ='
<ROOT>
<Customer CustomerID="VINET" ContactName="Paul Henriot">
   <Order CustomerID="VINET" EmployeeID="5" 
           OrderDate="1996-07-04T00:00:00">
      <OrderDetail OrderID="10248" ProductID="11" Quantity="12"/>
      <OrderDetail OrderID="10248" ProductID="42" Quantity="10"/>
   </Order>
</Customer>
<Customer CustomerID="LILAS" ContactName="Carlos Gonzlez">
   <Order CustomerID="LILAS" EmployeeID="3" 
           OrderDate="1996-08-16T00:00:00">
      <OrderDetail OrderID="10283" ProductID="72" Quantity="3"/>
   </Order>
</Customer>
</ROOT>'
--Create an internal representation of the XML document.
EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc, '<ROOT xmlns:xyz="urn:MyNamespace"/>'