KGy SOFT

ForwardedTypesSerializationBinder Class

KGy SOFT Core Libraries Help
Provides a SerializationBinder that makes possible to serialize and deserialize types with custom assembly identity.
See the Remarks section for details and some examples.
Inheritance Hierarchy

SystemObject
  System.Runtime.SerializationSerializationBinder
    KGySoft.Serialization.BinaryForwardedTypesSerializationBinder

Namespace:  KGySoft.Serialization.Binary
Assembly:  KGySoft.CoreLibraries (in KGySoft.CoreLibraries.dll) Version: 5.0.0
Syntax

public sealed class ForwardedTypesSerializationBinder : SerializationBinder, 
	ISerializationBinder

The ForwardedTypesSerializationBinder type exposes the following members.

Constructors

  NameDescription
Public methodForwardedTypesSerializationBinder
Initializes a new instance of the ForwardedTypesSerializationBinder class
Top
Properties

  NameDescription
Public propertyWriteLegacyIdentity
Gets or sets whether a legacy assembly identity is tried to be written on serializing.
See the Remarks section for details.
Top
Methods

  NameDescription
Public methodAddType
Adds the type to this binder. If no assemblyIdentities are defined, then any Type with the same full name will be resolved to type; otherwise, only the ones, whose identities match.
Public methodAddTypes
Adds the types to this binder without any specific assembly identity. Each Type that have the same full name as one of the given types, will be able to be resolved from any assembly.
Public methodBindToName
When WriteLegacyIdentity is , then tries to return a legacy assembly identity for the specified serializedType.
(Overrides SerializationBinderBindToName(Type, String, String).)
Public methodBindToType
Retrieves a type by its assemblyName and typeName.
(Overrides SerializationBinderBindToType(String, String).)
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Top
Extension Methods

  NameDescription
Public Extension MethodConvert(Type, CultureInfo)Overloaded.
Converts an Object specified in the obj parameter to the desired targetType.
See the Examples section of the generic ConvertTTarget(Object, CultureInfo) overload for an example.
(Defined by ObjectExtensions.)
Public Extension MethodCode exampleConvertTTarget(CultureInfo)Overloaded.
Converts an Object specified in the obj parameter to the desired TTarget.
(Defined by ObjectExtensions.)
Public Extension MethodIn (Defined by ObjectExtensions.)
Public Extension MethodTryConvert(Type, Object)Overloaded.
Tries to convert an Object specified in the obj parameter to the desired targetType.
(Defined by ObjectExtensions.)
Public Extension MethodTryConvert(Type, CultureInfo, Object)Overloaded.
Tries to convert an Object specified in the obj parameter to the desired targetType.
(Defined by ObjectExtensions.)
Public Extension MethodTryConvertTTarget(TTarget)Overloaded.
Tries to convert an Object specified in the obj parameter to the desired TTarget.
See the Examples section of the ConvertTTarget(Object, CultureInfo) method for a related example.
(Defined by ObjectExtensions.)
Public Extension MethodTryConvertTTarget(CultureInfo, TTarget)Overloaded.
Tries to convert an Object specified in the obj parameter to the desired TTarget.
See the Examples section of the ConvertTTarget(Object, CultureInfo) method for a related example.
(Defined by ObjectExtensions.)
Top
Remarks

By default, the ForwardedTypesSerializationBinder does nothing. Resolving types from legacy assemblies works automatically if at least a chunk version of the assembly exists on the current platform containing nothing but a bunch of TypeForwardedToAttribute attributes (this is the case for the original .NET Framework assemblies on .NET Core and .NET Standard).

To resolve types that are not forwarded by the TypeForwardedToAttribute from an existing assembly with the given identity use this binder for deserialization. Add the types to be handled by the AddType or AddTypes methods.

If WriteLegacyIdentity is set to , then mapping works also on serialization. For types without an explicitly set mapping the value of the TypeForwardedFromAttribute attribute will be written if it is defined.

Note Note
By default, both BinaryFormatter and BinarySerializationFormatter dumps legacy identities on serialization for types decorated by the TypeForwardedFromAttribute. If you use this binder on serialization without adding any type just after setting the WriteLegacyIdentity to , then the only difference will be that even the mscorlib assembly name will be dumped to the output stream, which would be omitted otherwise.

To serialize types with arbitrary assembly identity, use this binder both for serialization and deserialization. Add the type to be handled by the AddType method and specify at least one AssemblyName for each added Type.

Examples

The following example demonstrates the usage of the ForwardedTypesSerializationBinder when types have to be deserialized from a stream, which have been originally serialized by another version of the assembly.

C#
var binder = new ForwardedTypesSerializationBinder();

// MyType will be able to be deserialized if the assembly name in the
// serialization stream matches any of the enlisted ones.
binder.AddType(typeof(MyType),
    new AssemblyName("MyOldAssembly, Version=1.0.0.0"),
    new AssemblyName("MyOldAssembly, Version=1.2.0.0"),
    new AssemblyName("MyNewAssembly, Version=1.5.0.0"),
    new AssemblyName("MyNewAssembly, Version=2.0.0.0"));

// MyOtherType will be able to be deserialized if it was serialized by any versions of MyAssembly.
binder.AddType(typeof(MyOtherType), new AssemblyName("MyAssembly"));

// Any type of any assembly will be mapped to SomeOtherType if their full names match.
binder.AddType(typeof(SomeOtherType));

// Multiple types can be enlisted without assembly identity
binder.AddTypes(typeof(MyType), typeof(MyOtherType), typeof(SomeOtherType));

IFormatter formatter = new BinarySerializationFormatter { Binder = binder }; // or BinaryFormatter
object result = formatter.Deserialize(serializationStream);

Note Note
The WeakAssemblySerializationBinder is also able to ignore assembly information but if there are two different types of the same name in the same namespace, then the behavior of WeakAssemblySerializationBinder is not deterministic.

The following example demonstrates how to control the serialized assembly name.

C#
// Setting the WriteLegacyIdentity allows to use arbitrary custom indenity on serialization.
var binder = new ForwardedTypesSerializationBinder { WriteLegacyIdentity = true };

// When serializing a MyType instance, it will be saved with the firstly specified identity
binder.AddType(typeof(MyType),
    new AssemblyName("MyOldAssembly, Version=1.0.0.0"),
    new AssemblyName("MyOldAssembly, Version=1.2.0.0"),
    new AssemblyName("MyNewAssembly, Version=1.5.0.0"),
    new AssemblyName("MyNewAssembly, Version=2.0.0.0"));

// If WriteLegacyIdentity is true, types with TypeForwardedFromAttribute will be automatically written
// with their old identity stored in the TypeForwardedFromAttribute.AssemblyFullName property.
// List<T> has a TypeForwardedFromAttribute in .NET Core and Standard so it will be serialized with
// mscorlib assembly identity in every platform:
var obj = new List<MyType> { new MyType() };

IFormatter formatter = new BinaryFormatter { Binder = binder }; // or BinarySerializationFormatter
formatter.Serialize(serializationStream, obj);

Tip Tip
If not only the assembly name but also the inner content of a type (ie. field names) changed, then you can use the CustomSerializerSurrogateSelector class.
See Also

Reference