Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
181 lines (139 sloc) 13.7 KB
title dev_langs helpviewer_keywords ms.assetid
Custom serialization
binary serialization, custom serialization
custom serialization
binary serialization, controlling
OptionalFieldAttribute class, custom serialization
ISerializable interface, custom serialization
OnDeserializingAttribute class, custom serialization
OnSerializedAttribute class, custom serialization
serialization, custom serialization
serialization, controlling
OnDeserializedAttribute class, custom serialization
OnSerializingAttribute class, custom serialization

Custom serialization

Custom serialization is the process of controlling the serialization and deserialization of a type. By controlling serialization, it's possible to ensure serialization compatibility, which is the ability to serialize and deserialize between versions of a type without breaking the core functionality of the type. For example, in the first version of a type, there may be only two fields. In the next version of a type, several more fields are added. Yet the second version of an application must be able to serialize and deserialize both types. The following sections describe how to control serialization.

[!INCLUDE binary-serialization-warning]

[!IMPORTANT] In versions previous to .NET Framework 4.0, serialization of custom user data in a partially trusted assembly was accomplished using the GetObjectData. Starting with version 4.0, that method is marked with the xref:System.Security.SecurityCriticalAttribute attribute which prevents execution in partially trusted assemblies. To work around this condition, implement the xref:System.Runtime.Serialization.ISafeSerializationData interface.

Running custom methods during and after serialization

The best practice and easiest way (introduced in version 2.0 of the .NET Framework) is to apply the following attributes to methods that are used to correct data during and after serialization:

  • xref:System.Runtime.Serialization.OnDeserializedAttribute

  • xref:System.Runtime.Serialization.OnDeserializingAttribute

  • xref:System.Runtime.Serialization.OnSerializedAttribute

  • xref:System.Runtime.Serialization.OnSerializingAttribute

These attributes allow the type to participate in any one of, or all four of the phases, of the serialization and deserialization processes. The attributes specify the methods of the type that should be invoked during each phase. The methods do not access the serialization stream but instead allow you to alter the object before and after serialization, or before and after deserialization. The attributes can be applied at all levels of the type inheritance hierarchy, and each method is called in the hierarchy from the base to the most derived. This mechanism avoids the complexity and any resulting issues of implementing the xref:System.Runtime.Serialization.ISerializable interface by giving the responsibility for serialization and deserialization to the most derived implementation. Additionally, this mechanism allows the formatters to ignore the population of fields and retrieval from the serialization stream. For details and examples of controlling serialization and deserialization, click any of the previous links.

In addition, when adding a new field to an existing serializable type, apply the xref:System.Runtime.Serialization.OptionalFieldAttribute attribute to the field. The xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter and the xref:System.Runtime.Serialization.Formatters.Soap.SoapFormatter ignores the absence of the field when a stream that is missing the new field is processed.

Implementing the ISerializable interface

The other way to control serialization is achieved by implementing the xref:System.Runtime.Serialization.ISerializable interface on an object. Note, however, that the method in the previous section supersedes this method to control serialization.

In addition, you should not use default serialization on a class that is marked with the Serializable attribute and has declarative or imperative security at the class level or on its constructors. Instead, these classes should always implement the xref:System.Runtime.Serialization.ISerializable interface.

Implementing xref:System.Runtime.Serialization.ISerializable involves implementing the GetObjectData method and a special constructor that is used when the object is deserialized. The following sample code shows how to implement xref:System.Runtime.Serialization.ISerializable on the MyObject class from a previous section.

public class MyObject : ISerializable
    public int n1;
    public int n2;
    public String str;

    public MyObject()

    protected MyObject(SerializationInfo info, StreamingContext context)
      n1 = info.GetInt32("i");
      n2 = info.GetInt32("j");
      str = info.GetString("k");

    [SecurityPermissionAttribute(SecurityAction.Demand, SerializationFormatter = true)]
    public virtual void GetObjectData(SerializationInfo info, StreamingContext context)
        info.AddValue("i", n1);
        info.AddValue("j", n2);
        info.AddValue("k", str);
<Serializable()>  _
Public Class MyObject
    Implements ISerializable
    Public n1 As Integer
    Public n2 As Integer
    Public str As String

    Public Sub New()
    End Sub

    Protected Sub New(ByVal info As SerializationInfo, ByVal context As StreamingContext)
        n1 = info.GetInt32("i")
        n2 = info.GetInt32("j")
        str = info.GetString("k")
    End Sub 'New

    <SecurityPermissionAttribute(SecurityAction.Demand, SerializationFormatter := True)> _
    Public Overridable Sub GetObjectData(ByVal info As SerializationInfo, ByVal context As StreamingContext)
        info.AddValue("i", n1)
        info.AddValue("j", n2)
        info.AddValue("k", str)
    End Sub
End Class

When GetObjectData is called during serialization, you are responsible for populating the xref:System.Runtime.Serialization.SerializationInfo provided with the method call. Add the variables to be serialized as name and value pairs. Any text can be used as the name. You have the freedom to decide which member variables are added to the xref:System.Runtime.Serialization.SerializationInfo, provided that sufficient data is serialized to restore the object during deserialization. Derived classes should call the GetObjectData method on the base object if the latter implements xref:System.Runtime.Serialization.ISerializable.

