System.Runtime.Serialization.Formatters.Binary.BinaryFormatter Class

Summary

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

C# Syntax:

public sealed class BinaryFormatter : IRemotingFormatter, IFormatter

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 containing 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 containing 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 BinaryFormatter.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 BinaryFormatter.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 BinaryFormatter.DeserializeMethodResponse method in the IMethodCallMessage parameter. The first object in the graph returned by the BinaryFormatter.DeserializeMethodResponse method supports the IMethodReturnMessage interface.

System.Runtime.Serialization.Formatters.Binary Namespace

System.Runtime.Serialization.Formatters.Binary.BinaryFormatter Member List:

Public Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the BinaryFormatter class with default values.
ctor #2	Overloaded: .ctor(ISurrogateSelector selector, StreamingContext context) Initializes a new instance of the BinaryFormatter class with a given surrogate selector and streaming context.

Public Properties

AssemblyFormat	Read-write Gets or sets the format in which assembly names are serialized.
Binder	Read-write Gets or sets an object of type SerializationBinder that controls the binding of a serialized object to a type.
Context	Read-write Gets or sets the StreamingContext for this formatter.
SurrogateSelector	Read-write Gets or sets an ISurrogateSelector that controls type substitution during serialization and deserialization.
TypeFormat	Read-write Gets or sets the format in which type descriptions are laid out in the serialized stream.

Public Methods

Deserialize	Overloaded: Deserialize(Stream serializationStream) Deserializes the specified stream into an object graph.
Deserialize	Overloaded: Deserialize(Stream serializationStream, HeaderHandler handler) Deserializes the specified stream into an object graph. The provided HeaderHandler handles any headers in that stream.
DeserializeMethodResponse	Deserializes a response to a remote method call from the provided Stream.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Serialize	Overloaded: Serialize(Stream serializationStream, object graph) Serializes the object, or graph of objects with the specified top (root), to the given stream.
Serialize	Overloaded: Serialize(Stream serializationStream, object graph, Header[] headers) Serializes the object, or graph of objects with the specified top (root), to the given stream attaching the provided headers.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

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

System.Runtime.Serialization.Formatters.Binary.BinaryFormatter Member Details

Summary

Initializes a new instance of the BinaryFormatter class with default values.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public BinaryFormatter();

This constructor sets the properties of the BinaryFormatter object as follows:

Property Type	Condition
BinaryFormatter.SurrogateSelector	null .
BinaryFormatter.Context	A StreamingContext with a value indicating that serialized data can be transmitted to or received from any of the other contexts. ( StreamingContextStates.All ).

Return to top

Summary

Initializes a new instance of the BinaryFormatter class with a given surrogate selector and streaming context.

C# Syntax:

public BinaryFormatter(    ISurrogateSelector selector,    StreamingContext context );

selector

The ISurrogateSelector to use. Can be null.

context

The source and destination for the serialized data.

Initializes a new BinaryFormatter for serialization or deserialization of objects from the specified Stream.

The serialization or deserialization process uses the specified ISurrogateSelector to search for surrogates that are registered for the object types you want to deserialize. Surrogates are helpers that serialize and deserialize objects of specific classes. The default ISurrogateSelector cannot handle the serialization of objects that derive from the MarshalByRefObject for remoting purposes. In a remoting situation the specified ISurrogateSelector replaces the object derived from MarshalByRefObject with an ObjRef object that is serialized by the specified surrogate selector. Therefore, if you want to use remote objects, set the selector parameter to an instance of RemotingSurrogateSelector. If you do not need surrogates, set the selector argument to be null.

Return to top

Summary

Gets or sets the format in which assembly names are serialized.

C# Syntax:

public FormatterAssemblyStyle AssemblyFormat {get; set;}

Return to top

Summary

Gets or sets an object of type SerializationBinder that controls the binding of a serialized object to a type.

C# Syntax:

