Serialization Engines

There are four serialization engines in .NET Core:

• XmlSerializer (XML)

• JsonSerializer (JSON)

• The (somewhat redundant) data contract serializer (XML and JSON)

• The binary serializer (binary)

If you’re serializing to XML, you can choose between XmlSerializer and the data contract serializer. XmlSerializer offers greater flexibility on how the XML is structured, whereas the data contract serializer has the unique ability to preserve shared object references.

If you’re serializing to JSON, you also have a choice. JsonSerializer offers the best performance, whereas the data contract serializer has a few extra features due to its longer heritage. However, if you need extra features, a better choice is likely to be the third-party Json.NET library.

If you need to interoperate with legacy SOAP-based web services, the data contract serializer is the best choice.

And if you don’t care about the format, the binary serialization engine is the most powerful and easiest to use. The output, however, is not human-readable and it’s less version-tolerant than the other serializers.

Table 17-1 compares each of the engines. More stars equate to a better score.

Note that the XML serialization engine requires that you recycle the same XmlSerializer object for good performance.

Formatters

The output of the data contract and binary serializers is shaped by a pluggable formatter. The role of a formatter is the same with both serialization engines, although they use completely different classes to do the job.

A formatter shapes the final presentation to suit a particular medium or context of serialization. In .NET Core, the data contract serializer lets you choose between XML and JSON formatters, and in .NET Framework you can also choose a binary formatter. A binary formatter is designed to work in a context for which an arbitrary stream of bytes will do—typically a file/stream or proprietary messaging packet. Binary output is usually smaller than XML or JSON.

The binary serializer offers only a binary formatter in .NET Core (in .NET Framework, there’s also a SOAP formatter for XML-based messaging).

Explicit Versus Implicit Serialization

Serialization and deserialization can be initiated in two ways.

The first is explicitly, by requesting that a particular object be serialized or deserialized. When you serialize or deserialize explicitly, you choose both the serialization engine and the formatter.

In contrast, implicit serialization is initiated by .NET. This happens when:

• A serializer recursively serializes a child object.

• You use a feature that relies on serialization, such as Web API.

Web API can work with either XML or JSON serialization.

Implicit serialization is less prevalent in .NET Core than in .NET Framework, which includes WCF (implicitly using the data contract serializer), Remoting (implicitly using the binary serialization engine), and ASMX Web Services (implicitly using XmlSerializer).

Getting Started with Attribute-Based Serialization

To use XmlSerializer, you instantiate it and call Serialize or Deserialize with a Stream and object instance. To illustrate, suppose we define the following class:

public class Person
{
  public string Name;
  public int Age;
}

The following saves a Person to an XML file and then restores it:

Person p = new Person();
p.Name = "Stacey"; p.Age = 30;

var xs = new XmlSerializer (typeof (Person));

using (Stream s = File.Create ("person.xml"))
  xs.Serialize (s, p);

Person p2;
using (Stream s = File.OpenRead ("person.xml"))
  p2 = (Person) xs.Deserialize (s);

Console.WriteLine (p2.Name + " " + p2.Age);   // Stacey 30

Serialize and Deserialize can work with a Stream, XmlWriter/XmlReader, or TextWriter/TextReader. Here’s the resultant XML:

<?xml version="1.0"?>
<Person xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Name>Stacey</Name>
  <Age>30</Age>
</Person>

XmlSerializer can serialize types without any attributes—such as our Person type. By default, it serializes all public fields and properties on a type. You can exclude members that you don’t want serialized by applying the XmlIgnore attribute:

public class Person
{
  ...
  [XmlIgnore] public DateTime DateOfBirth;
}

XmlSerializer relies on a parameterless constructor for deserialization, throwing an exception if one is not present. (In our example, Person has an implicit parameterless constructor.) This also means that field initializers execute prior to deserialization:

public class Person
{
  public bool Valid = true;    // Executes before deserialization
}

Although XmlSerializer can serialize almost any type, it recognizes the following types and treats them specially:

• The primitive types, DateTime, TimeSpan, Guid, and nullable versions

• byte[] (which is converted to base 64)

• An XmlAttribute or XmlElement (whose contents are injected into the stream)

• Any type implementing IXmlSerializable

• Any collection type

The deserializer is version tolerant: it doesn’t complain if elements or attributes are missing or if superfluous data is present.

[XmlAttribute] public int Age;

public class Person
{
  [XmlElement ("FirstName")] public string Name;
  [XmlAttribute ("RoughAge")] public int Age;
}

