sp_xml_preparedocument (Transact-SQL)

Artigo
03/07/2014

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 recentemente criada do documento XML. Esse identificador é válido para a duração da sessão ou até que ele seja invalidado executando-se sp_xml_removedocument.

Dica

Um documento analisado é armazenado no cache interno de SQL Server.O analisador MSXML usa um oitavo da memória total disponível para o SQL Server.Para evitar ficar sem memória, execute sp_xml_removedocument para liberar a memória.

Dica

Para compatibilidade com versões anteriores, sp_xml_preparedocument recolhe os caracteres CR (char(13)) e LF (char(10)) em atributos mesmo se esses caracteres tiverem entidade.

Dica

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 má intenção podem ser usados para executar uma negação de ataque de serviço, é altamente recomendável que os usuários não passem documentos XML diretamente de fontes não confiáveis para sp_xml_preparedocument.

Para minimizar os ataques de expansão de entidade, sp_xml_preparedocument limita a 10.000 o número de entidades que podem ser expandidas em uma única entidade no nível superior de um documento.O limite não se aplica a entidades numéricas ou caractere.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.

Dica

sp_xml_preparedocument limita o número de elementos que podem ser abertos de uma só vez para 256.

Aplica-se a: SQL Server (SQL Server 2008 à versão atual).

Ícone de vínculo de tópico Convenções da sintaxe Transact-SQL

Sintaxe

sp_xml_preparedocument 
hdoc  
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ]

Argumentos

hdoc
É o identificador do documento recém-criado. hdoc é um inteiro.
[ xmltext ]
É 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; nesse caso é criada uma representação interna de um documento XML vazio.

Dica

sp_xml_preparedocument podem processar somente XML de texto não digitado.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, consulte 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 em OPENXML por meio de um documento XML bem formado. xpath_namespaces declara o prefixo que deve ser usado para fazer referência ao namespace urn:schemas-microsoft-com:xml-metaprop. Isso fornece metadados sobre os elementos XML analisados. Embora você possa redefinir o prefixo de namespace para o namespace metaproperty usando essa técnica, esse namespace não será perdido. O prefixo mp ainda será válido para urn:schemas-microsoft-com:xml-metaprop mesmo se xpath_namespaces não tiver tal declaração.

Valores de código de retorno

0 (êxito) ou >0 (falha)

Permissões

Requer associação na função pública.

Exemplos

A.Preparando uma representação interna de 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.Preparando 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.Especificando 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 metaproperty e adiciona o prefixo de mapeamento xyz 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"/>';