BinarySerializationOptions Enumeration

Options for serialization methods in BinarySerializer and BinarySerializationFormatter classes.

Definition

Namespace: KGySoft.Serialization.Binary
Assembly: KGySoft.CoreLibraries (in KGySoft.CoreLibraries.dll) Version: 10.5.0
C#
[FlagsAttribute]
public enum BinarySerializationOptions

Members

None0x0000 All options are disabled.
ForceRecursiveSerializationOfSupportedTypes0x0001

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 be used even for the supported types (as if TryUseSurrogateSelectorForAnyType was also enabled).

  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

ForcedSerializationValueTypesAsFallback0x0002

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

  Caution

Using this flag allows serializing value types with reference (non-value type) fields by marshaling. Deserializing such value may fail if the SafeMode flag if enabled. To be able to serialize string and array reference fields they must be decorated by MarshalAsAttribute using ByValTStr or ByValArray, respectively.

  Note

This option is obsolete. Use the CompactSerializationOfStructures flag instead.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled


Obsolete
RecursiveSerializationAsFallback0x0004

Makes possible to serialize any non-natively supported types if they are not marked by SerializableAttribute.

This flag is considered on serialization.

  Caution

Though this flag makes possible to serialize non-serializable types, deserializing such stream will not work when the SafeMode flag is enabled (unless the AllowNonSerializableExpectedCustomTypes option is also set).

Default state at serialization methods in BinarySerializer: Disabled

IgnoreSerializationMethods0x0008

If a type has methods decorated by 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

IgnoreIBinarySerializable0x0010

This flag ignores IBinarySerializable implementations.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled

OmitAssemblyQualifiedNames0x0020

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 without specifying the expected types.

  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 distinguished. If the expected types are not specified on deserialization, then any of the types with identical full names might be picked.

This flag is considered on serialization.

Default state at serialization methods in BinarySerializer: Disabled

IgnoreObjectChanges0x0040

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

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 (but note that surrogate selectors cannot be used in safe mode).

This flag is considered on deserialization.

Default state at serialization methods in BinarySerializer: Disabled

IgnoreTypeForwardedFromAttribute0x0080

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

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

IgnoreISerializable0x0100

This flag ignores ISerializable implementations for natively not supported types, forcing to serialize a default object graph (unless an applicable surrogate selector is defined).

This flag is considered both on serialization and deserialization.

  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

IgnoreIObjectReference0x0200

This flag ignores IObjectReference implementations.

  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

CompactSerializationOfStructures0x0400

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

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

  Caution

Enabling this flag makes the serialization architecture-dependent in terms of endianness, auto-packing and native integer sizes. If you enable this flag, make sure you perform the serialization and deserialization on the same architecture, preferably in the same process (which is the generally recommended usage of binary serialization anyway).

Default state at serialization methods in BinarySerializer: Disabled

TryUseSurrogateSelectorForAnyType0x0800

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

SafeMode0x1000

When this flag is enabled, the natively not supported types, whose assembly qualified names are stored in the serialization stream must be explicitly declared as expected types in the deserialization methods, including enums.

Additionally, safe mode ensures that during the deserialization natively supported 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 the natively not supported non-serializable types, though this can be relaxed by enabling the AllowNonSerializableExpectedCustomTypes flag.

  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 ForwardedTypesSerializationBinder, and set its SafeMode property to .

  Security Note

In safe mode it is not allowed to set the SurrogateSelector or Binder properties (except for using the ForwardedTypesSerializationBinder when its SafeMode is set to ) because they could be used to weaken the security actions described above. These restrictions (along with the necessity of specifying expected types) have been introduced in version v8.0. To revert to the old safe mode approach you can use the LegacySafeMode option (not recommended).

This flag is considered on deserialization.

Default state at serialization methods in BinarySerializer: Enabled

AllowNonSerializableExpectedCustomTypes0x2000

Indicates that recursively serialized types that are indicated as expected types at the deserialization methods should be able to be deserialized in SafeMode even if they are not marked by the SerializableAttribute.

This flag is considered on deserialization.

Default state at serialization methods in BinarySerializer: Disabled

PreferInvokingDefaultConstructor0x4000

Indicates that the default constructor should be called when it exists and no other constructor would be called on deserialization otherwise.

This flag is considered on deserialization.

This flag does not affect IBinarySerializable types, as their default constructor is called anyway if the special constructor does not exist.

  Caution

The conventional formatter-based way for custom initialization is using serialization methods marked by the OnDeserializingAttribute or OnDeserializedAttribute attributes, or implementing the IDeserializationCallback interface. Using this flag may interfere with such custom initialization, as the serialization methods are still executed along with the regular initialization in the default constructor, unless the IgnoreSerializationMethods flags is also set. Also, the serialization method marked by OnDeserializingAttribute is still executed before the constructor call (if exists), maintaining the same initialization order as in case of using the special constructor. Please also note that the default constructor will not be called for types that implement ISerializable, unless SurrogateSelector is set, which prevents the special constructor to be called.

Default state at serialization methods in BinarySerializer: Disabled

LegacySafeMode0x8000

The SafeMode option became more and more strict lately, tempting users to turn it off rather than to address the stricter security requirements if deserialization broke after a version upgrade. This flag exists only to be able to use at least the earlier security settings instead of going completely unsafe, but it is not recommended to prefer this option in a new project.

Using this flag instead of SafeMode allows setting the SurrogateSelector and Binder properties to any custom instance.

In legacy safe mode it is not required to specify the expected types for deserialization (though when they are specified, they are respected). With no specified expected types, this option only prevents loading assemblies during deserialization, so all the assemblies that are referred by the serialization stream must be preloaded before starting the deserialization (though this restriction can be worked around by setting a custom binder that still can load assemblies, for example).

All the other restrictions of SafeMode are effective in LegacySafeMode as well. When both flags are set, the stricter SafeMode will be used.

Default state at serialization methods in BinarySerializer: Disabled

Extension Methods

AllFlagsDefined Gets whether every single bit value in flags are defined in the enum type of flags, or when flags is zero, it is checked whether zero is defined in the enum type of flags.
(Defined by EnumExtensions)
IsSingleFlag Gets whether only a single bit is set in value.
(Defined by EnumExtensions)

See Also