KGy SOFT

BinarySerializationOptions Enumeration

KGy SOFT Core Libraries Help
Options for serialization methods in BinarySerializer and BinarySerializationFormatter classes.

Namespace:  KGySoft.Serialization.Binary
Assembly:  KGySoft.CoreLibraries (in KGySoft.CoreLibraries.dll) Version: 6.0.0-rc.1
Syntax

[FlagsAttribute]
public enum BinarySerializationOptions
Members

  Member nameValueDescription
None0 All options are disabled.
ForceRecursiveSerializationOfSupportedTypes1

Apart from primitive types, strings and arrays forces to serialize every type recursively. If SurrogateSelector is set, then the surrogate selectors will be tried to used even for the supported types (as if TryUseSurrogateSelectorForAnyType was also enabled).

Note Note
Even if this flag is enabled, non-serializable types will not be serialized automatically. Use the RecursiveSerializationAsFallback to enable serialization of such types.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled

ForcedSerializationValueTypesAsFallback2 Obsolete.

This option makes possible to serialize ValueTypes (struct) that are not marked by SerializableAttribute.

Caution note Caution
Never use this flag on a ValueType that has reference (non-value type) fields. Deserializing such value would result an invalid object with undetermined object references. Only string and array reference fields can be serialized safely if they are decorated by MarshalAsAttribute using ByValTStr or ByValArray, respectively.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled

RecursiveSerializationAsFallback4

Makes possible to serialize any object even if object is not marked with SerializableAttribute.

This flag is considered on serialization.

Caution note Caution
Though this flag makes possible to serialize non-serializable types, deserializing such stream will not work when the SafeMode flag is enabled (unless an applicable SurrogateSelector is used).

Default state at serialization methods in BinarySerializer: Enabled

IgnoreSerializationMethods8

If a type has methods decorated with OnSerializingAttribute, OnSerializedAttribute, OnDeserializingAttribute or OnDeserializedAttribute, or the type implements IDeserializationCallback, then these methods are called during the process. By setting this flag these methods can be ignored.

This flag is considered both on serialization and deserialization.

Default state at serialization methods in BinarySerializer: Disabled

IgnoreIBinarySerializable16

This flag ignores IBinarySerializable implementations.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled

OmitAssemblyQualifiedNames32

If enabled, type references will be stored without assembly identification. This can make possible to restore a type even if the version of the assembly has been modified since last serialization while makes serialized data more compact; however, it cannot be guaranteed that the correct type will be even found on deserialization.

Caution note Caution
If there are types with the same name in the same namespace in different assemblies, then by using this flag, these types cannot be distincted.
Note Note
If you want to deserialize a type that was stored with strong assembly reference (without this flag) from a different version of an assembly, then use WeakAssemblySerializationBinder instead.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled

IgnoreObjectChanges64

This option makes possible to deserialize an object, which has been changed since last serialization. When this option is enabled, names of the base classes, and fields that have been serialized but have been since then removed, will be ignored.

Caution note Caution
When this flag is enabled, an erroneous deserialization may silently succeed. When a field has been renamed or relocated into another base class, use an ISurrogateSelector implementation to apply mappings instead.

This flag is considered on deserialization.

Default state at serialization methods in BinarySerializer: Disabled

IgnoreTypeForwardedFromAttribute128

When this flag is enabled, every type will be serialized with its actual assembly identity rather than considering the value of an existing TypeForwardedFromAttribute.

This flag is ignored if OmitAssemblyQualifiedNames is enabled.

This flag is considered on serialization.

Note Note
Enabling this flag may cause that the type will not be able to be deserialized on a different platform, or at least not without using a SerializationBinder.

Default state at serialization methods in BinarySerializer: Disabled

IgnoreISerializable256

This flag ignores ISerializable implementations forcing to serialize a default object graph (unless an applicable surrogate is defined).

This flag is considered both on serialization and deserialization.

Note Note
Usually this flag must have the same value at serialization and deserialization; otherwise, the deserialization may fail.

Default state at serialization methods in BinarySerializer: Disabled

IgnoreIObjectReference512

This flag ignores IObjectReference implementations.

Note Note
Using this flag may cause that the deserialized object or its elements will have the wrong type, or the deserialization will fail.

This flag is considered on deserialization.

Default state at serialization methods in BinarySerializer: Disabled

CompactSerializationOfStructures1024

If a ValueType (struct) contains no references, then by enabling this option the instance will be serialized in a compact way form if possible.

This flag is considered on serialization.

Note Note
Note: This option has higher priority than RecursiveSerializationAsFallback flag, except for natively supported structures. This option affects only instances that have no references at all.

Default state at serialization methods in BinarySerializer: Enabled

TryUseSurrogateSelectorForAnyType2048

If this flag is enabled while SurrogateSelector is set, then the selector is tried to be used even for natively supported types.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled

SafeMode4096

If this flag is enabled, then it is ensured that no assembly loading is allowed during deserialization, unless a Binder is specified that can load assemblies. All of the assemblies that are referred by the serialization stream must be preloaded before starting the deserialization.

Additionally, it ensures that during the deserialization collections are allocated with limited capacity to prevent possible attacks that can cause OutOfMemoryException. Deserializing an invalid stream still may cause to throw a SerializationException.

It also disallows deserializing non-serializable types, unless the SurrogateSelector property is set that allows deserializing a type explicitly. Please note that deserializing non-serializable types is allowed without this flag by default (see also the RecursiveSerializationAsFallback flag).

In .NET Core / .NET 5.0 and above, deserializing non-natively supported system types in safe mode may require to preload some core legacy assemblies such as mscorlib.dll, System.dll, System.Core.dll, etc., which contain only type forwards on recent .NET platforms. You can avoid this if the stream was serialized with the IgnoreTypeForwardedFromAttribute option (so every non-natively supported type was serialized with its actual identity), or with the OmitAssemblyQualifiedNames option (so types can be located in any already loaded assembly).

Note Note
In safe mode no version mismatch is tolerated even for system assemblies. If you want to deserialize a stream in safe mode that contains different assembly identities from the loaded ones, then use WeakAssemblySerializationBinder, and set its SafeMode property to .
Security note Security Note
Please note that even enabling this flag may not prevent every possible attacks, especially when targeting the .NET Framework.
See the security notes at the Remarks section of the BinarySerializationFormatter class for more details.

This flag is considered on deserialization.

Default state at serialization methods in BinarySerializer: Disabled

See Also

Reference