<Person RoughAge="30" ...>
  <FirstName>Stacey</FirstName>
</Person>

[XmlRoot ("Candidate", Namespace = "http://mynamespace/test/")]
public class Person { ... }

public class Person
{
  [XmlElement (Order = 2)] public string Name;
  [XmlElement (Order = 1)] public int Age;
}

Subclasses and Child Objects

public class Person { public string Name; }

public class Student : Person { }
public class Teacher : Person { }

public void SerializePerson (Person p, string path)
{
  XmlSerializer xs = new XmlSerializer (typeof (Person));
  using (Stream s = File.Create (path))
    xs.Serialize (s, p);
}

[XmlInclude (typeof (Student))]
[XmlInclude (typeof (Teacher))]
public class Person { public string Name; }

XmlSerializer xs = new XmlSerializer (typeof (Person),
                     new Type[] { typeof (Student), typeof (Teacher) } );

<Person xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="Student">
  <Name>Stacey</Name>
</Person>

[XmlType ("Candidate")]
public class Student : Person { }

<Person xmlns:xsi="..."
        xsi:type="Candidate">

public class Person
{
  public string Name;
  public Address HomeAddress = new Address();
}

public class Address { public string Street, PostCode; }

Person p = new Person { Name = "Stacey" };
p.HomeAddress.Street = "Odo St";
p.HomeAddress.PostCode = "6020";

<Person ... >
  <Name>Stacey</Name>
  <HomeAddress>
    <Street>Odo St</Street>
    <PostCode>6020</PostCode>
  </HomeAddress>
</Person>

public class Address { public string Street, PostCode; }
public class USAddress : Address {  }
public class AUAddress : Address {  }

public class Person
{
  public string Name;
  public Address HomeAddress = new USAddress();
}

<Person ...>
  ...
  <HomeAddress xsi:type="USAddress">
    ...
  </HomeAddress>
</Person>

[XmlInclude (typeof (AUAddress))]
[XmlInclude (typeof (USAddress))]
public class Address
{
  public string Street, PostCode;
}

<Person ...>
  ...
  <USAddress>
    ...
  </USAddress>
</Person>

public class Person
{
  public string Name;

  [XmlElement ("Address", typeof (Address))]
  [XmlElement ("AUAddress", typeof (AUAddress))]
  [XmlElement ("USAddress", typeof (USAddress))]
  public Address HomeAddress = new USAddress();
}

Serializing Collections

XmlSerializer recognizes and serializes concrete collection types without intervention:

public class Person
{
  public string Name;
  public List<Address> Addresses = new List<Address>();
}

public class Address { public string Street, PostCode; }

Here’s the XML to which this serializes:

<Person ... >
  <Name>...</Name>
  <Addresses>
    <Address>
      <Street>...</Street>
      <Postcode>...</Postcode>
    </Address>
    <Address>
      <Street>...</Street>
      <Postcode>...</Postcode>
    </Address>
    ...
  </Addresses>
</Person>

The [XmlArray] attribute lets you rename the outer element (i.e., Addresses).

The [XmlArrayItem] attribute lets you rename the inner elements (i.e., the Address elements).

For instance, the following class:

public class Person
{
  public string Name;

  [XmlArray ("PreviousAddresses")]
  [XmlArrayItem ("Location")]
  public List<Address> Addresses = new List<Address>();
}

serializes to this:

<Person ... >
  <Name>...</Name>
  <PreviousAddresses>
    <Location>
      <Street>...</Street>
      <Postcode>...</Postcode>
    </Location>
    <Location>
      <Street>...</Street>
      <Postcode>...</Postcode>
    </Location>
    ...
  </PreviousAddresses>
</Person>

The XmlArray and XmlArrayItem attributes also allow you to specify XML namespaces.

To serialize collections without the outer element, for example:

<Person ... >
  <Name>...</Name>
  <Address>
    <Street>...</Street>
    <Postcode>...</Postcode>
  </Address>
  <Address>
    <Street>...</Street>
    <Postcode>...</Postcode>
  </Address>
</Person>

instead add [XmlElement] to the collection field or property:

public class Person
{
  ...
  [XmlElement ("Address")]
  public List<Address> Addresses = new List<Address>();
}

<Person ... >
  <Name>...</Name>
  <Addresses>
    <Address xsi:type="AUAddress">
    ...

