sp_xml_preparedocument (Transact-SQL)

项目
06/18/2013

读取作为输入提供的 XML 文本，然后使用 MSXML 分析器 (Msxmlsql.dll) 对其进行分析，并提供分析后的文档供使用。分析后的文档对 XML 文档中的各节点（元素、属性、文本和注释等）的树状表示形式。

sp_xml_preparedocument 返回一个句柄，可用于访问 XML 文档的新创建的内部表示形式。该句柄在会话的持续时间内有效，或者通过执行 sp_xml_removedocument 使其在句柄失效前一直有效。

注意
分析后的文档存储在 SQL Server 的内部缓存中。 MSXML 分析器占用 SQL Server 可用总内存的八分之一。若要避免内存不足，请运行 sp_xml_removedocument 以释放内存。

注意
为了保持向后兼容性，sp_xml_preparedocument 将会折叠属性中的 CR (char(13)) 和 LF (char(10)) 字符，即使这些字符被实体化，也会执行折叠操作。

注意
使用由 sp_xml_preparedocument 调用的 XML 分析器，便可分析内部 DTD 和实体声明。由于可使用恶意构造的 DTD 和实体声明执行拒绝服务攻击，因此，我们极力建议用户不要直接将 XML 文档从不可信的源传递到 sp_xml_preparedocument。为了减少递归实体扩展攻击，sp_xml_preparedocument 将文档顶级的单个实体下可扩展的最大实体数限制为 10,000。该限制不适用于字符或数字实体。通过该限制，可以存储带有多个实体引用的文档，同时可以禁止在长于 10,000 个扩展的链中递归扩展任意实体。

使用由 sp_xml_preparedocument 调用的 XML 分析器，便可分析内部 DTD 和实体声明。由于可使用恶意构造的 DTD 和实体声明执行拒绝服务攻击，因此，我们极力建议用户不要直接将 XML 文档从不可信的源传递到 sp_xml_preparedocument。

为了减少递归实体扩展攻击，sp_xml_preparedocument 将文档顶级的单个实体下可扩展的最大实体数限制为 10,000。该限制不适用于字符或数字实体。通过该限制，可以存储带有多个实体引用的文档，同时可以禁止在长于 10,000 个扩展的链中递归扩展任意实体。

注意
sp_xml_preparedocument 将可以同时打开的最大元素数限制为 256。

主题链接图标 Transact-SQL 语法约定

语法

sp_xml_preparedocument 
hdoc  
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ]

参数

hdoc
新建文档的句柄。 hdoc 为整数。

[ xmltext ]
是原来的 XML 文档。 MSXML 分析器分析该 XML 文档。 xmltext 是一个文本参数：char、nchar、varchar、nvarchar、text、ntext 或 xml。默认值为 NULL，在此情况下将创建一个空 XML 文档的内部表示形式。

注意
sp_xml_preparedocument 只能处理文本或非类型化的 XML。如果将作为输入的实例值已经是类型化的 XML，首先将它转换为新的非类型化的 XML 实例，或者转换为一个字符串，然后传递该值作为输入。有关详细信息，请参阅类型化的 XML 与非类型化的 XML 的比较。

[ xpath_namespaces ]
指定在 OPENXML 的行和列 XPath 表达式中使用的命名空间声明。 xpath_namespaces 是一个文本参数：char、nchar、varchar、nvarchar、text、ntext 或 xml。

默认值为 <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">。 xpath_namespaces 通过格式正确的 XML 文档，为在 OPENXML 中的 XPath 表达式中使用的前缀提供命名空间 URI。 xpath_namespaces 声明引用命名空间 urn:schemas-microsoft-com:xml-metaprop 所必须使用的前缀；这将提供有关分析的 XML 元素的元数据。虽然可以使用这项技术来为元属性命名空间重新定义命名空间前缀，但该命名空间不会丢失。即使 xpath_namespaces 不包含这类声明，前缀 mp 依然对 urn:schemas-microsoft-com:xml-metaprop 有效。

返回代码值

0（成功）或 >0（失败）

权限

要求具有 public 角色的成员身份。

示例

A.为格式正确的 XML 文档准备内部表示形式

以下示例向作为输入提供的 XML 文档的新建内部表示形式返回句柄：在对 sp_xml_preparedocument 的调用中，将使用默认的命名空间前缀映射。

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.为带 DTD 的格式正确的 XML 文档准备内部表示形式

以下示例向作为输入提供的 XML 文档的新建内部表示形式返回句柄：存储过程根据文档中包含的 DTD 来验证装载的文档。在对 sp_xml_preparedocument 的调用中，将使用默认的命名空间前缀映射。

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.指定命名空间 URI

以下示例返回作为输入提供的 XML 文档的新建内部表示形式的句柄。对 sp_xml_preparedocument 的调用将 mp 前缀保留到元属性命名空间的映射，并将 xyz 映射前缀添加到命名空间 urn:MyNamespace。

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"/>'