Classe System.Xml.XmlTextWriter

Este artigo fornece comentários complementares à documentação de referência para esta API.

A XmlTextWriter classe implementa a XmlWriter classe.

XmlTextWriter mantém uma pilha de namespace correspondente a todos os namespaces definidos na atual pilha de elementos. Usando XmlTextWriter você pode declarar namespaces manualmente.

w.WriteStartElement("root");
w.WriteAttributeString("xmlns", "x", null, "urn:1");
w.WriteStartElement("item","urn:1");
w.WriteEndElement();
w.WriteStartElement("item","urn:1");
w.WriteEndElement();
w.WriteEndElement();

O código C# acima produz a saída a seguir. XmlTextWriter promove a declaração de namespace para o elemento raiz para evitar que ele seja duplicado nos dois elementos filho. Os elementos filho adquirem o prefixo da declaração de namespace.

<root xmlns:x="urn:1">
<x:item/>
<x:item/>
</x:root>

XmlTextWriter também permite substituir a declaração de namespace atual. No exemplo a seguir, o URI do namespace "123" é substituído por "abc" para produzir o elemento <x:node xmlns:x="abc"/>XML.

w.WriteStartElement("x","node","123");
w.WriteAttributeString("xmlns","x",null,"abc");

Usando os métodos de gravação que usam um prefixo como argumento, você também pode especificar qual prefixo usar. No exemplo a seguir, dois prefixos diferentes são mapeados para o mesmo URI de namespace para produzir o texto <x:root xmlns:x="urn:1"><y:item xmlns:y="urn:1"/></x:root>XML.

XmlTextWriter w = new XmlTextWriter(Console.Out);
w.WriteStartElement("x","root","urn:1");
w.WriteStartElement("y","item","urn:1");
w.WriteEndElement();
w.WriteEndElement();
w.Close();

Se houver várias declarações de namespace mapeando prefixos diferentes para o mesmo URI de namespace, XmlTextWriter percorre a pilha de declarações de namespace em ordem inversa e seleciona a mais próxima.

XmlTextWriter w = new XmlTextWriter(Console.Out);
w.Formatting = Formatting.Indented;
w.WriteStartElement("x","root","urn:1");
w.WriteStartElement("y","item","urn:1");
w.WriteAttributeString("attr","urn:1","123");
w.WriteEndElement();
w.WriteEndElement();
w.Close();

No exemplo de C# acima, como a chamada WriteAttributeString não especifica um prefixo, o gravador usa o último prefixo inserido na pilha de namespaces e produz o seguinte XML:

<x:root xmlns:x="urn:1">
<y:item y:attr="123" xmlns:y="urn:1" />
</x:root>

Se ocorrerem conflitos de namespace, XmlTextWriter resolva-os gerando prefixos alternativos. Por exemplo, se um atributo e um elemento tiverem o mesmo prefixo, mas namespaces diferentes, XmlWriter gerará um prefixo alternativo para o atributo. Os prefixos gerados são nomeados n{i} onde i está um número começando em 1. O número é redefinido para 1 para cada elemento.

Os atributos associados a um URI de namespace devem ter um prefixo (namespaces padrão não se aplicam a atributos). Isso está em conformidade com a seção 5.2 da recomendação Namespaces W3C no XML. Se um atributo fizer referência a um URI de namespace, mas não especificar um prefixo, o gravador gerará um prefixo para o atributo.

Ao escrever um elemento vazio, se adiciona um espaço adicional entre o nome da tag e a tag de fechamento, por exemplo, <item />. Isso fornece compatibilidade com navegadores mais antigos.

Quando um String é usado como parâmetro de método, null e String.Empty são equivalentes. String.Empty segue as regras do W3C.

Para escrever dados fortemente tipados, use a classe XmlConvert para converter os tipos de dados em cadeia de caracteres. Por exemplo, o código C# a seguir converte os dados DoubleString e grava o elemento <price>19.95</price>.

Double price = 19.95;
writer.WriteElementString("price", XmlConvert.ToString(price));

XmlTextWriter não verifica o seguinte:

• Caracteres inválidos em nomes de atributo e elemento.
• Caracteres Unicode que não se ajustam à codificação especificada. Se os caracteres Unicode não se enquadrarem na codificação especificada, o XmlTextWriter não fará o escape dos caracteres Unicode em entidades de caracteres.
• Atributos duplicados.
• Caracteres no identificador público DOCTYPE ou no identificador do sistema.

Considerações de segurança

Os itens a seguir são coisas a serem consideradas ao trabalhar com a XmlTextWriter classe.

• As exceções geradas pelo XmlTextWriter podem revelar informações sobre o caminho que você não deseja que sejam transmitidas ao aplicativo. Seus aplicativos devem capturar exceções e processá-las adequadamente.

• Quando você passa o XmlTextWriter para outro aplicativo, o fluxo subjacente é exposto a esse aplicativo. Se você precisar passar o XmlTextWriter para um aplicativo semi-confiável, deverá usar um objeto XmlWriter criado pelo método Create.

• XmlTextWriter não valida nenhum dado que é passado para os métodos WriteDocType ou WriteRaw. Você não deve passar dados arbitrários para esses métodos.

• Se as configurações padrão forem alteradas, não haverá garantia de que a saída gerada seja dados XML bem formados.

• Não aceite componentes de suporte, como um Encoding objeto, de uma fonte não confiável.