This documentation is archived and is not being maintained.

XmlValidatingReader.EntityHandling Property

Gets or sets a value that specifies how the reader handles entities.

[Visual Basic]
Public Property EntityHandling As EntityHandling
[C#]
public EntityHandling EntityHandling {get; set;}
[C++]
public: __property EntityHandling get_EntityHandling();
public: __property void set_EntityHandling(EntityHandling);
[JScript]
public function get EntityHandling() : EntityHandling;
public function set EntityHandling(EntityHandling);

Property Value

One of the EntityHandling values. If no EntityHandling is specified, it defaults to EntityHandling.ExpandEntities.

Exceptions

Exception Type Condition
ArgumentOutOfRangeException Invalid value was specified.

Remarks

This property can be changed on the fly and takes effect after the next Read call.

When EntityHandling is set to ExpandCharEntities, attribute values are only partially normalized. The reader normalizes each individual text node independently from the content of adjacent entity reference nodes.

To illustrate the difference between the entity handling modes consider the following XML:

<!DOCTYPE doc [<!ENTITY num "123">]>
 <doc> &#65; &num; </doc>

When EntityHandling is set to ExpandEntities the "doc" element node contains one text node with the expanded entity text:

Depth NodeType Name Value
1 Text   A 123

When EntityHandling is set to ExpandCharEntites, and WhitespaceHandling is set to Significant or All, the "doc" element expands the character entity and returns the general entity as a node:

Depth NodeType Name Value
1 Text   A
1 EntityReference num  
1 SignificantWhitespace    

Example

[Visual Basic, C#, C++] The following example uses the ResolveEntity method to expand a general entity.

[Visual Basic] 
Imports System
Imports System.IO
Imports System.Xml

Public Class Sample
    
    Public Shared Sub Main()
        Dim reader As XmlTextReader = Nothing
        
        Try
            'Load the reader with the XML file.
            reader = New XmlTextReader("book1.xml")
            reader.WhitespaceHandling = WhitespaceHandling.None
            
            'Parse the file and display each node.
            While reader.Read()
                If reader.HasValue Then
                    Console.WriteLine("({0})  {1}={2}", reader.NodeType, reader.Name, reader.Value)
                Else
                    Console.WriteLine("({0}) {1}", reader.NodeType, reader.Name)
                End If
            End While
        
        Finally
            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()
  {
    XmlTextReader reader = null;

    try
    {           
        //Load the reader with the XML file.
        reader = new XmlTextReader("book1.xml");
        reader.WhitespaceHandling = WhitespaceHandling.None;

        //Parse the file and display each node.
        while (reader.Read())
        {
           if (reader.HasValue)
             Console.WriteLine("({0})  {1}={2}", reader.NodeType, reader.Name, reader.Value);
           else
             Console.WriteLine("({0}) {1}", reader.NodeType, reader.Name);
         }           
     }

     finally
     {
       if (reader!=null)
         reader.Close();
     }
  }
} // End class

[C++] 
#using <mscorlib.dll>
#using <System.Xml.dll>
using namespace System;
using namespace System::IO;
using namespace System::Xml;

int main()
{
   XmlTextReader* reader = 0;

   try
   {           
      //Load the reader with the XML file.
      reader = new XmlTextReader(S"book1.xml");
      reader->WhitespaceHandling = WhitespaceHandling::None;

      //Parse the file and display each node.
      while (reader->Read())
      {
         if (reader->HasValue)
            Console::WriteLine(S"({0})  {1}={2}", __box(reader->NodeType), reader->Name, reader->Value);
         else
            Console::WriteLine(S"({0}) {1}", __box(reader->NodeType), reader->Name);
      }           
   }

   __finally
   {
      if (reader!=0)
         reader->Close();
   }
}

The example uses the file, book1.xml, as input.

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

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

See Also

XmlValidatingReader Class | XmlValidatingReader Members | System.Xml Namespace

Show: