Clase System.Xml.XmlWriter

  • Artículo

La clase XmlWriterescribe datos XML en una secuencia, archivo o cadena. Admite las recomendaciones de W3C para el lenguaje de marcado extensible XML 1.0 (cuarta edición) y los espacios de nombres en XML 1.0 (tercera edición).

Los miembros de la clase XmlWriter le permiten:

  • Comprobar que los caracteres son caracteres legales XML y que los nombres de elemento y atributo son nombres XML válidos.
  • Comprobar que el documento XML tiene el formato correcto.
  • Codificar bytes binarios en Base64 y BinHex, y escribir el texto resultante.
  • Pasar valores mediante tipos de Common Language Runtime en lugar de cadenas, para evitar tener que realizar conversiones de valor manualmente.
  • Escribir varios documentos en un flujo de salida.
  • Escribir nombres válidos, nombres completos y tokens de nombres.

Creación de un escritor XML

Para crear una instancia de XmlWriter, use el método XmlWriter.Create. Para especificar el conjunto de características que desea habilitar en el escritor XML, pase un XmlWriterSettings al método Create. De lo contrario, se usa la configuración predeterminada. Consulte las páginas de referencia de Create para más información.

Especificar el formato de salida

La clase XmlWriterSettings incluye varias propiedades que controlan cómo se da formato a la salida de XmlWriter:

Propiedad Descripción
Encoding Especifica la codificación de texto que se va a utilizar. El valor predeterminado es Encoding.UTF8.
Indent Indica si se van a aplicar sangrías a los elementos. El valor predeterminado es false (sin sangría).
IndentChars Especifica la cadena de caracteres que se va a utilizar para aplicar la sangría. El valor predeterminado es dos espacios.
NewLineChars Especifica la cadena de caracteres que se va a utilizar para los saltos de línea. El valor predeterminado es \r\n (retorno de carro, avance de línea) para plataformas que no son Unix y \n (avance de línea) para plataformas Unix.
NewLineHandling Especifica cómo tratar los caracteres de nueva línea.
NewLineOnAttributes Indica si se van a escribir atributos en una línea nueva. Indent debe establecerse en true cuando se use esta propiedad. El valor predeterminado es false.
OmitXmlDeclaration Indica si se va a escribir una declaración XML. El valor predeterminado es false.

Las propiedades Indent y IndentChars controlan cómo se da formato al espacio en blanco que es poco importante. Por ejemplo, para aplicar sangría a nodos de elemento:

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 NewLineOnAttributes para escribir cada atributo en una nueva línea con un nivel adicional de sangría:

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)

Cumplimiento de los datos

Un escritor XML usa dos propiedades de la clase XmlWriterSettings para comprobar el cumplimiento de los datos:

  • La propiedad CheckCharacters instruye al escritor XML que compruebe los caracteres y produzca una excepción XmlException si alguno de los caracteres está fuera del intervalo legal, tal como define el W3C.

  • La propiedad ConformanceLevel configura el escritor XML para compruebe que la secuencia que se escribe cumple con las reglas de un fragmento o documento XML 1.0 con formato correcto, tal y como lo define el W3C. En la siguiente tabla, se describen los tres niveles de cumplimiento. El valor predeterminado es Document. Para obtener más información, consulte la información sobre la propiedad XmlWriterSettings.ConformanceLevel y la enumeración System.Xml.ConformanceLevel.

    Nivel Descripción
    Document La salida de XML se ajusta a las reglas de un documento XML 1.0 con formato correcto y se puede procesar mediante cualquier procesador conforme.
    Fragment La salida de XML cumple con las reglas de un fragmento de documento XML 1.0 con formato correcto.
    Auto El escritor XML determina qué nivel de cumplimiento se va a comprobar (documento o fragmento) en función de los datos entrantes.

Escritura de elementos

Puede usar los métodos XmlWriter siguientes para escribir nodos de elemento. Para ver ejemplos, consulte los métodos enumerados.

Usar En
WriteElementString Escribir un nodo de elementos completo, incluyendo un valor de cadena.
WriteStartElement Para escribir un valor de elemento mediante varias llamadas de método. Por ejemplo, puede llamar a WriteValue para escribir un valor con establecimiento de tipos, a WriteCharEntity para escribir una entidad de caracteres, a WriteAttributeString para escribir un atributo o puede escribir un elemento secundario. Se trata de una versión más sofisticada del método WriteElementString.

Para cerrar el elemento, llame a los métodos WriteEndElement o WriteFullEndElement.
WriteNode Para copiar un nodo de elemento que se encuentra en la posición actual de un objeto XmlReader o XPathNavigator. Cuando se llama, copia todo del objeto de origen en la instancia de XmlWriter.

Escribir atributos