<Person ... >
  <Name>...</Name>
  <!—start of optional outer element—>
  <AUAddress>
    <Street>...</Street>
    <Postcode>...</Postcode>
  </AUAddress>
  <USAddress>
    <Street>...</Street>
    <Postcode>...</Postcode>
  </USAddress>
  <!—end of optional outer element—>
</Person>

[XmlArrayItem ("Address",   typeof (Address))]
[XmlArrayItem ("AUAddress", typeof (AUAddress))]
[XmlArrayItem ("USAddress", typeof (USAddress))]
public List<Address> Addresses = new List<Address>();

[XmlElement ("Address",   typeof (Address))]
[XmlElement ("AUAddress", typeof (AUAddress))]
[XmlElement ("USAddress", typeof (USAddress))]
public List<Address> Addresses = new List<Address>();

IXmlSerializable

Although attribute-based XML serialization is flexible, it has limitations. For instance, you cannot add serialization hooks—nor can you serialize nonpublic members. It’s also awkward to use if the XML might present the same element or attribute in a number of different ways.

On that last issue, you can push the boundaries somewhat by passing an XmlAttributeOverrides object into XmlSerializer’s constructor. There comes a point, however, when it’s easier to take an imperative approach. This is the job of IXmlSerializable:

public interface IXmlSerializable
{
  XmlSchema GetSchema();
  void ReadXml (XmlReader reader);
  void WriteXml (XmlWriter writer);
}

Implementing this interface gives you total control over the XML that’s read or written.

The rules for implementing IXmlSerializable are as follows:

• ReadXml should read the outer start element, then the content, and then the outer end element.

• WriteXml should write just the content.

Here’s an example:

using System;
using System.Xml;
using System.Xml.Schema;
using System.Xml.Serialization;

public class Address : IXmlSerializable
{
  public string Street, PostCode;

  public XmlSchema GetSchema() { return null; }

  public void ReadXml(XmlReader reader)
  {
    reader.ReadStartElement();
    Street   = reader.ReadElementContentAsString ("Street", "");
    PostCode = reader.ReadElementContentAsString ("PostCode", "");
    reader.ReadEndElement();
  }

  public void WriteXml (XmlWriter writer)
  {
    writer.WriteElementString ("Street", Street);
    writer.WriteElementString ("PostCode", PostCode);
  }
}

Serializing and deserializing an instance of Address via XmlSerializer automatically calls the WriteXml and ReadXml methods. Further, if Person were defined like this:

public class Person
{
  public string Name;
  public Address HomeAddress;
}

IXmlSerializable would be called upon selectively to serialize the HomeAddress field.

We describe XmlReader and XmlWriter at length in the first section of Chapter 11. Also in Chapter 11, in “Patterns for Using XmlReader/XmlWriter” we provide examples of IXmlSerializable-ready classes.

Getting Started

Assuming Person is defined like this:

public class Person
{
  public string Name { get; set; }
}

we can serialize it to a JSON string by calling JsonSerializer.Serialize:

var p = new Person { Name = "Ian" };
string json = JsonSerializer.Serialize (p,
                new JsonSerializerOptions { WriteIndented = true });

Here is the result:

{
  Name: "Ian"
}

The JsonSerializer.Deserialize method does the reverse, and deserializes:

Person p2 = JsonSerializer.Deserialize<Person> (json);

The JSON serializer ignores fields, and serializes only properties.

Serializing Child Objects

Suppose that we define Person to have a home and work Address:

public class Address
{
  public string Street { get; set; }
  public string PostCode { get; set; }
}

public class Person
{
  public string Name { get; set; }
  public Address HomeAddress { get; set; }
  public Address WorkAddress { get; set; }
}

We can serialize this with no extra work:

var home = new Address { Street = "1 Main St.", PostCode="11235" };
var work = new Address { Street = "4 Elm Ln.", PostCode="31415" };
var p = new Person { Name = "Ian", HomeAddress = home, WorkAddress = work };

Console.WriteLine (JsonSerializer.Serialize (p,
                 new JsonSerializerOptions { WriteIndented = true } ));

Upon encountering HomeAddress and WorkAddress, the serializer creates JSON objects:

{
  "Name": "Ian",
  "HomeAddress": {
    "Street": "1 Main St.",
    "PostCode": "11235"
  },
  "WorkAddress": {
    "Street": "4 Elm Ln.",
    "PostCode": "31415"
  }
}

Note, though, what happens when we set HomeAddress and WorkAddress to the same object instance:

var p = new Person { Name = "Ian", HomeAddress = home, WorkAddress = home };

Here’s the output:

{
  "Name": "Ian",
  "HomeAddress": {
    "Street": "1 Main St.",
    "PostCode": "11235"
  },
  "WorkAddress": {
    "Street": "1 Main St.",
    "PostCode": "11235"
  }
}

There is no information in the JSON to indicate that HomeAddress and WorkAddress were originally the same object instance. When deserialized, two separate instances of Address will be created and assigned to the respective properties.

This also means that JsonSerializer cannot handle cycles in the object graph. To illustrate, suppose that we add a Partner property to our Person class:

public class Person
{
  ...
  public Person Partner { get; set; }
}

The following throws a JsonException because sara and ian contain a reference to each other:

var sara = new Person { Name = "Sara" };
var ian = new Person { Name = "Ian", Partner = sara };
sara.Partner = ian;
string json = JsonSerializer.Serialize (ian);   // throws

Support for cyclic references is planned in .NET Core 5.0.

Serializing Collections

JsonSerializer automatically serializes collections. Collections can appear in an object’s properties as well as in the root object itself. We can illustrate the latter by using the Person and Address classes that we defined at the beginning of the preceding section:

var sara = new Person { Name = "Sara" };
var ian = new Person { Name = "Ian" };

Console.WriteLine (JsonSerializer.Serialize (new[] { sara, ian },
  new JsonSerializerOptions { WriteIndented = true }));

Here’s the result:

[
  {
    "Name": "Sara"
  },
  {
    "Name": "Ian"
  }
]

The following deserializes the JSON:

Person[] people = JsonSerializer.Deserialize<Person[]> (json);

It is possible to serialize a collection containing differently typed objects:

var sara = new Person { Name = "Sara" };
var addr = new Address { Street = "1 Main St.", PostCode = "11235" };

Console.WriteLine (JsonSerializer.Serialize (new object[] { sara, addr },
  new JsonSerializerOptions { WriteIndented = true }));

This yields the following:

[
  {
    "Name": "Sara"
  },
  {
    "Street": "1 Main St.",
    "PostCode": "11235"
  }
]

Deserializing such collections is clumsy because the type of each element is not written into the JSON. You need to take the low-level approach of deserializing to JsonElement[] and then enumerating each property:

var deserialized = JsonSerializer.Deserialize<JsonElement[]>(json);
foreach (var element in deserialized)
{
  foreach (var prop in element.EnumerateObject())
    Console.WriteLine ($"{prop.Name}: {prop.Value}");
  Console.WriteLine ("---");
}

// Output:
Name: Sara
---
Street: 1 Main St.
PostCode: 11235

We describe how to use JsonElement in “JsonDocument”.

Controlling Serialization with Attributes

You can control the serialization process with attributes defined in the System.Text.Json.Serialization namespace.

public class Person
{
  public string Name { get; set; }

  [JsonIgnore]
  public decimal NetWorth { get; set; }   // Not serialized
}

public class Person
{
  [JsonPropertyName("FullName")]
  public string Name { get; set; }
}

{
  "FullName":"...",
}

public class Person_// v2
{
  public int Id { get; set; }
  public string Name { get; set; }
  public int Age { get; set; }     // New property
}

{
  "Id": 27182,
  "Name": "Sara",
  "Age": 35
}

public class Person_// v1
{
  public int Id { get; set; }
  public string Name { get; set; }
}

public class Person
{
  public int Id { get; set; }
  public string Name { get; set; }

  [JsonExtensionData]
  public IDictionary<string, JsonElement> Storage { get; set; } =
    new Dictionary<string, JsonElement>();
}

Customizing Data Conversion

Suppose that you need to interoperate with an API provider that encodes dates with the Unix timestamp format (number of seconds since 1/1/1970):

{
  "Id":27182,
  "Name":"Sara",
  "Born":464572800   // Number of seconds since 1/1/1970
}

We would like to deserialize this into a class that uses the .NET DateTime class:

public class Person
{
  public int Id { get; set; }
  public string Name { get; set; }
  public DateTime Born { get; set; }
}

We can achieve this by writing a custom data converter:

public class UnixTimestampConverter : JsonConverter<DateTime>
{
  public override DateTime Read (ref Utf8JsonReader reader, Type type,
                                 JsonSerializerOptions options)
  {
    if (reader.TryGetInt32(out int timestamp))
      return new DateTime (1970, 1, 1).AddSeconds (timestamp);

    throw new Exception ("Expected the timestamp as a number.");
  }

  public override void Write (Utf8JsonWriter writer, DateTime value,
                              JsonSerializerOptions options)
  {
    int timestamp = (int)(value - new DateTime(1970, 1, 1)).TotalSeconds;
    writer.WriteNumberValue(timestamp);
  }
}

Then we can either apply the [JsonConverter] to the properties that we want to convert:

[JsonConverter(typeof(UnixTimestampConverter))]
public DateTime Born { get; set; }

or, if the API is consistent in its representation of data types, make the converter act as a default:

JsonSerializerOptions opts = new JsonSerializerOptions();
opts.Converters.Add (new UnixTimestampConverter());
var sara = JsonSerializer.Deserialize<Person> (json, opts);

The latter instructs the serializer to use UnixTimestampConverter every time it encounters a DateTime.

JSON Serialization Options

The serializer accepts an optional JsonSerializationOptions parameter, allowing additional control over the serialization and deserialization process. The following subsections present the most useful options.

{
  "Name":"Dylan",
  "LuckyNumbers": [10, 7, ],
  "Age":46,
}

  var commaTolerant = JsonSerializer.Deserialize<Person> (brokenJson,
    new JsonSerializerOptions { AllowTrailingCommas = true });

{
  "Name":"Dylan" // Comment here
  /* This is another comment */
}

{ "name":"Dylan" }

var dylan = JsonSerializer.Deserialize<Person> (json,
  new JsonSerializerOptions { PropertyNameCaseInsensitive = true });

var dylan = new Person { Name = "Dylan" };

var json = JsonSerializer.Serialize (dylan,
  new JsonSerializerOptions
  {
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
  });

{"name": "Dylan"}

var dylan2 = JsonSerializer.Deserialize<Person> (json,
  new JsonSerializerOptions
  {
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
  });

var dict = new Dictionary<string, string>
{
  { "BookName", "Nutshell" }
  { "BookVersion", "8.0" },
};

Console.WriteLine (JsonSerializer.Serialize (dict,
  new JsonSerializerOptions
  {
    WriteIndented = true,
    DictionaryKeyPolicy = JsonNamingPolicy.CamelCase
  }));

{
  "bookName": "Nutshell"
  "bookVersion": "8.0",
}

string dylan = "<b>Dylan & Friends</b>";
Console.WriteLine (JsonSerializer.Serialize (dylan));

"u003Cbu003EDylan u0026 Friendsu003C/bu003E"

Console.WriteLine (JsonSerializer.Serialize (dylan,
  new JsonSerializerOptions {
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
  }));

"<b>Dylan & Friends</b>"

var person = new Person { Name = null };

{
  "Name": null
}

Console.WriteLine (JsonSerializer.Serialize (person),
  new JsonSerializerOptions { IgnoreNullValues = true } ));

{}

Getting Started

You can make a type serializable by applying a single attribute:

[Serializable] public sealed class Person
{
  public string Name;
  public int Age;
}

The [Serializable] attribute instructs the serializer to include all fields in the type. This includes both private and public fields (but not properties). Every field must itself be serializable; otherwise, an exception is thrown. Primitive .NET types such as string and int support serialization (as do many other .NET types).

To serialize an instance of Person, you instantiate BinaryFormatter (in System​.Runtime.Serialization.Formatters.Binary) and call Serialize.

The following serializes a Person with a BinaryFormatter:

Person p = new Person() { Name = "George", Age = 25 };

IFormatter formatter = new BinaryFormatter();

using (FileStream s = File.Create ("serialized.bin"))
  formatter.Serialize (s, p);

All of the data necessary to reconstruct the Person object is written to the file serialized.bin. The Deserialize method restores the object:

using (FileStream s = File.OpenRead ("serialized.bin"))
{
  Person p2 = (Person) formatter.Deserialize (s);
  Console.WriteLine (p2.Name + " " + p2.Age);     // George 25
}

The serialized data includes full type and assembly information, so if we try to cast the result of deserialization to a matching Person type in a different assembly, an error would result. The deserializer fully restores object references to their original state upon deserialization. This includes collections, which are just treated as serializable objects like any other (all collection types in System.Collections.* are marked as serializable).

[NonSerialized]

By default, all fields are serialized. Fields that you don’t want serialized, such as those used for temporary calculations or for storing file or window handles, you must mark explicitly with the [NonSerialized] attribute:

[Serializable] public sealed class Person
{
  public string Name;
  [NonSerialized] public int Age;
}

This instructs the serializer to ignore the Age member.

[OnDeserializing]

A method marked with the [OnDeserializing] attribute fires just prior to deserialization and acts as a kind of constructor. This can be important because the binary deserializer bypasses all your normal constructors as well as field initializers.

In the following example, we define a field called Valid, which we exclude from serialization with the [NonSerialized] attribute:

public sealed class Person
{
  public string Name;
  [NonSerialized] public bool Valid = true;

  public Person() => Valid = true;
}

A deserialized Person will never be Valid—despite the constructor and field initializer both setting Valid to true. We can solve this by writing a special deserialization constructor as follows:

[OnDeserializing]
void OnDeserializing (StreamingContext context) => Valid = true;

[OnDeserialized]

A method marked with the [OnDeserialized] attribute fires just after deserialization. This can be useful for updating calculated fields, and in conjunction with [OnSerializing], which we look at next.

[OnSerializing] and [OnSerialized]

The [OnSerializing] and [OnSerialized] attributes mark methods for execution before or after serialization.

[OnSerializing] is useful for populating a field that’s used only for serialization. To illustrate, suppose that you want to make the following class serializable:

class Foo
{
  public XDocument Xml;
}

The difficulty is that XDocument (in the System.Xml.Linq namespace) is not itself serializable. We can solve this by applying the [NonSerialized] attribute to the Xml field and then defining an [OnSerializing] method that writes the content of the XDocument to a string field (that we do serialize):

[Serializable]
class Foo
{
  [NonSerialized]
  public XDocument Xml;

  string _xmlString;  // used only for serialization

  [OnSerializing]
  void OnSerializing (StreamingContext context)
    => _xmlString = Xml.ToString();
}

The final step is to reconstruct the XDocument when deserializating. We can do this by adding an [OnDeserialized] method:

  [OnDeserialized]
  void OnDeserialized (StreamingContext context)
    => Xml = XDocument.Parse (_xmlString);

[OptionalField] and Versioning

Adding or removing fields doesn’t break compatibility with already serialized data: the deserializer skips over data for which there’s no matching field. When adding a field, you can apply the following attribute to remind yourself that it might be absent from data serialized by an older version of the software:

[Serializable] public sealed class Person
{
  public string Name;
  [OptionalField (VersionAdded = 2)] public DateTime DateOfBirth;
}

This serves as documentation and has no effect on serialization semantics.

Subclassing Serializable Classes

In the preceding examples, we sealed the classes that relied on attributes for serialization. To see why, consider the following class hierarchy:

[Serializable] public class Person
{
  public string Name;
  public int Age;
}

[Serializable] public sealed class Student : Person
{
  public string Course;
}

In this example, both Person and Student are serializable, and both classes use the default runtime serialization behavior because neither class implements ISerializable.

Now imagine that the developer of Person decides for some reason to implement ISerializable and provide a deserialization constructor to control Person serialization. The new version of Person might look like this:

[Serializable] public class Person : ISerializable
{
  public string Name;
  public int Age;

  public virtual void GetObjectData (SerializationInfo si,
                                     StreamingContext sc)
  {
    si.AddValue ("Name", Name);
    si.AddValue ("Age", Age);
  }

  protected Person (SerializationInfo si, StreamingContext sc)
  {
    Name = si.GetString ("Name");
    Age = si.GetInt32 ("Age");
  }

  public Person() {}
}

Although this works for instances of Person, this change breaks serialization of Student instances. Serializing a Student instance would appear to succeed, but the Course field in the Student type isn’t saved to the stream because the implementation of ISerializable.GetObjectData on Person has no knowledge of the members of the Student-derived type. Additionally, deserialization of Student instances throws an exception because the runtime is looking (unsuccessfully) for a deserialization constructor on Student.

The solution to this problem is to implement ISerializable from the outset for serializable classes that are public and nonsealed. (With internal classes, it’s not so important because you can easily modify the subclasses later if required.)

If we started out by writing Person, as in the preceding example, Student would then be written as follows:

[Serializable]
public class Student : Person
{
  public string Course;

  public override void GetObjectData (SerializationInfo si,
                                      StreamingContext sc)
  {
    base.GetObjectData (si, sc);
    si.AddValue ("Course", Course);
  }

  protected Student (SerializationInfo si, StreamingContext sc)
    : base (si, sc)
  {
    Course = si.GetString ("Course");
  }

  public Student() {}
}