Classe System.Xml.XmlWriter

  • Artigo

A classe XmlWriter grava dados XML em um fluxo, arquivo, leitor de texto ou cadeia de caracteres. Ele dá suporte as recomendações Linguagem XML (XML) 1.0 (quarta edição) e Namespaces in XML 1.0 (terceira edição) do W3C.

Os membros da classe XmlWriter permitem que você:

  • Verificar se os caracteres são caracteres XML legais e se os nomes de elementos e atributos são nomes XML válidos.
  • Verificar se o documento XML é bem-formado.
  • Codificar bytes binários como Base64 ou BinHex e gravar o texto resultante.
  • Passar valores usando tipos de Common Language Runtime em vez de cadeias de caracteres, para evitar a necessidade de realizar conversões de valores manualmente.
  • Gravar vários documentos em um fluxo de saída.
  • Gravar nomes válidos, nomes qualificados e tokens de nomes.

Criar um gravador XML

Para criar uma instância XmlWriter, use o método XmlWriter.Create. Para especificar o conjunto de recursos que você deseja habilitar no gravador de XML, passe um XmlWriterSettings para o método Create. Caso contrário, serão usadas as configurações padrão. Consulte as páginas de referência Create para obter detalhes.

Especificar o formato de saída

A classe XmlWriterSettings inclui várias propriedades que controlam como a saída XmlWriter é formatada:

Propriedade Descrição
Encoding Especifica a codificação de texto para usar. O padrão é Encoding.UTF8.
Indent Indica se recuar elementos. O padrão é false (sem recuo).
IndentChars Especifica a cadeia de caracteres para usar ao recuar. O padrão é os dois espaços.
NewLineChars Especifica a cadeia de caracteres para usar quebras de linha. O padrão é \r\n (retorno de carro, avanço de linha) para plataformas não Unix e \n (avanço de linha) para plataformas Unix.
NewLineHandling Especifica como lidar com os caracteres da nova linha.
NewLineOnAttributes Indica se escrever atributos em uma nova linha. Indent deve ser definido como true ao usar essa propriedade. O padrão é false.
OmitXmlDeclaration Indica se escrever uma declaração XML. O padrão é false.

As propriedades de Indent e de IndentChars controlam como o espaço em branco irrisória é formatado. Por exemplo, para recuar nós de elementos:

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.IndentChars = "\t";
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.IndentChars = vbTab
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

Use o NewLineOnAttributes para gravar cada atributo em uma nova linha com um nível extra de recuo:

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.NewLineOnAttributes = true;
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.NewLineOnAttributes = True
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

Conformidade de dados

Um gravador de XML usa duas propriedades da classe XmlWriterSettings para verificar a conformidade dos dados:

  • A propriedade CheckCharacters instrui o gravador de XML a verificar os caracteres e gerar uma exceção XmlException se algum caractere estiver fora do intervalo legal, conforme definido pelo W3C.

  • A propriedade ConformanceLevel configura o gravador de XML para verificar se o fluxo que está sendo gravado está em conformidade com as regras de um documento ou fragmento de documento XML 1.0 bem formado, conforme definido pelo W3C. Os três níveis de conformidade estão descritos na tabela a seguir. O padrão é Document. Para obter detalhes, confira a propriedade XmlWriterSettings.ConformanceLevel e a enumeração System.Xml.ConformanceLevel.

    Nível Descrição
    Document A saída XML está em conformidade com as regras de um documento XML 1.0 bem formado e pode ser processada por qualquer processador em conformidade.
    Fragment A saída XML está em conformidade com as regras de um fragmento de documento XML 1.0 bem formado.
    Auto O gravador de XML determina o nível de verificação de conformidade a ser aplicado (documento ou fragmento) com base nos dados recebidos.

Gravar elementos

Você pode usar os seguintes métodos XmlWriter para gravar nós de elementos. Para obter exemplos, confira os métodos listados.

Uso Para
WriteElementString Escreva um nó de elemento inteiro, incluindo um valor de cadeia de caracteres.
WriteStartElement Para gravar um valor de elemento usando várias chamadas de método. Por exemplo, você pode chamar WriteValue para gravar um valor tipado, WriteCharEntity para gravar uma entidade de caracteres, WriteAttributeString para escrever um atributo, ou você pode escrever um elemento filho. Essa é uma versão mais sofisticada do método WriteElementString.

Para fechar o elemento, chame o método WriteEndElement ou WriteFullEndElement.
WriteNode Para copiar um nó de elemento encontrado na posição atual de um objeto XmlReader ou XPathNavigator. Quando chamado, copia todos do objeto de origem para a instância de XmlWriter .

Atributos de gravação

Você pode usar os seguintes métodos XmlWriter para gravar atributos em nós de elementos. Esses métodos também podem ser usados para criar declarações de namespace em um elemento, conforme discutido na próxima seção.