Note that serialization can allow other code to see or modify object instance data that is otherwise inaccessible. Therefore, code that performs serialization requires the SecurityPermission with the xref:System.Security.Permissions.SecurityPermissionAttribute.SerializationFormatter flag specified. Under default policy, this permission is not given to Internet-downloaded or intranet code; only code on the local computer is granted this permission. The GetObjectData method must be explicitly protected either by demanding the SecurityPermission with the xref:System.Security.Permissions.SecurityPermissionAttribute.SerializationFormatter flag specified or by demanding other permissions that specifically help protect private data.

If a private field stores sensitive information, you should demand the appropriate permissions on GetObjectData to protect the data. Remember that code that has been granted SecurityPermission with the SerializationFormatter flag specified can view and modify the data stored in private fields. A malicious caller granted this SecurityPermission can view data such as hidden directory locations or granted permissions and use the data to exploit a security vulnerability on the computer. For a complete list of the security permission flags you can specify, see the SecurityPermissionFlag Enumeration.

It's important to stress that when xref:System.Runtime.Serialization.ISerializable is added to a class you must implement both GetObjectData and the special constructor. The compiler warns you if GetObjectData is missing. However, because it is impossible to enforce the implementation of a constructor, no warning is provided if the constructor is absent, and an exception is thrown when an attempt is made to deserialize a class without the constructor.

The current design was favored above a xref:System.Runtime.Serialization.ISerializationSurrogate.SetObjectData%2A method to get around potential security and versioning problems. For example, a SetObjectData method must be public if it is defined as part of an interface; thus users must write code to defend against having the SetObjectData method called multiple times. Otherwise, a malicious application that calls the SetObjectData method on an object in the process of executing an operation can cause potential problems.

During deserialization, xref:System.Runtime.Serialization.SerializationInfo is passed to the class using the constructor provided for this purpose. Any visibility constraints placed on the constructor are ignored when the object is deserialized; so you can mark the class as public, protected, internal, or private. However, it is a best practice to make the constructor protected unless the class is sealed, in which case the constructor should be marked private. The constructor should also perform thorough input validation. To avoid misuse by malicious code, the constructor should enforce the same security checks and permissions required to obtain an instance of the class using any other constructor. If you do not follow this recommendation, malicious code can preserialize an object, obtain control with the SecurityPermission with the xref:System.Security.Permissions.SecurityPermissionAttribute.SerializationFormatter flag specified and deserialize the object on a client computer bypassing any security that would have been applied during standard instance construction using a public constructor.

To restore the state of the object, simply retrieve the values of the variables from xref:System.Runtime.Serialization.SerializationInfo using the names used during serialization. If the base class implements xref:System.Runtime.Serialization.ISerializable, the base constructor should be called to allow the base object to restore its variables.

When you derive a new class from one that implements xref:System.Runtime.Serialization.ISerializable, the derived class must implement both the constructor as well as the GetObjectData method if it has variables that need to be serialized. The following code example shows how this is done using the MyObject class shown previously.

public class ObjectTwo : MyObject
    public int num;

    public ObjectTwo()
      : base()

    protected ObjectTwo(SerializationInfo si, StreamingContext context)
      : base(si, context)
        num = si.GetInt32("num");

    [SecurityPermissionAttribute(SecurityAction.Demand, SerializationFormatter = true)]
    public override void GetObjectData(SerializationInfo si, StreamingContext context)
        si.AddValue("num", num);
<Serializable()>  _
Public Class ObjectTwo
    Inherits MyObject
    Public num As Integer

    Public Sub New()

    End Sub

    Protected Sub New(ByVal si As SerializationInfo, _
    ByVal context As StreamingContext)
        MyBase.New(si, context)
        num = si.GetInt32("num")
    End Sub

    <SecurityPermissionAttribute(SecurityAction.Demand, SerializationFormatter := True)> _
    Public Overrides Sub GetObjectData(ByVal si As SerializationInfo, ByVal context As StreamingContext)
        MyBase.GetObjectData(si, context)
        si.AddValue("num", num)
    End Sub
End Class

Don't forget to call the base class in the deserialization constructor. If this isn't done, the constructor on the base class is never called, and the object is not fully constructed after deserialization.

Objects are reconstructed from the inside out; and calling methods during deserialization can have undesirable side effects, because the methods called might refer to object references that have not been deserialized by the time the call is made. If the class being deserialized implements the xref:System.Runtime.Serialization.IDeserializationCallback, the xref:System.Runtime.Serialization.IDeserializationCallback.OnDeserialization* method is automatically called when the entire object graph has been deserialized. At this point, all the child objects referenced have been fully restored. A hash table is a typical example of a class that is difficult to deserialize without using the event listener. It is easy to retrieve the key and value pairs during deserialization, but adding these objects back to the hash table can cause problems, because there is no guarantee that classes that derived from the hash table have been deserialized. Calling methods on a hash table at this stage is therefore not advisable.

See also

You can’t perform that action at this time.