Puede usar los métodos XmlWriter siguientes para escribir atributos en nodos de elemento. Estos métodos también se pueden usar para crear declaraciones de espacio de nombres en un elemento, como se describe en la sección siguiente.

Usar En
WriteAttributeString Para escribir un nodo de atributos completo, incluyendo un valor de cadena.
WriteStartAttribute Para escribir el valor del atributo utilizando varias llamadas de métodos. Por ejemplo,puede llamar a WriteValue para escribir un valor con tipo. Se trata de una versión más sofisticada del método WriteElementString.

Para cerrar el elemento, llame al método WriteEndAttribute.
WriteAttributes Para copiar todos los atributos encontrados en la posición actual de un objeto XmlReader. Los atributos que se escriben dependen del tipo de nodo en el que está actualmente el lector:

- Para un nodo de atributo, escribe el atributo actual y, luego, el resto de los atributos hasta la etiqueta de cierre del elemento.
- Para un nodo de elemento, escribe todos los atributos contenidos en el elemento.
- Para un nodo de declaración XML, escribe todos los atributos en la declaración.
- Para todos los demás tipos de nodo, el método genera una excepción.

Administración de espacios de nombres

Los espacios de nombres se utilizan para calificar nombres de atributos y elementos en un documento XML. Los prefijos de espacio de nombres asocian elementos y atributos con espacios de nombres que, a su vez, se asocian a una referencias de URI. Los espacios de nombres crean nombres de elementos y atributos únicos en un documento XML.

XmlWriter mantiene una pila de espacios de nombres correspondiente a todos los espacios de nombres definidos en el ámbito del espacio de nombres actual. A la hora de escribir elementos y atributos, puede utilizar espacios de nombres de las siguientes formas:

  • Declare los espacios de nombres manualmente mediante el método WriteAttributeString. Esto puede resultar útil si conoce la mejor forma de optimizar el número de declaraciones de espacios de nombres. Para ver un ejemplo, consulte el método WriteAttributeString(String, String, String, String).

  • Invalidar la declaración de espacio de nombres actual con un espacio de nombres nuevo. En el código siguiente, el método WriteAttributeString cambia el URI del espacio de nombres del prefijo "x" de "123"a "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()

    El código genera la siguiente cadena XML:

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

  • Especifique un prefijo de espacio de nombres al escribir atributos o elementos. Muchos de los métodos usados para escribir elementos y atributos le permiten hacer esto. Por ejemplo, el método WriteStartElement(String, String, String) escribe una etiqueta de inicio y la asocia a un espacio de nombres y prefijo especificados.

Escritura de datos con tipo

El método WriteValue acepta un objeto de Common Language Runtime (CLR), convierte el valor de entrada en su representación de cadena según las reglas de conversión de tipos de datos del lenguaje de definición de esquema XML (XSD) y lo escribe mediante el método WriteString. Esto es más fácil que usar los métodos de la clase XmlConvert para convertir los datos con tipo en un valor de cadena antes de escribirlos.

Al escribir en texto, el valor con tipo se serializa en texto mediante las reglas de XmlConvert para ese tipo de esquema.

Para ver los tipos de datos XSD predeterminados que corresponden a los tipos CLR, consulte el método WriteValue.

XmlWriter también se puede utilizar para escribir en un almacén de datos XML. Por ejemplo, la clase XPathNavigator puede crear un objeto XmlWriter para crear nodos para un objeto XmlDocument. Si el almacén de datos tiene información de esquema disponible, el método WriteValue genera una excepción si intenta realizar la conversión a un tipo que no está permitido. Si el almacén de datos no tiene información de esquema disponible, el método WriteValue trata todos los valores como un tipo xsd:anySimpleType.

Cierre del escritor XML

Cuando se usan métodos XmlWriter para generar salida XML, los elementos y atributos no se escriben hasta que se llama al método Close. Por ejemplo, si usa XmlWriter para rellenar un objeto XmlDocument, no podrá ver los elementos y atributos escritos en el documento de destino hasta que cierre la instancia de XmlWriter.

Programación asincrónica

La mayoría de los métodos XmlWriter tienen homólogos asincrónicos que tienen "Async" al final de sus nombres de método. Por ejemplo, el equivalente asincrónico de WriteAttributeString es WriteAttributeStringAsync.

Para el método WriteValue, que no tiene un homólogo asincrónico, convierta el valor devuelto en una cadena y use el método WriteStringAsync en su lugar.

Consideraciones sobre la seguridad

Tenga en cuenta lo siguiente al trabajar con la clase XmlWriter:

  • Las excepciones generadas por XmlWriter pueden revelar información sobre la ruta de acceso que no se debe propagar a la aplicación. La aplicación debe detectar excepciones y procesarlas correctamente.

  • XmlWriter no valida los datos que se pasan a los métodos WriteDocType o WriteRaw. No se deben pasar datos arbitrarios a estos métodos.