BinarySerializationFormatter Class

public sealed class BinarySerializationFormatter : IFormatter

Public NotInheritable Class BinarySerializationFormatter
	Implements IFormatter

public ref class BinarySerializationFormatter sealed : IFormatter

[<SealedAttribute>]
type BinarySerializationFormatter = 
    class
        interface IFormatter
    end

Inheritance

Object    BinarySerializationFormatter

Implements

IFormatter

BinarySerializationFormatter aims to serialize objects effectively where the serialized data is almost always more compact than the results produced by the BinaryFormatter class.

BinarySerializationFormatter natively supports all of the primitive types and a sort of other simple types, arrays, generic and non-generic collections.

Even if a type is not marked to be serializable by the SerializableAttribute, then you can use the RecursiveSerializationAsFallback option to force its serialization. Please note though that such types might not be able to be deserialized when SafeMode is enabled. Alternatively, you can implement the IBinarySerializable interface, which can be used to produce a more compact custom serialization than the one provided by implementing the ISerializable interface.

As BinarySerializationFormatter implements IFormatter it fully supports SerializationBinder and ISurrogateSelector implementations, though for security they are mainly disabled in safe mode. See security notes above for more details.

A SerializationBinder can be used to deserialize types of unmatching assembly identity and to specify custom type-name mappings in both directions. Though BinarySerializationFormatter automatically handles TypeForwardedToAttribute and TypeForwardedFromAttribute (see also the IgnoreTypeForwardedFromAttribute option), you can use also the ForwardedTypesSerializationBinder, especially for types without a defined forwarding. The WeakAssemblySerializationBinder can also be general solution if you need to ignore the assembly version or the complete assembly identity on resolving a type. If the name of the type has also been changed, then the CustomSerializationBinder can be used. See also the Remarks section of the Binder property for more details.

An ISurrogateSelector can be used to customize serialization and deserialization. It can be used for types that cannot be handled anyway for some reason. For example, if you need to deserialize types, whose field names have been renamed you can use the CustomSerializerSurrogateSelector. Or, if the produced raw data has to be compatible with the obfuscated version of a type, then it can be achieved by the NameInvariantSurrogateSelector.

There are three ways to serialize/deserialize an object. To serialize into a byte array use the Serialize method. Its result can be deserialized by the Deserialize methods. Additionally, you can use the SerializeToStream/DeserializeFromStream methods to dump/read the result to and from a Stream, and the the SerializeByWriter/DeserializeByReader methods to use specific BinaryWriter and BinaryReader instances for serialization and deserialization, respectively.

Natively supported simple types

Following types are natively supported. When these types are serialized, no type name is stored and there is no recursive traversal of the fields:

• reference
• Non-derived Object instances.
• DBNull
• Boolean
• SByte
• Byte
• Int16
• UInt16
• Int32
• UInt32
• Int64
• UInt64
• Char
• String
• Single
• Double
• Decimal
• DateTime
• TimeSpan
• DateTimeOffset
• IntPtr
• UIntPtr
• Version
• Guid
• Uri
• StringBuilder
• StringSegment
• CultureInfo
• CompareInfo
• Comparer
• CaseInsensitiveComparer
• Enum types, though their names are saved in the serialization stream so they must be specified as expected types when deserializing in safe mode.
• Type instances if they are runtime types. For natively not supported types their names are stored in the stream so in safe mode deserialization they must be specified as expected types.
• Known StringComparer implementations.
• StringSegmentComparer implementations.
• NullableT types if type parameter is any of the supported types.
• KeyValuePairTKey, TValue if Key and Value are any of the supported types.
• DictionaryEntry if Key and Value are any of the supported types.
• StrongBoxT if Value is any of the supported types.
• Default EqualityComparerT implementations.
• Default ComparerT implementations.
• Default EnumComparerTEnum implementations.
• BigInteger (in .NET Framework 4.0 and above)
• Complex (in .NET Framework 4.0 and above)
• Vector2 (in .NET Framework 4.6 and above)
• Vector3 (in .NET Framework 4.6 and above)
• Vector4 (in .NET Framework 4.6 and above)
• Quaternion (in .NET Framework 4.6 and above)
• Plane (in .NET Framework 4.6 and above)
• Matrix3x2 (in .NET Framework 4.6 and above)
• Matrix4x4 (in .NET Framework 4.6 and above)
• Rune (in .NET Core 3.0 and above)
• Index (in .NET Standard 2.1 and above)
• Range (in .NET Standard 2.1 and above)
• Half (in .NET 5.0 and above)
• DateOnly (in .NET 6.0 and above)
• TimeOnly (in .NET 6.0 and above)
• Int128 (in .NET 7.0 and above)
• UInt128 (in .NET 7.0 and above)
• Tuple types if generic arguments are any of the supported types (in .NET Framework 4.0 and above)
• ValueTuple types if generic arguments are any of the supported types (in .NET Standard 2.0 and above)
• Any object that implements the IBinarySerializable interface.

Natively supported generic collections

Following generic collections are natively supported. When their generic arguments are one of the simple types or other supported collections, then no recursive traversal of the fields occurs:

• Array of element types above or compound of other supported collections
• ListT
• CircularListT
• LinkedListT
• HashSetT
• QueueT
• StackT
• ThreadSafeHashSetT
• ArraySegmentT
• ArraySectionT
• Array2DT
• Array3DT
• SortedSetT (in .NET Framework 4.0 and above)
• ConcurrentBagT (in .NET Framework 4.0 and above)
• ConcurrentQueueT (in .NET Framework 4.0 and above)
• ConcurrentStackT (in .NET Framework 4.0 and above)
• DictionaryTKey, TValue
• SortedListTKey, TValue
• SortedDictionaryTKey, TValue
• CircularSortedListTKey, TValue
• ConcurrentDictionaryTKey, TValue (in .NET Framework 4.0 and above)
• ImmutableArrayT (in .NET Core 2.0 and above)
• ImmutableArrayTBuilder (in .NET Core 2.0 and above)
• ImmutableListT (in .NET Core 2.0 and above)
• ImmutableListTBuilder (in .NET Core 2.0 and above)
• ImmutableHashSetT (in .NET Core 2.0 and above)
• ImmutableHashSetTBuilder (in .NET Core 2.0 and above)
• ImmutableSortedSetT (in .NET Core 2.0 and above)
• ImmutableSortedSetTBuilder (in .NET Core 2.0 and above)
• ImmutableQueueT (in .NET Core 2.0 and above)
• ImmutableStackT (in .NET Core 2.0 and above)
• ImmutableDictionaryTKey, TValue (in .NET Core 2.0 and above)
• ImmutableDictionaryTKey, TValueBuilder (in .NET Core 2.0 and above)
• ImmutableSortedDictionaryTKey, TValue (in .NET Core 2.0 and above)
• ImmutableSortedDictionaryTKey, TValueBuilder (in .NET Core 2.0 and above)
• Vector64T (in .NET Core 3.0 and above)
• Vector128T (in .NET Core 3.0 and above)
• Vector256T (in .NET Core 3.0 and above)
• Vector512T (in .NET 8.0 and above)

Natively supported non-generic collections

Following non-generic collections are natively supported. When they contain only other natively supported elements, then no recursive traversal of the fields occurs:

Serialization events

BinarySerializationFormatter supports calling methods decorated by OnSerializingAttribute, OnSerializedAttribute, OnDeserializingAttribute and OnDeserializedAttribute as well as calling IDeserializationCallback.OnDeserialization method. Attributes should be used on methods that have a single StreamingContext parameter.

Example: Size comparison to BinaryFormatter

using System;
using System.Collections;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Formatters.Binary;

using KGySoft.CoreLibraries;
using KGySoft.Serialization.Binary;

