Caveman's Blog

My commitment to learning.

Version Tolerant Serialization

leave a comment »

Recently we had a situation where the datatypes of a few properties in a extended commerce server 2007 class had to be changed. This class is serializable and a change to the datatypes would break compatibility with the data from the past. The data from the past has to be supported by the application for a period of about 3 months.

The challenge on hand is to make the changes to the class in such a way that changes would not make the application to break compatibility with the data form the past.

One solution that we have implemented was to change the type Property, add a new version of the private data member and retain the older data member. This gives us the flexibility of casting the old data into the new type and returning it via the property.


Version Tolerant Serialization (VTS) is a set of features introduced in .NET Framework 2.0 that makes it easier, over time, to modify serializable types. Specifically, the VTS features are enabled for classes to which the SerializableAttribute attribute has been applied. VTS makes it possible to add new fields to those classes without breaking compatibility with other versions of the type. [1]

The VTS features are enabled when using the BinaryFormatter. Additionally, all features except extraneous data tolerance are also enabled when using the SoapFormatter. For more information about using these classes for serialization, see Binary Serialization. [1]

The set of features includes the following [1]:

Tolerance of Extraneous or Unexpected Data

In the past, during deserialization, any extraneous or unexpected data caused exceptions to be thrown. With VTS, in the same situation, any extraneous or unexpected data is ignored instead of causing exceptions to be thrown. This enables applications that use newer versions of a type (that is, a version that includes more fields) to send information to applications that expect older versions of the same type.

Tolerance of Missing Data

Fields can be marked as optional by applying the OptionalFieldAttribute attribute to them. During deserialization, if the optional data is missing, the serialization engine ignores the absence and does not throw an exception. Thus, applications that expect older versions of a type can send data to applications that expect newer versions of the same type.

Serialization Callbacks

Serialization callbacks are a mechanism that provides hooks into the serialization/deserialization process at four points.

Using Callbacks

To use callbacks, apply the appropriate attribute to a method that accepts a StreamingContext parameter. Only one method per class can be marked with each of these attributes.

The VersionAdded Property

The OptionalFieldAttribute has the VersionAdded property. In version 2.0 of the .NET Framework, this is not used. However, it is important to set this property correctly to ensure that the type will be compatible with future serialization engines.

The property indicates which version of a type a given field has been added. It should be incremented by exactly one (starting at 2) every time the type is modified.

Best Practices

1. To ensure proper versioning behavior, follow these rules when modifying a type from version to version:

2. Never remove a serialized field.

3. Never apply the NonSerializedAttribute attribute to a field if the attribute was not applied to the field in the previous version.

4. Never change the name or the type of a serialized field.

5. When adding a new serialized field, apply the OptionalFieldAttribute attribute.

6. When removing a NonSerializedAttribute attribute from a field (that was not serializable in a previous version), apply the OptionalFieldAttribute attribute.

7. For all optional fields, set meaningful defaults using the serialization callbacks unless 0 or null as defaults are acceptable.

To ensure that a type will be compatible with future serialization engines, follow these guidelines:

1. Always set the VersionAdded property on the OptionalFieldAttribute attribute correctly.

2. Avoid branched versioning.

1. MSDN Online

kick it on


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: