Using Reflection to Serialize Types

One of the most prominent uses for reflection is serialization. Serialization is the process of turning an object into a stream of bytes that can be stored or transferred “elsewhere” and then used to reconstruct the object. You obviously cannot take an existing object and directly transfer it to another machine and expect it to work. Certain addresses and handles only correspond to memory on one machine or, for that matter, one process. In the past, MFC had a facility whereby an object could serialize and deserialize itself. The programmer decided which fields needed to be serialized through the code. Using reflection, it was possible to assist the programmer in serializing an object. The programmer no longer needed to depend on intimate knowledge of an object's format to serialize it. In addition, if the object changed, it would automatically serialize in a correct manner without the need to change the code that references it.

Although an object can be serialized in many formats, the predominant format used for objects that are to be passed between disparate systems is XML. (Remoting opens the possibility of transferring data as a binary stream, which is much faster, but it is not very portable or compatible with other machines.) XML is the format that this chapter will primarily focus attention toward in discussing serialization.

The .NET Framework uses two types of serialization (binary serialization and SoapRpc serialization used with ASP.NET and Web applications have been excluded): one used for remoting and one used for “manual” serialization directly to XML. Although both of these serialization methods use XML as the underlying format, remoting uses a specific dialect of XML known as Simple Object Access Protocol (SOAP).

Serialization Used in Remoting

To demonstrate SOAP serialization that is used in remoting (refer to Chapter 13, “Remoting”), consider the following code in Listings 17.13–17.15. The full source for this sample is in SerializationVehicleVehicleSoap and is part of the solution in SerializationVehicle.

Listing 17.13. Building a Vehicle List

public class VehicleBuilder
{
    public Vehicle Vehicle(string licenseNumber)
    {
        if (licenseNumber == "0")
        {
            Vehicle v = new Car();
            v.licenseNumber = licenseNumber;
            v.make = DateTime.Now;
            return v;
        }
        else if (licenseNumber == "1")
        {
            Vehicle v = new Bike();
            v.licenseNumber = licenseNumber;
            v.make = DateTime.Now;
            return v;
        }
        else
        {
            return null;
        }
    }
}

This is simply a utility class that allows you to easily build a vehicle based on the license number passed in (“0” is for a car, “1” is for a bike). Listing 17.14 shows the actual implementation of vehicle, car, and bike.

Listing 17.14. Defining a Vehicle

[Serializable]
public abstract class Vehicle
{
    public string licenseNumber;
    public DateTime make;
}

[Serializable]
public class Car : Vehicle
{
}

[Serializable]
public class Bike : Vehicle
{
}

Notice that all that is needed to serialize the object is to indicate that the object is serializable with the [Serializable] attribute. Vehicle is abstract to show that the serialization services can deal with polymorphism. That is all you have to do. Listing 17.15 shows a possible test.

Listing 17.15. Testing Serialization

public class VehicleSerializationTest
{
    public static int Main(string[] args)
    {
        VehicleBuilder vb = new VehicleBuilder();
        Vehicle [] va = new Vehicle[2];
        va[0] = vb.Vehicle("0");
        va[1] = vb.Vehicle("1");
        // Create an instance of the Soap Serializer class;
        // specify the type of object to serialize.
        Stream stream = File.Create("out.xml");
        SoapFormatter soap = new SoapFormatter();
        soap.Serialize(stream, va);
        stream.Close();
        stream = File.OpenRead("out.xml");
        va = (Vehicle [])soap.Deserialize(stream);
        stream.Close();
        Console.WriteLine("The first item is: {0} ", va[0]);
        Console.WriteLine("The second item is: {0} ", va[1]);
        return 0;
    }
}

The first task is to build up an array of Vehicles. Because of the license number passed in the first (va[0]), Vehicle is a Car and the second is a Bike. Next, you open up (Create) a file called out.xml. Using the SoapFormatter class, you serialize the Vehicle Array out to the file. It is not important, but it is interesting to look at what the format of the output file looks like:

<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/
/www.w3.org/2001/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http:/
/schemas.xmlsoap.org/soap/encoding/" xmlns:a1="http://schemas.microsoft.com/clr /nsassem
/VehicleSerialization/VehicleSoap">
  <SOAP-ENV:Body>
    <SOAP-ENC:Array SOAP-ENC:arrayType="a1:Vehicle[2]">
        <item href="#ref-3"/>
        <item href="#ref-4"/>
    </SOAP-ENC:Array>
    <a1:Car id="ref-3">
        <licenseNumber id="ref-5">0</licenseNumber>
        <make>2001-08-21T17:46:22.1585-05:00</make>
    </a1:Car>
    <a1:Bike id="ref-4">
        <licenseNumber id="ref-6">1</licenseNumber>
        <make>2001-08-21T17:46:22.1585-05:00</make>
    </a1:Bike>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

From this file, you can see that it created a Vehicle array with two Vehicles in it (arrayType=“a1:Vehicle[2]”). SOAP creates two items referring to “#ref-3” and “#ref-4.” Notice that “#ref-3” refers to a Car and “#ref-4” refers to a Bike (id=“ref-3” and id=“ref-4” respectively).

Go back to the sample in Listing 17.15. After the Vehicle array is serialized, then the file is immediately opened again and SoapFormatter deserializes the contents of the file, producing the Vehicle array again. Finally, each item is printed to the Console to verify that it was properly deserialized. The output looks like this:

The first item is: VehicleSerialization.Car
The second item is: VehicleSerialization.Bike

You got back exactly what you put in.

The next example shows how the serializer can descend multiple levels of an object graph. Portions of the code will be shown in Listings 17.16 and 17.17. The full source for this sample is in SerializationMultilevelMultilevelSoap and is part of the solution in SerializationMultilevel. You start out with a definition of the classes involved in Listing 17.16.

Listing 17.16. A Family Organization

[Serializable]
public class Person
{
    public string name;
    public double age;
}

[Serializable]
public class Marriage
{
    public Person husband;
    public Person wife;
}

[Serializable]
public class Family
{
    public Marriage couple;
    public Person [] children;
}

As you can see, this organization nests one class in another. This will test to see if you can maintain this structure when serializing and deserializing. Listing 17.17 shows the test used to exercise this serialization.

Listing 17.17. Building and Testing a Family Organization

public static int Main(string[] args)
{
    Person me = new Person();
    me.age = 43;
    me.name = "Kevin Burton";

    Person wife = new Person();
    wife.age = 50;
    wife.name = "Becky Burton";

    Marriage marriage = new Marriage();
    marriage.husband = me;
    marriage.wife = wife;

    Family family = new Family();
    family.couple = marriage;

    family.children = new Person[4];
    family.children[0] = new Person();
    family.children[0].age = 20;
    family.children[0].name = "Sarah";
    family.children[1] = new Person();
    family.children[1].age = 18;
    family.children[1].name = "Ann Marie";
    family.children[2] = new Person();
    family.children[2].age = 17;
    family.children[2].name = "Mike";
    family.children[3] = new Person();
    family.children[3].age = 13;
    family.children[3].name = "Rose";
    Stream stream = File.Create("out.xml");
    SoapFormatter soap = new SoapFormatter();
    soap.Serialize(stream, family);
    stream.Close();

    Console.WriteLine(family.couple.husband.name);
    Console.WriteLine(family.couple.wife.name);
    foreach(Person p in family.children)
    {
        Console.WriteLine(p.name);
    }

    Console.WriteLine("----------");
    stream = File.OpenRead("out.xml");
    soap = new SoapFormatter();
    family = (Family)soap.Deserialize(stream);
    stream.Close();
       Console.WriteLine(family.couple.husband.name);
    Console.WriteLine(family.couple.wife.name);
    foreach(Person p in family.children)
    {
        Console.WriteLine(p.name);
    }

    return 0;
}

The serialized output looks like this:

SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/
/www.w3.org/2001/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http:/
/schemas.xmlsoap.org/soap/encoding/" xmlns:a1="http://schemas.microsoft.com/clr/nsassem
/MultiLevel/ MultiLevelSoap">
<SOAP-ENV:Body>
  <a1:Family id="ref-1">
    <couple href="#ref-3"/>
    <children href="#ref-4"/>
  </a1:Family>
  <a1:Marriage id="ref-3">
    <husband href="#ref-5"/>
    <wife href="#ref-6"/>
  </a1:Marriage>
  <SOAP-ENC:Array id="ref-4" SOAP-ENC:arrayType="a1:Person[4]">
    <item href="#ref-7"/>
    <item href="#ref-8"/>
    <item href="#ref-9"/>
    <item href="#ref-10"/>
  </SOAP-ENC:Array>
  <a1:Person id="ref-5">
    <name id="ref-11">Kevin Burton</name>
    <age>43</age>
  </a1:Person>
  <a1:Person id="ref-6">
    <name id="ref-12">Becky Burton</name>
    <age>50</age>
  </a1:Person>
  <a1:Person id="ref-7">
    <name id="ref-13">Sarah</name>
    <age>20</age>
  </a1:Person>
  <a1:Person id="ref-8">
    <name id="ref-14">Ann Marie</name>
    <age>18</age>
  </a1:Person>
  <a1:Person id="ref-9">
    <name id="ref-15">Mike</name>
    <age>17</age>
  </a1:Person>
  <a1:Person id="ref-10">
    <name id="ref-16">Rose</name>
    <age>13</age>
  </a1:Person>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The output from the program looks like this:

Kevin Burton
Becky Burton
Sarah
Ann Marie
Mike
Rose
----------
Kevin Burton
Becky Burton
Sarah
Ann Marie
Mike
Rose

As was expected, what you put in is what you got out.

XML Serialization

To demonstrate XML serialization, or more precisely, serialization using System.Xml.Serialization, you will use the same classes that you used in the previous section. To start out, you will look at how the Vehicle class is serialized. Compare this implementation with the implementation described in Listings 17.13–17.15. Portions of the code will be shown in Listings 17.18–17.20. The full source to this sample is in SerializationVehicleVehicleXml and is part of the solution in SerializationVehicle.

You will begin by generating a Vehicle array. No changes are required to the VehicleBuilder class, so for this sample, assume that you are using the same code as in Listing 17.13. Listing 17.18 shows how little is changed from the previous section.

Listing 17.18. Vehicles Marked for Serialization

[XmlInclude(typeof(Car)), XmlInclude(typeof(Bike))]
public abstract class Vehicle
{
    public string licenseNumber;
    public DateTime make;
}

public class Car : Vehicle
{
}

public class Bike : Vehicle
{
}

If you did not want to serialize an abstract class, you could have just removed the [Serializable] attribute from the classes and that would be all that needed to be done. As it is, you need to add an [XmlInclude] attribute; otherwise, the XmlSerializer gets confused when trying to serialize a Vehicle array. Listing 17.19 shows the test program.

Listing 17.19. Testing Vehicle Serialization with XmlSerializer

public static int Main(string[] args)
{
    VehicleBuilder vb = new VehicleBuilder();
    Vehicle [] va = new Vehicle[2];
    va[0] = vb.Vehicle("0");
    va[1] = vb.Vehicle("1");

    // Create an instance of the XmlSerializer class;
    // specify the type of object to serialize.
    XmlSerializer serializer =
        new XmlSerializer(typeof(Vehicle[]));
    StreamWriter streamWriter = new StreamWriter("out.xml");
    serializer.Serialize(streamWriter, va);
    streamWriter.Close();

    StreamReader streamReader = new StreamReader("out.xml");
    va = (Vehicle [])serializer.Deserialize(streamReader);
    streamReader.Close();

    Console.WriteLine("The first item is: {0} ", va[0]);
    Console.WriteLine("The second item is: {0} ", va[1]);

    return 0;
}