public static class Example
{
    public static void Main()
    {
        IFormatter formatter;

        // feel free to change the type in NextObject<>
        var instance = ThreadSafeRandom.Instance.NextObject<Dictionary<int, List<string>>>();
        Console.WriteLine("Generated object:   " + Dump(instance));

        using (var ms = new MemoryStream())
        {
            // serializing by KGy SOFT version:
            formatter = new BinarySerializationFormatter();
            formatter.Serialize(ms, instance);

            // deserialization:
            ms.Position = 0L;
            object deserialized = formatter.Deserialize(ms);

            Console.WriteLine("Deserialized object " + Dump(deserialized));
            Console.WriteLine("Length by BinarySerializationFormatter: " + ms.Length);
        }

        using (var ms = new MemoryStream())
        {
            // serializing by System version:
            formatter = new BinaryFormatter();
            formatter.Serialize(ms, instance);
            Console.WriteLine("Length by BinaryFormatter: " + ms.Length);
        }
    }

    private static string Dump(object o)
    {
        if (o == null)
            return "<null>";

        if (o is IConvertible convertible)
            return convertible.ToString(CultureInfo.InvariantCulture);

        if (o is IEnumerable enumerable)
            return $"[{enumerable.Cast<object>().Select(Dump).Join(", ")}]";

        return $"{{{o.GetType().GetProperties(BindingFlags.Public | BindingFlags.Instance).Select(p => $"{p.Name} = {Dump(p.GetValue(o))}").Join(", ")}}}";
    }
}

// This code example produces a similar output to this one:
// Generated object:   [{Key = 1418272504, Value = [aqez]}, {Key = 552276491, Value = [addejibude, yifefa]}]
// Deserialized object [{Key = 1418272504, Value = [aqez]}, {Key = 552276491, Value = [addejibude, yifefa]}]
// Length by BinarySerializationFormatter: 50
// Length by BinaryFormatter: 2217

Example: How to implement a custom serializable type 

The following example shows how to apply validation for a serializable class that does not implement ISerializable so it will be serialized by its fields.

using System;
using System.Runtime.Serialization;

[Serializable]
public class Example1
{
    public int IntProp { get; set; }
    public string StringProp { get; set; }

    // Regular validation when constructing the class normally
    public Example1(int intValue, string stringValue)
    {
        if (intValue <= 0)
            throw new ArgumentOutOfRangeException(nameof(intValue));
        if (stringValue == null)
            throw new ArgumentNullException(nameof(stringValue));
        if (stringValue.Length == 0)
            throw new ArgumentException("Value is empty", nameof(stringValue));

        IntProp = intValue;
        StringProp = stringValue;
    }

    // The validation for deserialization. This is executed once the instance is deserialized.
    // Another way for post-validation if you implement the IDeserializationCallback interface.
    [OnDeserialized]
    private void OnDeserialized(StreamingContext context)
    {
        if (IntProp <= 0 || String.IsNullOrEmpty(StringProp))
            throw new SerializationException("Invalid serialization stream");
    }
}

The example above may not be applicable if you if you need to validate the values in advance just like in the constructor. In that case you can implement the ISerializable interface and do the validation in the special serialization constructor:

using System;
using System.Runtime.Serialization;

[Serializable]
public class Example2 : ISerializable
{
    public int IntProp { get; set; }
    public string StringProp { get; set; }

    // Regular validation when constructing the class normally
    public Example2(int intValue, string stringValue)
    {
        if (intValue <= 0)
            throw new ArgumentOutOfRangeException(nameof(intValue));
        if (stringValue == null)
            throw new ArgumentNullException(nameof(stringValue));
        if (stringValue.Length == 0)
            throw new ArgumentException("Value is empty", nameof(stringValue));

        IntProp = intValue;
        StringProp = stringValue;
    }

    // Deserialization constructor with validation
    private Example2(SerializationInfo info, StreamingContext context)
    {
        // GetValue throws SerializationException internally if the specified name is not found
        if (info.GetValue(nameof(IntProp), typeof(int)) is not int i || i <= 0)
            throw new SerializationException("IntProp is invalid");
        if (info.GetValue(nameof(StringProp), typeof(string)) is not string s || s.Length == 0)
            throw new SerializationException("StringProp is invalid");

        IntProp = i;
        StringProp = s;
    }

    // Serialization
    void ISerializable.GetObjectData(SerializationInfo info, StreamingContext context)
    {
        info.AddValue(nameof(IntProp), IntProp);
        info.AddValue(nameof(StringProp), StringProp);
    }
}

Reference