BinaryFormatter Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Caution
BinaryFormatter serialization is obsolete and should not be used. See https://aka.ms/binaryformatter for more information.
Serializes and deserializes an object, or an entire graph of connected objects, in binary format.
public ref class BinaryFormatter sealed : System::Runtime::Serialization::IFormatter
public ref class BinaryFormatter sealed : System::Runtime::Remoting::Messaging::IRemotingFormatter
public sealed class BinaryFormatter : System.Runtime.Serialization.IFormatter
[System.Obsolete("BinaryFormatter serialization is obsolete and should not be used. See https://aka.ms/binaryformatter for more information.", DiagnosticId="SYSLIB0011", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
public sealed class BinaryFormatter : System.Runtime.Serialization.IFormatter
public sealed class BinaryFormatter : System.Runtime.Remoting.Messaging.IRemotingFormatter
[System.Runtime.InteropServices.ComVisible(true)]
public sealed class BinaryFormatter : System.Runtime.Remoting.Messaging.IRemotingFormatter
type BinaryFormatter = class
interface IFormatter
[<System.Obsolete("BinaryFormatter serialization is obsolete and should not be used. See https://aka.ms/binaryformatter for more information.", DiagnosticId="SYSLIB0011", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>]
type BinaryFormatter = class
interface IFormatter
type BinaryFormatter = class
interface IRemotingFormatter
interface IFormatter
[<System.Runtime.InteropServices.ComVisible(true)>]
type BinaryFormatter = class
interface IRemotingFormatter
interface IFormatter
Public NotInheritable Class BinaryFormatter
Implements IFormatter
Public NotInheritable Class BinaryFormatter
Implements IRemotingFormatter
- Inheritance
-
BinaryFormatter
- Attributes
- Implements
Examples
using namespace System;
using namespace System::IO;
using namespace System::Collections;
using namespace System::Runtime::Serialization::Formatters::Binary;
using namespace System::Runtime::Serialization;
ref class App
{
public:
static void Serialize()
{
// Create a hashtable of values that will eventually be serialized.
Hashtable^ addresses = gcnew 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 keys/values),
// you must first open a stream for writing.
// In this case we will use a file stream.
FileStream^ fs = gcnew FileStream( "DataFile.dat",FileMode::Create );
// Construct a BinaryFormatter and use it to serialize the data to the stream.
BinaryFormatter^ formatter = gcnew BinaryFormatter;
try
{
formatter->Serialize( fs, addresses );
}
catch ( SerializationException^ e )
{
Console::WriteLine( "Failed to serialize. Reason: {0}", e->Message );
throw;
}
finally
{
fs->Close();
}
}
static void Deserialize()
{
// Declare the hashtable reference.
Hashtable^ addresses = nullptr;
// Open the file containing the data that we want to deserialize.
FileStream^ fs = gcnew FileStream( "DataFile.dat",FileMode::Open );
try
{
BinaryFormatter^ formatter = gcnew BinaryFormatter;
// Deserialize the hashtable from the file and
// assign the reference to our local variable.
addresses = dynamic_cast<Hashtable^>(formatter->Deserialize( fs ));
}
catch ( SerializationException^ e )
{
Console::WriteLine( "Failed to deserialize. Reason: {0}", e->Message );
throw;
}
finally
{
fs->Close();
}
// To prove that the table deserialized correctly, display the keys/values.
IEnumerator^ myEnum = addresses->GetEnumerator();
while ( myEnum->MoveNext() )
{
DictionaryEntry ^ de = safe_cast<DictionaryEntry ^>(myEnum->Current);
Console::WriteLine( " {0} lives at {1}.", de->Key, de->Value );
}
}
};
[STAThread]
int main()
{
App::Serialize();
App::Deserialize();
return 0;
}
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);
}
}
}
Imports System.IO
Imports System.Collections
Imports System.Runtime.Serialization.Formatters.Binary
Imports System.Runtime.Serialization
Module App
Sub Main()
Serialize()
Deserialize()
End Sub
Sub Serialize()
' Create a hashtable of values that will eventually be serialized.
Dim addresses As 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.
Dim fs As New FileStream("DataFile.dat", FileMode.Create)
' Construct a BinaryFormatter and use it to serialize the data to the stream.
Dim formatter As New BinaryFormatter
Try
formatter.Serialize(fs, addresses)
Catch e As SerializationException
Console.WriteLine("Failed to serialize. Reason: " & e.Message)
Throw
Finally
fs.Close()
End Try
End Sub
Sub Deserialize()
' Declare the hashtable reference.
Dim addresses As Hashtable = Nothing
' Open the file containing the data that you want to deserialize.
Dim fs As New FileStream("DataFile.dat", FileMode.Open)
Try
Dim formatter As New BinaryFormatter
' Deserialize the hashtable from the file and
' assign the reference to the local variable.
addresses = DirectCast(formatter.Deserialize(fs), Hashtable)
Catch e As SerializationException
Console.WriteLine("Failed to deserialize. Reason: " & e.Message)
Throw
Finally
fs.Close()
End Try
' To prove that the table deserialized correctly,
' display the key/value pairs.
Dim de As DictionaryEntry
For Each de In addresses
Console.WriteLine("{0} lives at {1}.", de.Key, de.Value)
Next
End Sub
End Module
Remarks
Warning
BinaryFormatter
is insecure and can't be made secure. For more information, see the BinaryFormatter security guide.
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.
Important
Using binary serialization to deserialize untrusted data can lead to security risks. For more information, see Validate All Inputs and the BinaryFormatter security guide.
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 |
Constructors
BinaryFormatter() |
Initializes a new instance of the BinaryFormatter class with default values. |
BinaryFormatter(ISurrogateSelector, StreamingContext) |
Initializes a new instance of the BinaryFormatter class with a given surrogate selector and streaming context. |
Properties
AssemblyFormat |
Gets or sets the behavior of the deserializer with regards to finding and loading assemblies. |
Binder |
(Insecure) Gets or sets an object of type SerializationBinder that controls the binding of a serialized object to a type. |
Context |
Gets or sets the StreamingContext for this formatter. |
FilterLevel |
Gets or sets the TypeFilterLevel of automatic deserialization the BinaryFormatter performs. |
SurrogateSelector |
Gets or sets a ISurrogateSelector that controls type substitution during serialization and deserialization. |
TypeFormat |
Gets or sets the format in which type descriptions are laid out in the serialized stream. |
Methods
Deserialize(Stream) |
Obsolete.
Deserializes the specified stream into an object graph. |
Deserialize(Stream, HeaderHandler) |
Deserializes the specified stream into an object graph. The provided HeaderHandler handles any headers in that stream. |
DeserializeMethodResponse(Stream, HeaderHandler, IMethodCallMessage) |
Deserializes a response to a remote method call from the provided Stream. |
Equals(Object) |
Determines whether the specified object is equal to the current object. (Inherited from Object) |
GetHashCode() |
Serves as the default hash function. (Inherited from Object) |
GetType() |
Gets the Type of the current instance. (Inherited from Object) |
MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
Serialize(Stream, Object) |
Obsolete.
Serializes the object, or graph of objects with the specified top (root), to the given stream. |
Serialize(Stream, Object, Header[]) |
Serializes the object, or graph of objects with the specified top (root), to the given stream attaching the provided headers. |
ToString() |
Returns a string that represents the current object. (Inherited from Object) |
UnsafeDeserialize(Stream, HeaderHandler) |
Deserializes the specified stream into an object graph. The provided HeaderHandler handles any headers in that stream. |
UnsafeDeserializeMethodResponse(Stream, HeaderHandler, IMethodCallMessage) |
Deserializes a response to a remote method call from the provided Stream. |