sp_xml_preparedocument (Transact-SQL)
Aplica-se a: 
SQL Server Banco de Dados SQL do Azure
Lê o texto XML fornecido como entrada, analisa o texto usando o analisador MSXML (msxmlsql.dll) e fornece o documento analisado em um estado pronto para consumo. Esse documento analisado é uma representação em árvore dos vários nós no documento XML: elementos, atributos, texto, comentários e assim por diante.
sp_xml_preparedocument retorna um identificador que pode ser usado para acessar a representação interna recém-criada do documento XML. Esse identificador é válido durante a sessão ou até que o identificador seja invalidado pela execução sp_xml_removedocumentdo .
Um documento analisado é armazenado no cache interno do SQL Server. O analisador MSXML pode usar um oitavo da memória total disponível para SQL Server. Para evitar ficar sem memória, execute sp_xml_removedocument para liberar a memória assim que o documento não for mais necessário. Em muitos casos, o método nodes() pode ser uma alternativa melhor e ajudar a evitar o uso excessivo de memória.
Para compatibilidade com versões anteriores, recolhe os caracteres CR (char(13)) e LF (char(10)) em atributos, sp_xml_preparedocument mesmo que esses caracteres tenham a entidade definida.
Observação
O analisador XML invocado por sp_xml_preparedocument pode analisar DTDs internos e declarações de entidade. Como DTDs e declarações de entidade construídos com códigos maliciosos podem ser usados para executar um ataque de negação de serviço, é altamente recomendável que os usuários não passem documentos XML diretamente de fontes não confiáveis para o sp_xml_preparedocument.
Para mitigar ataques de expansão de entidade recursiva, sp_xml_preparedocument limita a 10.000 o número de entidades que podem ser expandidas sob uma única entidade no nível superior de um documento. O limite não se aplica a entidades numéricas ou de caracteres. Esse limite permite que documentos com muitas referências de entidade sejam armazenados, mas impede que qualquer entidade seja recursivamente expandida em uma cadeia com mais de 10.000 expansões.
sp_xml_preparedocument Limita o número de elementos que podem ser abertos ao mesmo tempo para 256.
Convenções de sintaxe de Transact-SQL
Sintaxe
sp_xml_preparedocument hdoc OUTPUT
[ , xmltext ]
[ , xpath_namespaces ]
[ ; ]
Argumentos
hdoc
O identificador para o documento recém-criado. hdoc é um número inteiro.
[ texto xml]
O documento XML original. O analisador MSXML analisa este documento XML. xmltext é um parâmetro de texto: char, nchar, varchar, nvarchar, text, ntext ou xml. O valor padrão é NULL, caso em que uma representação interna de um documento XML vazio é criada.
Observação
sp_xml_preparedocument só pode processar texto ou XML não tipado. Se um valor de instância a ser usado como entrada já é XML digitado, primeiro converta-o em uma nova instância XML digitada ou uma cadeia de caracteres e, em seguida, passe esse valor como entrada. Para obter mais informações, confira Comparar XML digitado com XML não digitado.
[ xpath_namespaces ]
Especifica as declarações de namespace usadas em expressões XPATH de linha e coluna em OPENXML. xpath_namespaces é um parâmetro de texto: char, nchar, varchar, nvarchar, text, ntext ou xml.
O valor padrão é <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces fornece os URIs de namespace para os prefixos usados nas expressões XPath no OPENXML, com um documento XML bem formado. xpath_namespaces declara o prefixo que deve ser usado para se referir ao namespaceurn:schemas-microsoft-com:xml-metaprop; isso fornece metadados sobre os elementos XML analisados. Embora você possa redefinir o prefixo de namespace para o namespace de metapropriedade usando essa técnica, esse namespace não é perdido. O prefixo mp ainda é válido mesmo urn:schemas-microsoft-com:xml-metaprop que xpath_namespaces não contenha tal declaração.
Valores do código de retorno
0 (sucesso) ou > 0 (falha).
Permissões
Requer associação à função pública .
Exemplos
R. Preparar uma representação interna para um documento XML bem formado
O exemplo a seguir retorna um identificador para a representação interna criada recentemente do documento XML que é fornecido como entrada. Na chamada para sp_xml_preparedocument, é usado um mapeamento de prefixo de namespace padrão.
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. Preparar uma representação interna para um documento XML bem formado com um DTD
O exemplo a seguir retorna um identificador para a representação interna criada recentemente do documento XML que é fornecido como entrada. O procedimento armazenado valida o documento carregado contra o DTD incluído no documento. Na chamada para sp_xml_preparedocument, é usado um mapeamento de prefixo de namespace padrão.
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. Especificar um URI de namespace
O exemplo a seguir retorna um identificador para a representação interna criada recentemente do documento XML que é fornecido como entrada. A chamada para sp_xml_preparedocument preserva o prefixo mp para o mapeamento de namespace de metapropriedade e adiciona o prefixo de xyz mapeamento ao namespace 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"/>';