XmlDocument.CreateEntityReference (Método)

Si se conoce la entidad a la que se hace referencia, la lista de nodos secundarios del nodo XmlEntityReference se forma igual que la lista del nodo XmlEntity correspondiente.

Los espacios de nombres utilizados en el texto de reemplazo para la referencia a entidad se enlazan en el momento en que se configura el nodo primario del nodo de referencia a entidad; por ejemplo, cuando el nodo de referencia a entidad se inserta en el documento. Por ejemplo, dada la entidad siguiente:

<!ENTITY a "<b>test</b>">

Si se llama a CreateEntityReference("a"), se obtiene un único nodo del tipo EntityReference sin nodos secundarios. Si se anexa este nodo como nodo secundario del nodo siguiente,

<item xmlns="urn:1"/>

al llamar a AppendChild, se configura el nodo primario del nodo de referencia a entidad recién creado y los nodos secundarios se expanden en este contexto de espacio de nombres. El NamespaceURI del nodo de elemento secundario b será urn:1. Los nodos secundarios de la referencia a entidad no cambian aunque se desplace la referencia a entidad a un lugar del documento que tenga otro contexto de espacio de nombres predeterminado. Esto no sucede con los nodos de referencia a entidad existentes cuando se quitan y se insertan, ni con las referencias a entidades que se clonan mediante CloneNode. Sólo sucede con las referencias a entidades recién creadas.

Si la entidad correspondiente no se define en DocumentType al agregar el nodo de referencia a entidad, porque la referencia a entidad no está definida, el único nodo secundario será un nodo de texto vacío.

También se permiten las entidades integradas amp, lt, gt, apos y quot, que tendrán un nodo de texto secundario con el valor de carácter expandido adecuado.

Aunque este método crea el nuevo objeto en el contexto del documento, no lo agrega automáticamente al árbol del documento. Para agregar el nuevo objeto, se debe llamar explícitamente a uno de los métodos de inserción de nodos.

De acuerdo con la recomendación Extensible Markup Language (XML) 1.0 del Consorcio W3C (www.w3.org/TR/1998/REC-xml-19980210), los nodos EntityReference sólo se permiten en los nodos Element, Attribute y EntityReference.

En el ejemplo siguiente se crean dos nodos de referencia a entidad y se insertan en un documento XML.

using System;
using System.IO;
using System.Xml;

public class Sample
{
  public static void Main()
  {
    //Create the XmlDocument.
    XmlDocument doc = new XmlDocument();
    doc.LoadXml("<!DOCTYPE book [<!ENTITY h 'hardcover'>]>" +
                "<book genre='novel' ISBN='1-861001-57-5'>" +
                "<title>Pride And Prejudice</title>" +
                "<misc/>" +
                "</book>"); 

    //Create an entity reference node. The child count should be 0 
    //since the node has not been expanded.
    XmlEntityReference entityref = doc.CreateEntityReference("h");
    Console.WriteLine(entityref.ChildNodes.Count ); 

    //After the the node has been added to the document, its parent node
    //is set and the entity reference node is expanded.  It now has a child
    //node containing the entity replacement text. 
    doc.DocumentElement.LastChild.AppendChild(entityref);
    Console.WriteLine(entityref.FirstChild.InnerText);

    //Create and insert an undefined entity reference node.  When the entity
    //reference node is expanded, because the entity reference is undefined
    //the child is an empty text node.
    XmlEntityReference entityref2 = doc.CreateEntityReference("p");
    doc.DocumentElement.LastChild.AppendChild(entityref2);
    Console.WriteLine(entityref2.FirstChild.InnerText);

  }
}

.NET Framework

.NET Framework Client Profile

Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (no se admite el rol Server Core), Windows Server 2008 R2 (se admite el rol Server Core con SP1 o versiones posteriores; no se admite Itanium)

Referencia