XmlSerializer.UnreferencedObject Event
Assembly: System.Xml (in system.xml.dll)
'Declaration Public Event UnreferencedObject As UnreferencedObjectEventHandler 'Usage Dim instance As XmlSerializer Dim handler As UnreferencedObjectEventHandler AddHandler instance.UnreferencedObject, handler
/** @event */ public void add_UnreferencedObject (UnreferencedObjectEventHandler value) /** @event */ public void remove_UnreferencedObject (UnreferencedObjectEventHandler value)
In JScript, you can handle the events defined by a class, but you cannot define your own.
Not applicable.
The UnreferencedObject event only occurs when the XmlSerializer is used to deserialize an XML document that contains 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 can 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 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 that corresponds to the XML node or element type.
The following example adds an UnreferencedObjectEventHandler to an XmlSerializer. The event is handled by the Serializer_UnreferencedObject method. To run the example, 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>
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>
import System.*;
import System.IO.*;
import System.Text.*;
import System.Xml.*;
import System.Xml.Serialization.*;
import System.Xml.Schema.*;
// You must use the SoapIncludeAttribute to inform the XmlSerializer
// that the Vehicle type should be recognized when deserializing.
/** @attribute SoapInclude(Vehicle.class)
*/
public class Group
{
public String groupName;
public Vehicle groupVehicle;
} //Group
/** @attribute SoapInclude(Vehicle.class)
*/
public class Vehicle
{
public String licenseNumber;
} //Vehicle
public class Run
{
public static void main(String[] args)
{
Run test = new Run();
test.DeserializeObject("UnrefObj.xml");
} //main
public void DeserializeObject(String fileName)
{
// Create an instance of the XmlSerializer class.
XmlTypeMapping myMapping = (new SoapReflectionImporter()).
ImportTypeMapping(Group.class.ToType());
XmlSerializer mySerializer = new XmlSerializer(myMapping);
mySerializer.add_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();
} //DeserializeObject
private void Serializer_UnreferencedObject(Object sender,
UnreferencedObjectEventArgs e)
{
Console.WriteLine("UnreferencedObject:");
Console.WriteLine("ID: " + e.get_UnreferencedId());
Console.WriteLine("UnreferencedObject: " + e.get_UnreferencedObject());
Vehicle myVehicle = (Vehicle)e.get_UnreferencedObject();
Console.WriteLine("License: " + myVehicle.licenseNumber);
} //Serializer_UnreferencedObject
} //Run
// 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>
Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition
The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.Reference
XmlSerializer ClassXmlSerializer Members
System.Xml.Serialization Namespace
XmlAttributes
Other Resources
Introducing XML SerializationHow to: Specify an Alternate Element Name for an XML Stream
Controlling XML Serialization Using Attributes
Examples of XML Serialization
XML Schema Definition Tool (Xsd.exe)