Creación de código XML correcto con XmlTextWriter

Actualización: November 2007

La clase XmlTextWriter, derivada de la clase XmlWriter, escribe código XML en un archivo, consola, secuencia y otros tipos de salida. Al escribir código XML, los métodos realizan un trabajo adicional para crear XML con un formato correcto. En la tabla siguiente se ofrece una lista de los métodos que se encargan de asegurar que los datos tienen un formato correcto.

Las tareas adicionales siguientes son realizadas por la clase XmlTextWriter para asegurar que el formato del código XML es correcto:

• Garantiza que los elementos XML se escriben en el orden apropiado. Por ejemplo, no permitirá escribir un atributo fuera de un elemento, un bloque CDATA dentro de un atributo ni varios elementos raíz. Además, asegura que la declaración <?xml se encuentra la primera y que el nodo <!DOCTYPE se halla después del elemento raíz.

• Garantiza que el valor y formato del atributo xml:space es correcto y asegura que su valor es aceptable de acuerdo con la recomendación del lenguaje de marcado extensible (XML) 1.0 (Segunda Edición) del World Wide Web Consortium (W3C). En el ejemplo siguiente se muestra el uso de un valor válido para el atributo xml:space del método WriteAttributeString:

  w.WriteAttributeString("xml:space", "", "preserve");
  

  Valores válidos para el atributo xml:space son default y preserve. Si el valor del argumento no es ninguno de éstos, se inicia una excepción ArgumentException.

• Comprueba cuándo se usa una cadena como parámetro, (por ejemplo Null==String.Empty y String.Empty), y si sigue las reglas del W3C.

En la tabla siguiente se muestran métodos y propiedades adicionales definidos por la clase XmlTextWriter que no se heredan ni definen en la clase XmlWriter, ni se heredan de Object.

En el ejemplo siguiente se crea una salida XML mediante la clase XmlTextWriter.

Shared Sub WriteQuote(writer As XmlWriter, symbol As String, price As Double, change As Double, volume As Long)
   writer.WriteStartElement("Stock")
   writer.WriteAttributeString("Symbol", symbol)
   writer.WriteElementString("Price", XmlConvert.ToString(price))
   writer.WriteElementString("Change", XmlConvert.ToString(change))
   writer.WriteElementString("Volume", XmlConvert.ToString(volume))
   writer.WriteEndElement()
End Sub 'WriteQuote

Public Shared Sub Main()
   Dim writer As New XmlTextWriter(Console.Out)
   writer.Formatting = Formatting.Indented
   WriteQuote(writer, "MSFT", 74.125, 5.89, 69020000)
   writer.Close()
End Sub 'Main

static void WriteQuote(XmlWriter writer, string symbol, 
                double price, double change, long volume)
{
   writer.WriteStartElement("Stock");
   writer.WriteAttributeString("Symbol", symbol);
   writer.WriteElementString("Price", XmlConvert.ToString(price));
   writer.WriteElementString("Change", XmlConvert.ToString(change));
   writer.WriteElementString("Volume", XmlConvert.ToString(volume));
   writer.WriteEndElement();
}

public static void Main(){
    XmlTextWriter writer = new XmlTextWriter(Console.Out);
    writer.Formatting = Formatting.Indented;
    WriteQuote(writer, "MSFT", 74.125, 5.89, 69020000);
    writer.Close();
}

Resultados

<Stock Symbol="MSFT">
      <Price>74.125</Price>
      <Change>5.89</Change>
      <Volume>69020000</Volume>
</Stock>

La entrada del método WriteQuote es el símbolo Stock, que se proporciona en una variable de tipo string. El precio y el cambio se declaran como double, y el volumen es long. Para convertir estas variables en cadenas, se utiliza la clase XmlConvert. Esta clase contiene métodos que convierten todos los tipos de datos en cadenas. Además, la clase XmlConvert posee métodos que realizan la conversión opuesta al convertir las cadenas a tipos de datos de Microsoft .NET Framework. Para obtener más información, vea Codificación de caracteres de nombres XML y conversión de tipos de datos XML.

Para consultar un ejemplo de código en el que se demuestre cómo escribir XML en un archivo, vea XmlTextWriter.WriteProcessingInstruction. Para consultar un ejemplo de código en el que se demuestre cómo escribir XML en la consola, vea XmlTextWriter.WriteString.

En el código siguiente se muestra cómo escribir un elemento que produce <price>19.95</price>:

'Write the price.
writer.WriteElementString("price", "19.95")

//Write the price.
writer.WriteElementString("price", "19.95");

En el código siguiente se muestra cómo escribir un atributo que produce <element name="purchaseOrder"/>:

writer.WriteStartElement("element")
writer.WriteAttributeString("name", "purchaseOrder")
writer.WriteEndElement()

writer.WriteStartElement("element"); 
writer.WriteAttributeString("name", "purchaseOrder"); 
writer.WriteEndElement();

El método WriteAttributeString escribe atributos y declaraciones de espacio de nombres

El método WriteAttributeString tiene dos tareas diferentes. La primera es escribir atributos y asociarlos con un usuario definido en el prefijo de espacio de nombres. La segunda tarea consiste en generar las declaraciones de espacios de nombres. Si se escriben atributos y el parámetro localname es xmlns, se considera que este método crea una declaración de espacio de nombres.

En el ejemplo de código siguiente, el método WriteAttributeString se utiliza para escribir atributos dentro de un elemento.

'Write the genre attribute.
writer.WriteAttributeString("genre", "novel")
'Write the ISBN attribute.
writer.WriteAttributeString("ISBN", "1-8630-014")

