sp_xml_preparedocument (Transact-SQL)
Gilt für: 
SQL Server Azure SQL-Datenbank
Liest den xml-Text, der als Eingabe bereitgestellt wird, analysiert den Text mithilfe des MSXML-Parsers (msxmlsql.dll), und stellt das analysierte Dokument in einem Zustand bereit für den Verbrauch 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 während der Sitzung gültig oder bis der Handle durch Ausführen sp_xml_removedocumentungültig wird.
Ein analysiertes Dokument wird im internen Cache von SQL Server gespeichert. Der MSXML-Parser kann einen Achtel des für SQL Server verfügbaren Gesamtspeichers verwenden. Um zu vermeiden, dass nicht genügend Arbeitsspeicher verfügbar ist, führen Sie die Ausführung sp_xml_removedocument aus, um den Arbeitsspeicher freizugeben, sobald das Dokument nicht mehr benötigt wird. In vielen Fällen ist die Methode "nodes()" möglicherweise eine bessere Alternative und trägt dazu bei, übermäßige Speichernutzung zu vermeiden.
Reduziert aus Gründen der Abwärtskompatibilität sp_xml_preparedocument die Zeichen CR (char(13)) und LF (char(10)) in Attributen, auch wenn diese Zeichen entitisiert werden.
Hinweis
Der von sp_xml_preparedocument der XML-Parser aufgerufene XML-Parser kann interne DTDs und Entitätsdeklarationen analysieren. Da böswillige DTDs und Entitätsdeklarationen zum Ausführen eines Denial-of-Service-Angriffs verwendet werden können, wird dringend empfohlen, dass Benutzer XML-Dokumente nicht direkt aus nicht vertrauenswürdigen Quellen an sp_xml_preparedocument.
Um rekursive Entitätserweiterungsangriffe zu mindern, beschränken Sie die Anzahl der Entitäten, sp_xml_preparedocument die unter einer einzelnen Entität auf der obersten Ebene eines Dokuments erweitert werden können. Der Grenzwert 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.
sp_xml_preparedocument beschränkt die Anzahl der Elemente, die gleichzeitig auf 256 geöffnet werden können.
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. Der MSXML-Parser analysiert dieses XML-Dokument. 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 typisierte 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 Vergleichen von typisiertem XML mit nicht typisiertem XML.
[ xpath_namespaces ]
Gibt die Namespacedeklarationen 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 Präfixe bereit, die in den XPath-Ausdrücken in OPENXML verwendet werden, mit einem wohlgeformten XML-Dokument. xpath_namespaces deklariert das Präfix, das zum Verweisen auf den Namespace urn:schemas-microsoft-com:xml-metapropverwendet werden muss. Dadurch werden Metadaten zu den analysierten XML-Elementen bereitgestellt. Obwohl Sie das Namespacepräfix für den Metaproperty-Namespace mithilfe dieser Technik neu definieren können, geht dieser Namespace nicht verloren. Das Präfix mp ist weiterhin gültig, urn:schemas-microsoft-com:xml-metaprop auch wenn xpath_namespaces keine solche Deklaration enthält.
Rückgabecodewerte
0 (erfolgreich) oder > 0 Fehler.
Berechtigungen
Erfordert die Mitgliedschaft in der public -Rolle.
Beispiele
A. Vorbereiten 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. Vorbereiten 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-URI
Im folgenden Beispiel wird ein Handle für die neu erstellte interne Darstellung des als Eingabe bereitgestellten XML-Dokuments zurückgegeben. Der Aufruf zum sp_xml_preparedocument Beibehalten des mp Präfixes für die Metaproperty-Namespacezuordnung und fügt dem Namespace urn:MyNamespacedas xyz Zuordnungspräfix hinzu.
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"/>';