Just like before, you create a Vehicle array first. Then instead of using a SoapFormatter, you use XmlSerializer. The Vehicle array is serialized to “out.xml”. This file now looks like this:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfVehicle xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/
/www.w3.org/2001/XMLSchema">
  <Vehicle xsi:type="Car">
    <licenseNumber>0</licenseNumber>
    <make>2001-08-21T22:04:59.2750080-05:00</make>
  </Vehicle>
  <Vehicle xsi:type="Bike">
    <licenseNumber>1</licenseNumber>
    <make>2001-08-21T22:04:59.2750080-05:00</make>
  </Vehicle>
</ArrayOfVehicle>

This is a little more readable than the SOAP version, but the same information is contained here. It has been said that programmatic types dominate serialization in System.Runtime.Serialization, which is used by remoting. In other words, the serialization scheme used for System.Runtime.Serialization is more centered in CLR types than in XML types if a conflict exists. With serialization using System.Xml.Serialization, the focus is more on XML types. A little of that bias can be seen in the requirement to use [XmlInclude] when serializing an abstract class. More importantly, using the attributes associated with System.Xml.Serialization gives the programmer a great deal of flexibility in mapping between CLR types and XML types.

This mapping is achieved by using an optional tool called the XML Schema Design Tool (xsd.exe). If the preceding vehicle class was put into a library (VehicleLibrary.dll), then you could run xsd.exe on the library like this:

xsd VehicleLibrary.dll

This would generate a file 'schema0.xsd' that looks like this:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="Vehicle" nillable="true" type="Vehicle" />
  <xs:complexType name="Vehicle" abstract="true">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="1" name="licenseNumber" type="xs:string" />
      <xs:element minOccurs="1" maxOccurs="1" name="make" type="xs:dateTime" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="Automobile">
    <xs:complexContent mixed="false">
      <xs:extension base="Vehicle" />
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="Bicycle">
    <xs:complexContent mixed="false">
      <xs:extension base="Vehicle" />
    </xs:complexContent>
  </xs:complexType>
  <xs:element name="Car" nillable="true" type="Car" />
  <xs:element name="Bike" nillable="true" type="Bike" />
</xs:schema>

This schema can be used to validate the XML coming into the system and that was generated by XmlSerializer. Because the sample that is shown both generates the XML and generates the schema as well, it is difficult to show the significance.

Suppose that the XML document must have the tags “Car” and “Bike” changed to “Automobile” and “Bicycle.” In that case, you would just need to modify the Vehicle class:

[XmlType("Automobile")]
public class Car : Vehicle
{
}

[XmlType("Bicycle")]
public class Bike : Vehicle
{
}

Now the XML that is generated by the XmlSerializer looks like this:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfVehicle xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/
/www.w3.org/2001/XMLSchema">
  <Vehicle xsi:type="Automobile">
    <licenseNumber>0</licenseNumber>
    <make>2001-08-21T23:04:57.6792592-05:00</make>
  </Vehicle>
  <Vehicle xsi:type="Bicycle">
    <licenseNumber>1</licenseNumber>
    <make>2001-08-21T23:04:57.6792592-05:00</make>
  </Vehicle>
</ArrayOfVehicle>

If the xsd.exe tool were run on the same library, it would generate the following:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="Vehicle" nillable="true" type="Vehicle" />
  <xs:complexType name="Vehicle" abstract="true">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="1" name="licenseNumber" type="xs:string" />
      <xs:element minOccurs="1" maxOccurs="1" name="make" type="xs:dateTime" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="Automobile">
    <xs:complexContent mixed="false">
      <xs:extension base="Vehicle" />
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="Bicycle">
    <xs:complexContent mixed="false">
      <xs:extension base="Vehicle" />
    </xs:complexContent>
  </xs:complexType>
  <xs:element name="Automobile" nillable="true" type="Automobile" />
  <xs:element name="Bicycle" nillable="true" type="Bicycle" />
</xs:schema>

Now the schema will properly validate XML documents coming into the system, and you will generate proper XML documents. (If this requirement were imposed on you, it would be likely that the external source or destination of the document would already have a schema that you would use to generate classes.) Notice that the class names (in other words, the CLR types) have not changed. The other XML attributes allow for similar flexibility in mapping CLR types to XML types.