public SerializationBinder Binder {get; set;}

Implements:

IFormatter.Binder

Return to top

Summary

Gets or sets the StreamingContext for this formatter.

C# Syntax:

public StreamingContext Context {get; set;}

Implements:

IFormatter.Context

The StreamingContext provides an enumeration that describes the source and the destination for a given serialized stream, as well as a way for serialization to retain that context and an additional caller-defined context.

Return to top

Summary

Gets or sets an ISurrogateSelector that controls type substitution during serialization and deserialization.

C# Syntax:

public ISurrogateSelector SurrogateSelector {get; set;}

Implements:

IFormatter.SurrogateSelector

The surrogate selector is used by System.Runtime.Remoting to generate ObjRef instances for objects that derive from MarshalByRefObject.

Return to top

Summary

Gets or sets the format in which type descriptions are laid out in the serialized stream.

C# Syntax:

public FormatterTypeStyle TypeFormat {get; set;}

Return to top

Summary

Deserializes the specified stream into an object graph.

C# Syntax:

public object Deserialize(    Stream serializationStream );

serializationStream

The stream from which to deserialize the object graph.

Return Value:

The top (root) of the object graph.

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.
SerializationException	serializationStream supports seeking, but its length is 0.

Implements:

IFormatter.Deserialize

Note For successful deserialization, the current position in the stream must be at the beginning of the object graph.

Return to top

Summary

Deserializes the specified stream into an object graph. The provided HeaderHandler handles any headers in that stream.

C# Syntax:

public object Deserialize(    Stream serializationStream,    HeaderHandler handler );

serializationStream

The stream from which to deserialize the object graph.

handler

The HeaderHandler that handles any headers in the serializationStream. Can be null.

Return Value:

The deserialized object or the top object (root) of the object graph.

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.
SerializationException	serializationStream supports seeking, but its length is 0.

Implements:

IRemotingFormatter.Deserialize

Headers are used only for specific remoting applications.

Note In order for deserialization to succeed the current position in the stream must be at the beginning of the object graph.

Return to top

Summary

Deserializes a response to a remote method call from the provided Stream.

C# Syntax:

public object DeserializeMethodResponse(    Stream serializationStream,    HeaderHandler handler,    IMethodCallMessage methodCallMessage );

serializationStream

The stream from which to deserialize the object graph.

handler

The HeaderHandler that handles any headers in the serializationStream. Can be null.

methodCallMessage

The IMethodCallMessage containing details about where the call came from.

Return Value:

The deserialized response to the remote method call.

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.
SerializationException	serializationStream supports seeking, but its length is 0.

To save time, details about the caller object are not sent to the remote object during the method call. Instead, these details are obtained from the original method call that is passed to the current method in the methodCallMessage parameter.

Note In order for deserialization to succeed the current position in the stream must be at the beginning of the object graph.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~BinaryFormatter();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Serializes the object, or graph of objects with the specified top (root), to the given stream.

C# Syntax:

public void Serialize(    Stream serializationStream,    object graph );

serializationStream

The stream to which the graph is to be serialized.

graph

The object at the root of the graph to serialize.

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.
SerializationException	An error has occurred during serialization, such as if an object in the graph parameter is not marked as serializable.

Implements:

IFormatter.Serialize

Return to top

Summary

Serializes the object, or graph of objects with the specified top (root), to the given stream attaching the provided headers.

C# Syntax:

public void Serialize(    Stream serializationStream,    object graph,    Header[] headers );

serializationStream

The stream to which the object is to be serialized.

graph

The object at the root of the graph to serialize.

headers

Remoting headers to include in the serialization. Can be null.

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.
SerializationException	An error has occurred during serialization, such as if an object in the graph parameter is not marked as serializable.

Implements:

IRemotingFormatter.Serialize

The serialization process includes the information supplied in the headers parameter at the front of the serialized stream.

Note Headers are used only for specific remoting applications.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page