Uso Para
WriteAttributeString Para gravar um nó de atributo inteiro, incluindo um valor de cadeia de caracteres.
WriteStartAttribute Para gravar o valor do atributo usando várias chamadas de método. Por exemplo, você pode chamar WriteValue para gravar um valor tipado. Essa é uma versão mais sofisticada do método WriteElementString.

Para fechar o elemento, chame o método WriteEndAttribute.
WriteAttributes Para copiar todos os atributos encontrados na posição atual de um objeto XmlReader. Os atributos que são gravados dependem do tipo de nó em que o leitor está posicionado no momento:

- Para um nó de atributo, ele grava o atributo atual e, em seguida, o restante dos atributos até a marca de fechamento do elemento.
- Para um nó de elemento, ele grava todos os atributos contidos no elemento.
- Para um nó de declaração XML, ele grava todos os atributos na declaração.
- Para todos os outros tipos de nós, o método gera uma exceção.

Manipular namespaces

Namespaces são usados para qualificar nomes de elementos e atributos em um documento XML. Os prefixos de namespace associam elementos e atributos a namespaces, que, por sua vez, estão associados a referências de URI. Namespaces criam a exclusividade de nome de elementos e atributos em um documento XML.

O XmlWriter mantém uma pilha de namespaces que corresponde a todos os namespaces definidos no escopo do namespace atual. Ao escrever os elementos e atributos você pode utilizar namespaces das seguintes maneiras:

  • Declare os namespaces manualmente usando o método WriteAttributeString. Isso pode ser útil quando você souber a melhor otimizar o número de declarações de namespace. Para obter um exemplo, confira o método WriteAttributeString(String, String, String, String).

  • Substitua a declaração atual do namespace com um novo namespace. No código a seguir, o método WriteAttributeString altera o URI do namespace para o prefixo "x" de "123" para "abc".

    writer.WriteStartElement("x", "root", "123");
writer.WriteStartElement("item");
writer.WriteAttributeString("xmlns", "x", null, "abc");
writer.WriteEndElement();
writer.WriteEndElement();

    writer.WriteStartElement("x", "root", "123")
writer.WriteStartElement("item")
writer.WriteAttributeString("xmlns", "x", Nothing, "abc")
writer.WriteEndElement()
writer.WriteEndElement()

    O código gerencia a seguinte cadeia de caracteres XML:

    <x:root xmlns:x="123">
  <item xmlns:x="abc" />
</x:root>

  • Especificar um prefixo de namespace para escrever atributos ou elementos. Muitos dos métodos usados para gravar elementos e atributos permitem que você faça isso. Por exemplo, o método WriteStartElement(String, String, String) grava uma marca de início e a associa a um namespace e prefixo especificados.

Gravar dados tipados

O método WriteValue aceita um objeto de Common Language Runtime (CLR), converte o valor de entrada em sua representação de cadeia de caracteres de acordo com as regras de conversão de tipo de dados da linguagem de definição de esquema XML (XSD) e o grava usando o método WriteString. Isso é mais fácil do que usar os métodos da classe XmlConvert para converter os dados digitados em um valor de cadeia de caracteres antes de escrevê-los.

Ao gravar em texto, o valor digitado é serializado em texto usando as regras XmlConvert para esse tipo de esquema.

Para obter os tipos de dados XSD padrão que correspondem aos tipos CLR, confira o método WriteValue.

O XmlWriter também pode ser usado para gravar em um armazenamento de dados XML. Por exemplo, a classe de XPathNavigator pode criar um objeto de XmlWriter para criar nós para um objeto de XmlDocument . Se o armazenamento de dados tiver informações de esquema disponíveis, o método WriteValue gerará uma exceção se você tentar converter para um tipo que não seja permitido. Se o armazenamento de dados não tiver informações de esquema disponíveis, o método WriteValue tratará todos os valores como um tipo xsd:anySimpleType.

Fechar o gravador XML

Quando você usa os métodos XmlWriter para gerar a linguagem XML, os elementos e atributos não são gravados até que você chame o método Close. Por exemplo, se você estiver usando XmlWriter para preencher um objeto XmlDocument, não poderá ver os elementos e atributos escritos no documento de destino até fechar a instância XmlWriter.

Programação assíncrona

A maioria dos métodos XmlWriter tem contrapartes assíncronas que têm "Async" no final dos nomes dos métodos. Por exemplo, o equivalente assíncrono de WriteAttributeString é WriteAttributeStringAsync.

Para o método WriteValue, que não tem um equivalente assíncrono, converta o valor de retorno em uma cadeia de caracteres e use o método WriteStringAsync.

Considerações de segurança

Considere o seguinte ao trabalhar com a classe XmlWriter:

  • As exceções geradas pelo XmlWriter podem revelar informações do caminho que você não deseja que sejam propagadas para o aplicativo. Seu aplicativo deve capturar exceções e processá-las adequadamente.

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