Compartilhar via

Classe System.Xml.XmlWriter

A XmlWriter classe 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 XmlWriter classe permitem que você:

  • Verifique se os caracteres são caracteres XML legais e se os nomes de elemento e atributo são nomes XML válidos.
  • Verifique se o documento XML está bem formado.
  • Codificar bytes binários como Base64 ou BinHex e gravar o texto resultante.
  • Passe valores usando tipos de common language runtime em vez de cadeias de caracteres, para evitar ter que executar manualmente conversões de valor.
  • Escreva vários documentos em um fluxo de saída.
  • Escreva nomes válidos, nomes qualificados e identificadores de nome.

Criar um gravador XML

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

Especificar o formato de saída

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

Propriedade Descrição
Encoding Especifica a codificação de texto a ser usada. O padrão é Encoding.UTF8.
Indent Indica se recuar elementos. O padrão é false (sem recuo).
IndentChars Especifica a sequência de caracteres a ser usada para a indentação. O padrão é dois espaços.
NewLineChars Especifica a cadeia de caracteres a ser usada para 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 os atributos devem ser gravados em uma nova linha. Indent deve ser definido para true ao usar esta propriedade. O padrão é false.
OmitXmlDeclaration Indica se deve gravar uma declaração XML. O padrão é false.

As Indent propriedades e as IndentChars propriedades controlam como o espaço em branco insignificante é 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 XML usa duas propriedades da XmlWriterSettings classe para verificar a conformidade de dados:

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

  • A ConformanceLevel propriedade configura o gravador 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 são descritos na tabela a seguir. O padrão é Document. Para obter detalhes, consulte a XmlWriterSettings.ConformanceLevel propriedade e a System.Xml.ConformanceLevel enumeração.

    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 XML determina qual nível de verificação de conformidade deve ser aplicado (documento ou fragmento) com base nos dados de entrada.

Escrever elementos

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

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

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

Atributos de gravação

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

Utilização 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 escrever um valor tipado. Esta é uma versão mais sofisticada do WriteElementString método.

Para fechar o elemento, você chama o WriteEndAttribute método.
WriteAttributes Para copiar todos os atributos encontrados na posição atual de um XmlReader objeto. 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 exclusividade de elemento e nome de atributo 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 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ê sabe como otimizar melhor o número de declarações de namespace. Para obter um exemplo, consulte o WriteAttributeString(String, String, String, String) método.

  • Substitua a declaração de namespace atual por um novo namespace. No código a seguir, o método WriteAttributeString altera o URI do namespace do 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 gera a seguinte cadeia de caracteres XML:

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

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

Escrever dados digitados

O WriteValue método aceita um objeto CLR (Common Language Runtime), 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 XSD (linguagem de definição de esquema XML) e grava-o usando o WriteString método. 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 conforme as regras XmlConvert para esse tipo de esquema.

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

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

Fechar o gravador XML

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

Programação assíncrona

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

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

Considerações de segurança

Considere o seguinte ao trabalhar com a XmlWriter classe:

  • As exceções geradas pelo XmlWriter podem divulgar informações de 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 os dados que são passados para o método WriteDocType ou WriteRaw. Você não deve passar dados arbitrários para esses métodos.

  • Last updated on