//Write the genre attribute.
writer.WriteAttributeString("genre", "novel");
//Write the ISBN attribute.
writer.WriteAttributeString("ISBN", "1-8630-014");

El método WriteAttributeString también establece secuencias de escape para el contenido de texto del atributo en función de lo que encuentra. Si se usan comillas dobles, el método XmlTextWriter establece secuencias de escape para ellas en el contenido de texto del valor del atributo con &quot;. Si se usan comillas simples, establece secuencias de escape del contenido de texto del valor del atributo con &apos;.

Para generar declaraciones de espacios de nombres, hay un método WriteAttributeString sobrecargado que permite a la aplicación definir una declaración de espacio de nombres. En el ejemplo de código siguiente se crean dos espacios de nombres predeterminados. La primera declaración enlaza todos los elementos sin prefijo a la primera declaración de espacio de nombres mientras que cualquier elemento declarado con un prefijo "po" se enlaza a la segunda declaración de espacio de nombres.

' Write the default namespace, identified as xmlns with no prefix
writer.WriteAttributeString("xmlns", Nothing, "http://www.w3.org/2000/10/XMLSchema")
' Write a namespace for the purchase order with a prefix of "po"
writer.WriteAttributeString("xmlns", "po", Nothing, "https://contoso.com/po")

// Write the default namespace, identified as xmlns with no prefix
writer.WriteAttributeString("xmlns", null, "http://www.w3.org/2000/10/XMLSchema");
// Write a namespace for the purchase order with a prefix of "po"
writer.WriteAttributeString("xmlns", "po", null, "https://contoso.com/po");

Método Close

El método Close comprueba que el documento XML sea válido cuando se cierra la secuencia. Esto evita la creación de documentos XML que no sean válidos y asegura que el código XML sea correcto. Además de cerrar la secuencia, el método Close también llama a todos los métodos WriteEnd<xxx> necesarios para cerrar el documento.

Pares de métodos

Los métodos de la clase XmlWriter también vienen en pares: los pares de métodos WriteStartDocument y WriteEndDocument, WriteStartElement y WriteEndElement, y WriteStartAttribute y WriteEndAttribute. Por ejemplo, con estos métodos se pueden crear atributos o elementos anidados. Estos pares de métodos se utilizan para crear un documento XML y atributos o elementos complejos.

WriteStartDocument y WriteEndDocument (Métodos)

El método WriteStartDocument inicia un documento nuevo y escribe la declaración XML con el atributo de versión establecido a "1.0". El método WriteEndDocument cierra ese documento. Antes de la siguiente llamada al método WriteStartDocument para empezar a escribir en el próximo documento, se pueden modificar el formato, la sangría y otras propiedades. El método WriteStartDocument reconoce mediante programación que se está escribiendo un documento XML y aplica las reglas para la raíz. Si no se emplea este método, se crea un fragmento de XML y se comprueba si su formato es correcto. No se aplican las reglas para la raíz. En el ejemplo de código siguiente se muestra el principio y el final de un documento

' Write the XML declaration.
writer.WriteStartDocument()
. . .
' Close the document.
writer.WriteEndDocument()

// Write the XML declaration. 
writer.WriteStartDocument();
. . .
// Close the document.
writer.WriteEndDocument();

WriteStartElement y WriteEndElement (Métodos)

El par de métodos WriteStartElement y WriteEndElement delimita uno o varios elementos. En todos los métodos WriteStartElement invalidados, para la etiqueta de inicio se requiere un nombre local como parámetro. En el código siguiente se utiliza el par de métodos WriteStartElement y WriteEndElement.

' Write the title.
writer.WriteStartElement("title")
writer.WriteString("The Handmaid's Tale")
writer.WriteEndElement()

// Write the title.
writer.WriteStartElement("title");
writer.WriteString("The Handmaid's Tale");
writer.WriteEndElement();

Resultados

<title>The Handmaid's Tale</title>

El método WriteStartElement proporciona una firma de método invalidado que permite al código especificar prefijos de espacio de nombres para sus elementos. Para obtener más información, vea Prefijos de espacio de nombres de elemento en XmlTextWriter.

WriteStartAttribute y WriteEndAttribute (Métodos)

El par de métodos WriteStartAttribute y WriteEndAttribute es similar a los otros métodos de inicio y finalización, excepto en que comienzan y finalizan atributos. WriteStartAttribute escribe el principio del atributo, el método WriteString se usa para escribir el valor del atributo y el método WriteEndAttribute finaliza la etiqueta del atributo. En el ejemplo de código siguiente se muestra el par de métodos WriteStartAttribute y WriteEndAttribute.

writer.WriteStartAttribute(prefix, "ISBN", "urn:samples")
writer.WriteString("1-861003-78")
writer.WriteEndAttribute()

writer.WriteStartAttribute(prefix, "ISBN", "urn:samples");
writer.WriteString("1-861003-78");
writer.WriteEndAttribute();

Resultados

<book bk:ISBN="1-861003-78">

El método WriteStartAttribute tiene un método sobrecargado que permite a una aplicación especificar un prefijo de espacio de nombres de modo que pueda asociar dicho prefijo con los atributos que escribe. Para obtener más información, vea Prefijos de espacio de nombres de atributo en XmlTextWriter.

Vea también

Conceptos

Formato de salida XML con XmlTextWriter

Características del espacio de nombres en XmlTextWriter

Referencia

XmlTextWriter

XmlTextWriter

XmlWriter

XmlWriter

Otros recursos

Escribir XML con XmlWriter