Classe System.Xml.XmlTextWriter

Este artigo fornece observações complementares à documentação de referência para essa API.

A classe XmlTextWriter implementa a classe XmlWriter.

Observação

Recomendamos que você crie instâncias XmlWriter usando o método XmlWriter.Create e a classe XmlWriterSettings para aproveitar a nova funcionalidade.

XmlTextWriter mantém uma pilha de namespace correspondente a todos os namespaces definidos na atual pilha de elementos. Usando XmlTextWriter, você pode declarar os 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 o seguinte saída. XmlTextWriter promove a declaração de namespace para o elemento raiz para evitar que ela seja duplicada nos dois elementos filhos. Os elementos filhos pegam o prefixo da declaração do namespace.

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

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

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

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

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 percorrerá a pilha de declarações de namespace de trás para frente e escolherá 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 escritor usa o último prefixo colocado na pilha de namespace 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 os resolverá 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 denominados n{i}, em que i é um número que começa em 1. O número é redefinido como 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 escritor gerará um prefixo para o atributo.

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

Quando um String é utilizado 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 de Double para String 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 atributos e elementos.
• 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 aspectos a serem considerados ao trabalhar com a classe XmlTextWriter.

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

• Quando você passa o XmlTextWriter para outro aplicativo, o fluxo subjacente é exposto para esse aplicativo. Se você precisar passar XmlTextWriter a um aplicativo de confiança parcial, você deve usar um objeto de XmlWriter criado pelo método de Create em vez disso.

• O 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 há garantia de que a saída gerada seja de dados XML bem formados.

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