Enum ReferencePreservationMode

Namespace

Nerdbank.MessagePack

Assembly

Nerdbank.MessagePack.dll

An enumeration of the modes supported for preserving references in serialized object graphs.

public enum ReferencePreservationMode

Fields

AllowCycles = 2

References are preserved. Cycles are allowed.

The remarks in RejectCycles apply to this mode as well.

This setting adds security implications. Deserializing untrusted data with this setting enabled may lead to a denial of service attack by allowing the data source to introduce unexpected reference cycles, leading to an object graph that causes the program to crash with a StackOverflowException later while operating on that object graph.

Not all cycles can be deserialized. Consider the cycle of A -> B -> A. If A is first to be deserialized, then this cycle can be deserialized if and only if A has a default constructor and no required or init properties. In brief, only the last serialized object in a cycle is allowed to have a non-default constructor or required or initproperties due to limitations in the C# language and the way PolyType works. Since the order of serialized objects in a cycle is difficult to control in practice, any types that may be involved in cycles should avoid non-default constructors and required or initproperties.

Off = 0

References are not preserved. Attempts to deserialize a msgpack stream that includes references will throw MessagePackSerializationException.

If an object appears multiple times in a serialized object graph, it will be serialized anew at each location it is referenced. This has two outcomes: redundant data leading to larger serialized payloads and the loss of reference equality when deserialized.

Serialization will throw StackOverflowException (typically crashing the process) if the object graph contains cycles.

RejectCycles = 1

References are preserved. Cycles are rejected during serialization and deserialization.

When an object appears multiple times in an object graph, it will be serialized as a reference to the first occurrence. Deserialization will create a new object graph wherein objects are shared across the graph as they were in the original object graph. Of course there will not be reference equality between the original and deserialized objects, but the deserialized objects will have reference equality with each other.

This option utilizes a proprietary msgpack extension and can only be deserialized by libraries that understand this extension. A reference requires between 3-6 bytes in the msgpack stream instead of whatever the object's by-value representation would have required.

There is a small perf penalty for this feature, but depending on the object graph it may turn out to improve performance due to avoiding redundant serializations.