Resolving Entities with the XmlValidatingReader

The EntityHandling property defines the way the XmlValidatingReader handles entities.

ExpandEntities

If the EntityHandling property is set to ExpandEntities, the XmlValidatingReader expands all entities in the XML document. Because entity text is expanded, the XmlNodeType of EntityReference does not appear. This is the default.

ExpandCharEntities

If the EntityHandling property is set to ExpandCharEntities, the XmlValidatingReader expands the character entities and returns the general entities as EntityReference node types (NodeType = XmlNodeType.EntityReference, Name = name of the entity, HasValue = false).

ResolveEntity

The ResolveEntity method can be used to expand the general entity for EntityReference nodes, allowing you to optimize entity handling by expanding the entity only when required. If the GetAttribute method is called, the general entities are expanded.

Entity handling can be changed at any time during the read process. Changes to the EntityHandling setting take effect when the Read method is next called.

The following code example creates an XmlValidatingReader with the XML input from book1.xml.

Imports System
Imports System.IO
Imports System.Xml
 
Public Class Sample
   
   Public Shared Sub Main()
      Dim reader As XmlValidatingReader = Nothing
      Dim txtreader As XmlTextReader = Nothing
      
      Try
         ' Create and load the XmlTextReader with the XML file.
         txtreader = New XmlTextReader("book1.xml")
         txtreader.WhitespaceHandling = WhitespaceHandling.None
         
         ' Create the XmlValidatingReader over the XmlTextReader.
         ' Set the reader to not expand general entities.
         reader = New XmlValidatingReader(txtreader)
         reader.ValidationType = ValidationType.None
         reader.EntityHandling = EntityHandling.ExpandCharEntities
         
         reader.MoveToContent()
         ' Move to the root element.
         reader.Read()
         ' Move to the title start tag.
         reader.Skip()
         ' Skip the title element.
         ' Read the miscellaneous start tag.  The reader is now positioned on
         ' the entity reference node.
         reader.ReadStartElement()
         
         ' Because EntityHandling is set to ExpandCharEntities, you must call 
         ' ResolveEntity to expand the entity.  The entity replacement text is 
         ' then parsed and returned as a child node.
         Console.WriteLine("Expand the entity...")
         reader.ResolveEntity()
         
         Console.WriteLine("The entity replacement text is returned as a text node.")
         reader.Read()
         Console.WriteLine("NodeType: {0} Value: {1}", reader.NodeType, reader.Value)
         
         Console.WriteLine("An EndEntity node closes the entity reference scope.")
         reader.Read()
         Console.WriteLine("NodeType: {0} Name: {1}", reader.NodeType, reader.Name)
      
      Finally
         If Not (txtreader Is Nothing) Then
            txtreader.Close()
         End If
         If Not (reader Is Nothing) Then
            reader.Close()
         End If
      End Try
   End Sub
   ' Main
End Class
' Sample
[C#]
using System;
using System.IO;
using System.Xml;

public class Sample
{
  public static void Main()
  {
     XmlValidatingReader reader = null;
     XmlTextReader txtreader = null;

     try
     {
       // Create and load the XmlTextReader with the XML file.
       txtreader = new XmlTextReader("book1.xml");
       txtreader.WhitespaceHandling = WhitespaceHandling.None;

       // Create the XmlValidatingReader over the XmlTextReader.
       // Set the reader to not expand general entities.
       reader = new XmlValidatingReader(txtreader);
       reader.ValidationType = ValidationType.None;
       reader.EntityHandling = EntityHandling.ExpandCharEntities;

       reader.MoveToContent();  
       // Move to the root element.
       reader.Read();  
       // Move to the title start tag.
       reader.Skip();  
       // Skip the title element.
      
       // Read the miscellaneous start tag.  The reader is now positioned on
       // the entity reference node.
       reader.ReadStartElement(); 

       // Because EntityHandling is set to ExpandCharEntities, you must call 
       // ResolveEntity to expand the entity.  The entity replacement text is 
       // then parsed and returned as a child node.
       
       Console.WriteLine("Expand the entity...");
       reader.ResolveEntity();  

       Console.WriteLine("The entity replacement text is returned as a text node.");
       reader.Read();  
       Console.WriteLine("NodeType: {0} Value: {1}", reader.NodeType ,reader.Value);

       Console.WriteLine("An EndEntity node closes the entity reference scope.");
       reader.Read();
       Console.WriteLine("NodeType: {0} Name: {1}", reader.NodeType,reader.Name);
     
    }
    finally
    {
       if (txtreader != null)
         txtreader.Close();
       if (reader != null)
         reader.Close();
    }
  }
}

The following outlines the contents of the input file, book1.xml, to be validated.

<?xml version='1.0' ?>
<!DOCTYPE book [<!ENTITY h 'hardcover'>]>
<book>
  <title>Pride And Prejudice</title>
  <misc>&h;</misc>
</book>

See Also

Validation of XML with Schemas | XmlValidatingReader.ResolveEntity Method