Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

BinaryFormatter Class

Serializes and deserializes an object, or an entire graph of connected objects, in binary format.

Namespace: System.Runtime.Serialization.Formatters.Binary
Assembly: mscorlib (in mscorlib.dll)

[ComVisibleAttribute(true)] 
public sealed class BinaryFormatter : IRemotingFormatter, IFormatter
/** @attribute ComVisibleAttribute(true) */ 
public final class BinaryFormatter implements IRemotingFormatter, IFormatter
ComVisibleAttribute(true) 
public final class BinaryFormatter implements IRemotingFormatter, IFormatter
Not applicable.

The SoapFormatter and BinaryFormatter classes implement the IRemotingFormatter interface to support remote procedure calls (RPCs), and the IFormatter interface (inherited by the IRemotingFormatter) to support serialization of a graph of objects. The SoapFormatter class also supports RPCs with ISoapMessage objects, without using the IRemotingFormatter functionality.

During RPCs, the IRemotingFormatter interface allows the specification of two separate object graphs: the graph of objects to serialize, and an additional graph that contains an array of header objects that convey information about the remote function call (for example, transaction ID or a method signature).

RPCs that use the BinaryFormatter separate into two distinct parts: method calls, which are sent to the server with the remote object that contains the method called, and method responses, which are sent from the server to the client with the status and response information from the called method.

During serialization of a method call the first object of the object graph must support the IMethodCallMessage interface. To deserialize a method call, use the Deserialize method with the HeaderHandler parameter. The remoting infrastructure uses the HeaderHandler delegate to produce an object that supports the ISerializable interface. When the BinaryFormatter invokes the HeaderHandler delegate, it returns the URI of the remote object with the method that is being called. The first object in the graph returned supports the IMethodCallMessage interface.

The serialization procedure for a method response is identical to that of a method call, except the first object of the object graph must support the IMethodReturnMessage interface. To deserialize a method response, use the DeserializeMethodResponse method. To save time, details about the caller object are not sent to the remote object during the method call. These details are instead obtained from the original method call, which is passed to the DeserializeMethodResponse method in the IMethodCallMessage parameter. The first object in the graph returned by the DeserializeMethodResponse method supports the IMethodReturnMessage interface.

Unpaired Surrogates

Any unpaired surrogate characters are lost in binary serialization. For example, the following string contains a high surrogate Unicode character (\ud800) in between the two Test words:

Test\ud800Test

Before serialization, the byte array of the string is as follows:

Byte Array Value

Character

84

T

101

e

115

s

116

t

55296

\ud800

84

T

101

e

115

s

116

t

After deserialization, the high surrogate Unicode character is lost:

Byte Array Value

Character

84

T

101

e

115

s

116

t

84

T

101

e

115

s

116

t

using System;
using System.IO;
using System.Collections;
using System.Runtime.Serialization.Formatters.Binary;
using System.Runtime.Serialization;

public class App 
{
    [STAThread]
    static void Main() 
    {
        Serialize();
        Deserialize();
    }

    static void Serialize() 
    {
        // Create a hashtable of values that will eventually be serialized.
        Hashtable addresses = new Hashtable();
        addresses.Add("Jeff", "123 Main Street, Redmond, WA 98052");
        addresses.Add("Fred", "987 Pine Road, Phila., PA 19116");
        addresses.Add("Mary", "PO Box 112233, Palo Alto, CA 94301");

        // To serialize the hashtable and its key/value pairs,  
        // you must first open a stream for writing. 
        // In this case, use a file stream.
        FileStream fs = new FileStream("DataFile.dat", FileMode.Create);

        // Construct a BinaryFormatter and use it to serialize the data to the stream.
        BinaryFormatter formatter = new BinaryFormatter();
        try 
        {
            formatter.Serialize(fs, addresses);
        }
        catch (SerializationException e) 
        {
            Console.WriteLine("Failed to serialize. Reason: " + e.Message);
            throw;
        }
        finally 
        {
            fs.Close();
        }
    }

   
    static void Deserialize() 
    {
        // Declare the hashtable reference.
        Hashtable addresses  = null;

        // Open the file containing the data that you want to deserialize.
        FileStream fs = new FileStream("DataFile.dat", FileMode.Open);
        try 
        {
            BinaryFormatter formatter = new BinaryFormatter();

            // Deserialize the hashtable from the file and 
            // assign the reference to the local variable.
            addresses = (Hashtable) formatter.Deserialize(fs);
        }
        catch (SerializationException e) 
        {
            Console.WriteLine("Failed to deserialize. Reason: " + e.Message);
            throw;
        }
        finally 
        {
            fs.Close();
        }

        // To prove that the table deserialized correctly, 
        // display the key/value pairs.
        foreach (DictionaryEntry de in addresses) 
        {
            Console.WriteLine("{0} lives at {1}.", de.Key, de.Value);
        }
    }
}

import System.*;
import System.IO.*;
import System.Collections.*;
import System.Runtime.Serialization.Formatters.Binary.*;
import System.Runtime.Serialization.*;

public class App
{
    /** @attribute STAThread()
     */
    public static void main(String[] args) throws SerializationException
    {
        Serialize();
        Deserialize();
    } //main

    static void Serialize() throws SerializationException
    {
        // Create a hashtable of values that will eventually be serialized.
        Hashtable addresses = new Hashtable();

        addresses.Add("Jeff", "123 Main Street, Redmond, WA 98052");
        addresses.Add("Fred", "987 Pine Road, Phila., PA 19116");
        addresses.Add("Mary", "PO Box 112233, Palo Alto, CA 94301");

        // To serialize the hashtable and its key/value pairs,  
        // you must first open a stream for writing. 
        // In this case, use a file stream.
        FileStream fs = new FileStream("DataFile.dat", FileMode.Create);

        // Construct a BinaryFormatter and use it to serialize the data to the 
        // stream.
        BinaryFormatter formatter = new BinaryFormatter();

        try {
            formatter.Serialize(fs, addresses);
        }
        catch (SerializationException e) {
            Console.WriteLine("Failed to serialize. Reason: " 
                + e.get_Message());
            throw e;
        }
        finally {
            fs.Close();
        }
    } //Serialize

    static void Deserialize() throws SerializationException
    {
        // Declare the hashtable reference.
        Hashtable addresses = null;

        // Open the file containing the data that you want to deserialize.
        FileStream fs = new FileStream("DataFile.dat", FileMode.Open);

        try {
            BinaryFormatter formatter = new BinaryFormatter();

            // Deserialize the hashtable from the file and 
            // assign the reference to the local variable.
            addresses = (Hashtable)(formatter.Deserialize(fs));
        }
        catch (SerializationException e) {
            Console.WriteLine("Failed to deserialize. Reason: " 
                + e.get_Message());
            throw e;
        }
        finally {
            fs.Close();
        }

        // To prove that the table deserialized correctly, 
        // display the key/value pairs.
        IEnumerator objEnum = addresses.GetEnumerator();
        while (objEnum.MoveNext()) {
            DictionaryEntry de = (DictionaryEntry)objEnum.get_Current();        
            Console.WriteLine("{0} lives at {1}.", de.get_Key(), 
                de.get_Value());
        }
    } //Deserialize
} //App

System.Object
  System.Runtime.Serialization.Formatters.Binary.BinaryFormatter

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows Millennium Edition, 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.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft