Clase System.Xml.XmlWriter

2025-06-19

La XmlWriter clase escribe datos XML en una secuencia, un archivo, un lector de texto o una cadena. Admite las recomendaciones de la W3C Extensible Markup Language (XML) 1.0 (cuarta edición) y Espacios de nombres en XML 1.0 (tercera edición).

Los miembros de la XmlWriter clase le permiten:

Compruebe que los caracteres son caracteres XML legales y que los nombres de elemento y atributo son nombres XML válidos.
Compruebe que el documento XML tiene el formato correcto.
Codifique bytes binarios como Base64 o BinHex y escriba el texto resultante.
Pase valores mediante tipos de Common Language Runtime en lugar de cadenas, para evitar tener que realizar manualmente conversiones de valor.
Escriba 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 XmlWriter instancia, use el XmlWriter.Create método . 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 Create páginas de referencia para obtener más información.

Especificar el formato de salida

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

Propiedad	Descripción
Encoding	Especifica la codificación de texto que se va a usar. 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 nueva línea. Indent debe establecerse en `true` al usar 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 formatea el espacio en blanco insignificante. 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)

Conformidad de datos

Un escritor XML usa dos propiedades de la XmlWriterSettings clase para comprobar si hay conformidad con los datos:

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

La ConformanceLevel propiedad configura el sistema de escritura XML para comprobar que la secuencia que se escribe cumple con las reglas de un documento o fragmento de documento XML 1.0 bien formado, tal y como define el W3C. Los tres niveles de conformidad se describen en la tabla siguiente. El valor predeterminado es Document. Para obtener más información, consulte la XmlWriterSettings.ConformanceLevel propiedad y la System.Xml.ConformanceLevel enumeración.

Nivel	Descripción
Document	La salida 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 XML se ajusta a las reglas de un fragmento de documento XML 1.0 bien formado.
Auto	El escritor XML determina qué nivel de comprobación de conformación se va a aplicar (documento o fragmento) en función de los datos entrantes.

Escritura de elementos

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

Uso	En
WriteElementString	Escriba un nodo de elemento completo, incluido 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 tipo, a WriteCharEntity para escribir una entidad de caracteres, a WriteAttributeString para escribir un atributo o escribir un elemento secundario. Se trata de una versión más sofisticada del WriteElementString método . Para cerrar el elemento, llame al método WriteEndElement o al método 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 desde el objeto de origen a la XmlWriter instancia.

Escribir atributos

Puede usar los métodos siguientes XmlWriter 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.

Uso	En
WriteAttributeString	Para escribir un nodo de atributo completo, incluido un valor de cadena.
WriteStartAttribute	Para escribir el valor del atributo mediante varias llamadas de método. Por ejemplo, puede llamar WriteValue para escribir un valor tipificado. Se trata de una versión más sofisticada del WriteElementString método . Para cerrar el elemento, llame al WriteEndAttribute método .
WriteAttributes	Para copiar todos los atributos encontrados en la posición actual de un XmlReader objeto. Los atributos que se escriben dependen del tipo de nodo en el que se coloca actualmente el lector: - Para un nodo de atributo, escribe el atributo actual y, a continuación, 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 de la declaración. - Para todos los demás tipos de nodo, el método produce una excepción.

Administración de espacios de nombres

Los espacios de nombres se usan para calificar los nombres de los elementos y atributos 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 garantizan la singularidad de los nombres de elementos y atributos 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. Al escribir elementos y atributos, puede usar espacios de nombres de las maneras siguientes:

Declare los espacios de nombres manualmente mediante el método WriteAttributeString. Esto puede ser útil cuando sepa cómo optimizar mejor el número de declaraciones de espacio de nombres. Para obtener un ejemplo, vea el WriteAttributeString(String, String, String, String) método .

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 para el 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 hacerlo. Por ejemplo, el WriteStartElement(String, String, String) método escribe una etiqueta de inicio y la asocia a un espacio de nombres y prefijo especificados.

Escritura de datos con tipo

El WriteValue método 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 esquemas XML (XSD) y lo escribe mediante el WriteString método . Esto es más fácil que usar los métodos de la clase XmlConvert para convertir los datos tipados en un valor de cadena antes de guardarlos.

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 WriteValue método .

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

Cerrar el escritor XML

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

Programación asincrónica

La mayoría de los XmlWriter métodos 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 WriteValue método , que no tiene un homólogo asincrónico, convierta el valor devuelto en una cadena y use el WriteStringAsync método en su lugar.

Consideraciones de seguridad

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

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 ningún dato que se pase al WriteDocType método o WriteRaw . No debe pasar datos arbitrarios a estos métodos.

Compartir a través de