Export (0) Print
Expand All

XmlSerializer.UnreferencedObject Event

Occurs during deserialization of a SOAP-encoded XML stream, when the XmlSerializer encounters a recognized type that is not used (unreferenced).

[Visual Basic]
Public Event UnreferencedObject As UnreferencedObjectEventHandler
[C#]
public event UnreferencedObjectEventHandler UnreferencedObject;
[C++]
public: __event UnreferencedObjectEventHandler* UnreferencedObject;

[JScript] In JScript, you can handle the events defined by a class, but you cannot define your own.

Event Data

The event handler receives an argument of type UnreferencedObjectEventArgs containing data related to this event. The following UnreferencedObjectEventArgs properties provide information specific to this event.

Property Description
UnreferencedId Gets the ID of the object.
UnreferencedObject Gets the deserialized, but unreferenced, object.

Remarks

The UnreferencedObject event can only occur when the XmlSerializer is used to deserialize an XML document containing a SOAP message that conforms to section 5 of the World Wide Web Consortium (www.w3.org) document, "Simple Object Access Protocol (SOAP) 1.1".

Documents that conform to section 5 are in a special format. At the very least, such a document includes the main body of the SOAP message. However, rather than having all types defined inline in the document, some type definitions might be encoded as references to top-level elements in the document. Thus, for every element found in the main body that is a reference, there must be a corresponding element that contains the type definition. To correlate the referencing element and the type definition, the type definition has an id attribute set to a unique string ID and the referencing element has an href attribute that references the same ID.

<Group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" id="id1" n1:GroupName=".NET" GroupNumber="ZDI=" CreationDate="2002-05-02" xmlns:n1="http:'www.cpandl.com">
    <PosInt xsi:type="xsd:nonNegativeInteger">10000</PosInt>
    <GroupVehicle href="#id2" />
  </Group>
  <Vehicle id="id2" n1:type="Vehicle" xmlns:n1="http://www.w3.org/2001/XMLSchema-instance">
    <licenseNumber xmlns:q1="http://www.w3.org/2001/XMLSchema" n1:type="q1:string">1234</licenseNumber>
  </Vehicle>

The UnreferencedObject event will thus occur when there is a type definition found in the document, but no parameter in the main body references it. When the event occurs, you can retrieve the XML type of the unreferenced object by examining the UnreferencedObject property of the UnreferencedObjectEventArgs class. The XML ID of the object is returned by the UnreferencedId property.

The UnreferencedObject event should not be confused with the UnknownElement and UnknownNode events, which occur when there is no class member corresponding to the XML node or element type.

Example

[Visual Basic, C#, C++] The following example adds an UnreferencedObjectEventHandler to an XmlSerializer. The event is handled by the Serializer_UnreferencedObject method. To run the example, you should cut and paste the following XML into a file named "UnrefObj.xml".

<wrapper>
  <Group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" id="id1" n1:GroupName=".NET" xmlns:n1="http://www.cpandl.com">
   </Group>
<Vehicle id="id2" n1:type="Vehicle" xmlns:n1="http://www.w3.org/2001/XMLSchema-instance">
    <licenseNumber xmlns:q1="http://www.w3.org/2001/XMLSchema" n1:type="q1:string">ABCD</licenseNumber>
  </Vehicle>
<Vehicle id="id3" n1:type="Vehicle" xmlns:n1="http://www.w3.org/2001/XMLSchema-instance">
    <licenseNumber xmlns:q1="http://www.w3.org/2001/XMLSchema" n1:type="q1:string">1234</licenseNumber>
  </Vehicle>
</wrapper>
[Visual Basic] 
Imports System
Imports System.IO
Imports System.Text
Imports System.Xml
Imports System.Xml.Serialization
Imports System.Xml.Schema

' You must use the SoapIncludeAttribute to inform the XmlSerializer
' that the Vehicle type should be recognized when deserializing.
<SoapInclude(GetType(Vehicle))> _
Public Class Group
    Public GroupName As String 
   public GroupVehicle As Vehicle 
End Class

Public Class Vehicle
   Public licenseNumber As String 
End Class

 
Public Class Run
   Shared Sub Main()
      Dim test As Run = new Run()
      test.DeserializeObject("UnrefObj.xml")
   End Sub
   
   Public Sub DeserializeObject(filename As String)
      ' Create an instance of the XmlSerializer class.
      Dim myMapping As XmlTypeMapping = _
      (new SoapReflectionImporter().ImportTypeMapping _
      (GetType(Group)))
      Dim mySerializer As XmlSerializer =  _
      new XmlSerializer(myMapping)

      AddHandler mySerializer.UnreferencedObject, _
      AddressOf Serializer_UnreferencedObject

      ' Reading the file requires an  XmlTextReader.
      Dim reader As XmlTextReader = _
      new XmlTextReader(filename)
      reader.ReadStartElement()

      ' Deserialize and cast the object.
      Dim myGroup As Group  
      myGroup = CType( mySerializer.Deserialize(reader), Group)
      reader.ReadEndElement()
      reader.Close()
   End Sub
   
   Private Sub Serializer_UnreferencedObject _
   (sender As object , e As UnreferencedObjectEventArgs)
      Console.WriteLine("UnreferencedObject:")
      Console.WriteLine("ID: " + e.UnreferencedId)
      Console.WriteLine("UnreferencedObject: " + e.UnreferencedObject)
      Dim myVehicle As Vehicle = CType(e.UnreferencedObject, Vehicle)
      Console.WriteLine("License: " + myVehicle.licenseNumber)
       End Sub
 End Class
 
' The XML document should contain this information:

'<wrapper>

'  <Group xmlns:xsi="http:'www.w3.org/2001/XMLSchema-instance" 
'xmlns:xsd="http:'www.w3.org/2001/XMLSchema" id="id1" 
'n1:GroupName=".NET" xmlns:n1="http:'www.cpandl.com">
'   </Group>

'<Vehicle id="id2" n1:type="Vehicle" 
'xmlns:n1="http:'www.w3.org/2001/XMLSchema-instance">
'    <licenseNumber xmlns:q1="http:'www.w3.org/2001/XMLSchema" 
'n1:type="q1:string">ABCD</licenseNumber>
'  </Vehicle>

'<Vehicle id="id3" n1:type="Vehicle" 
'xmlns:n1="http:'www.w3.org/2001/XMLSchema-instance">
'    <licenseNumber xmlns:q1="http:'www.w3.org/2001/XMLSchema" 
'n1:type="q1:string">1234</licenseNumber>
'  </Vehicle>

'</wrapper>


[C#] 
using System;
using System.IO;
using System.Text;
using System.Xml;
using System.Xml.Serialization;
using System.Xml.Schema;

// You must use the SoapIncludeAttribute to inform the XmlSerializer
// that the Vehicle type should be recognized when deserializing.
[SoapInclude(typeof(Vehicle))]
public class Group
{
   public string GroupName;
   public Vehicle GroupVehicle;
}
 [SoapInclude(typeof(Vehicle))]
public class Vehicle
{
   public string licenseNumber;
}

public class Run
{
   public static void Main()
   {
      Run test = new Run();
      test.DeserializeObject("UnrefObj.xml");
   }
   
   public void DeserializeObject(string filename)
   {
      // Create an instance of the XmlSerializer class.
      XmlTypeMapping myMapping = 
      (new SoapReflectionImporter().ImportTypeMapping(
      typeof(Group)));
      XmlSerializer mySerializer =  
      new XmlSerializer(myMapping);
 
      mySerializer.UnreferencedObject += 
      new UnreferencedObjectEventHandler
      (Serializer_UnreferencedObject);

      // Reading the file requires an  XmlTextReader.
      XmlTextReader reader= 
      new XmlTextReader(filename);
      reader.ReadStartElement();

      // Deserialize and cast the object.
      Group myGroup; 
      myGroup = (Group) mySerializer.Deserialize(reader);
      reader.ReadEndElement();
      reader.Close();
   }

   private void Serializer_UnreferencedObject
   (object sender, UnreferencedObjectEventArgs e){
      Console.WriteLine("UnreferencedObject:");
      Console.WriteLine("ID: " + e.UnreferencedId);
      Console.WriteLine("UnreferencedObject: " + e.UnreferencedObject);
      Vehicle myVehicle = (Vehicle) e.UnreferencedObject;
      Console.WriteLine("License: " + myVehicle.licenseNumber);
   }
}

// The file named "UnrefObj.xml" should contain this XML:

// <wrapper>

//  <Group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
//xmlns:xsd="http://www.w3.org/2001/XMLSchema" id="id1" 
//n1:GroupName=".NET" xmlns:n1="http://www.cpandl.com">
//   </Group>

//<Vehicle id="id2" n1:type="Vehicle" 
//xmlns:n1="http://www.w3.org/2001/XMLSchema-instance">
//   <licenseNumber xmlns:q1="http://www.w3.org/2001/XMLSchema" 
//n1:type="q1:string">ABCD</licenseNumber>
//   </Vehicle>

//<Vehicle id="id3" n1:type="Vehicle" 
//xmlns:n1="http://www.w3.org/2001/XMLSchema-instance">
//    <licenseNumber xmlns:q1="http://www.w3.org/2001/XMLSchema" 
//n1:type="q1:string">1234</licenseNumber>
//  </Vehicle>

//</wrapper>


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

__gc public class Vehicle;
[SoapInclude(__typeof(Vehicle))]
__gc public class Vehicle
{
public:
   String* licenseNumber;
};

// You must use the SoapIncludeAttribute to inform the XmlSerializer
// that the Vehicle type should be recognized when deserializing.
[SoapInclude(__typeof(Vehicle))]
__gc public class Group
{
public:
   String* GroupName;
   Vehicle * GroupVehicle;
};

__gc public class Run 
{
public:
   void DeserializeObject(String* filename) 
   {
      // Create an instance of the XmlSerializer class.
      XmlTypeMapping * myMapping = 
         ((new SoapReflectionImporter()) -> ImportTypeMapping(__typeof(Group)));
      XmlSerializer* mySerializer = new XmlSerializer(myMapping);

      mySerializer -> UnreferencedObject += new UnreferencedObjectEventHandler
         (this, &Run::Serializer_UnreferencedObject);

      // Reading the file requires an  XmlTextReader.
      XmlTextReader* reader = new XmlTextReader(filename);
      reader -> ReadStartElement();

      // Deserialize and cast the object.
      Group * myGroup; 
      myGroup = dynamic_cast<Group*>(mySerializer -> Deserialize(reader));
      reader -> ReadEndElement();
      reader -> Close();
   }

private:
   void Serializer_UnreferencedObject(Object* /*sender*/, UnreferencedObjectEventArgs * e) 
   {
      Console::WriteLine(S"UnreferencedObject:");
      Console::WriteLine(S"ID: {0}", e -> UnreferencedId);
      Console::WriteLine(S"UnreferencedObject: {0}", e -> UnreferencedObject);
      Vehicle * myVehicle = dynamic_cast<Vehicle*>(e -> UnreferencedObject);
      Console::WriteLine(S"License: {0}", myVehicle -> licenseNumber);
   }
};

int main() 
{
   Run* test = new Run();
   test -> DeserializeObject(S"UnrefObj.xml");
}


// The file named S"UnrefObj.xml" should contain this XML:

// <wrapper>

//  <Group xmlns:xsi=S"http://www.w3.org/2001/XMLSchema-instance" 
//xmlns:xsd=S"http://www.w3.org/2001/XMLSchema" id=S"id1" 
//n1:GroupName=S".NET" xmlns:n1=S"http://www.cpandl.com">
//   </Group>

//<Vehicle id=S"id2" n1:type=S"Vehicle" 
//xmlns:n1=S"http://www.w3.org/2001/XMLSchema-instance">
//   <licenseNumber xmlns:q1=S"http://www.w3.org/2001/XMLSchema" 
//n1:type=S"q1:String*">ABCD</licenseNumber>
//   </Vehicle>

//<Vehicle id=S"id3" n1:type=S"Vehicle" 
//xmlns:n1=S"http://www.w3.org/2001/XMLSchema-instance">
//    <licenseNumber xmlns:q1=S"http://www.w3.org/2001/XMLSchema" 
//n1:type=S"q1:String*">1234</licenseNumber>
//  </Vehicle>

//</wrapper>

[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

XmlSerializer Class | XmlSerializer Members | System.Xml.Serialization Namespace | Attributes That Control Encoded SOAP Serialization | Generating SOAP Messages With XML Serialization | Introducing XML Serialization | Controlling XML Serialization Using Attributes | Examples of XML Serialization | The XML Schema Definition Tool and XML Serialization

Show:
© 2014 Microsoft