System.Runtime.Serialization.ObjectManager Class

Summary

Keeps track of objects as they are deserialized.

C# Syntax:

public class ObjectManager

During deserialization, the Formatter queries the ObjectManager to determine whether a reference to an object in the serialized stream refers to an object that has already been deserialized (a backward reference), or to an object that has not yet been deserialized (a forward reference). If the reference in the serialized stream is a forward reference, then the Formatter can register a fixup with the ObjectManager. If the reference in the serialized stream is a backward reference, the Formatter immediately completes the reference. Fixup refers to the process of finalizing object references not already completed during the object deserialization process. After the required object has been deserialized, the ObjectManager will complete the reference.

The ObjectManager follows a set of rules that dictate the fixup order. All objects that implement ISerializable or have an ISerializationSurrogate can expect to have all the objects that they transmitted through SerializationInfo available when the object tree is deserialized. However, a parent object cannot presume that all its child objects will be fully completed when it is fully deserialized. All child objects will be present but not all the grandchild objects will necessarily be present. If an object needs to take certain actions that depend on executing code on its child objects, it can delay these actions, implement the IDeserializationCallback interface, and execute the code only when it is called back on this interface.

System.Runtime.Serialization Namespace

System.Runtime.Serialization.ObjectManager Member List:

Public Constructors

ctor #1

Initializes a new instance of the ObjectManager class.

Public Methods

DoFixups	Performs all the recorded fixups.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetObject	Returns the object with the specified object ID.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
RaiseDeserializationEvent	Raises the deserialization event to any registered object that implements IDeserializationCallback.
RecordArrayElementFixup	Overloaded: RecordArrayElementFixup(long arrayToBeFixed, int index, long objectRequired) Records a fixup for one element in an array.
RecordArrayElementFixup	Overloaded: RecordArrayElementFixup(long arrayToBeFixed, int[] indices, long objectRequired) Records fixups for the specified elements in an array to be executed later.
RecordDelayedFixup	Records a fixup for an object member to be executed later.
RecordFixup	Records a fixup for a member of an object to be executed later.
RegisterObject	Overloaded: RegisterObject(object obj, long objectID) Registers an object as it is deserialized, associating it with objectID.
RegisterObject	Overloaded: RegisterObject(object obj, long objectID, SerializationInfo info) Registers an object as it is deserialized, associating it with objectID, and recording the SerializationInfo used with it.
RegisterObject	Overloaded: RegisterObject(object obj, long objectID, SerializationInfo info, long idOfContainingObj, MemberInfo member) Registers a member of an object as it is deserialized, associating it with objectID, and recording the SerializationInfo.
RegisterObject	Overloaded: RegisterObject(object obj, long objectID, SerializationInfo info, long idOfContainingObj, MemberInfo member, int[] arrayIndex) Registers a member of an array contained in an object while it is deserialized, associating it with objectID, and recording the SerializationInfo.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Runtime.Serialization.ObjectManager

System.Runtime.Serialization.ObjectManager Member Details

Summary

Initializes a new instance of the ObjectManager class.

C# Syntax:

public ObjectManager(    ISurrogateSelector selector,    StreamingContext context );

selector

The surrogate selector to use. The ISurrogateSelector determines the correct surrogate to use when deserializing objects of a given type. At deserialization time, the surrogate selector creates a new instance of the object from the information transmitted on the stream.

context

The streaming context. The StreamingContext is not used by the ObjectManager, but is passed as a parameter to any objects implementing ISerializable or having a ISerializationSurrogate. These objects can take specific actions depending on the source of the information to deserialize.

Return to top

Summary

Performs all the recorded fixups.

C# Syntax:

public virtual void DoFixups();

Exceptions

Exception Type	Condition
SerializationException	A fixup was not successfully completed.

The fixups are carried out by any appropriate surrogate, the object itself (if it implements ISerializable), or the default implementation.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~ObjectManager();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns the object with the specified object ID.

C# Syntax:

public virtual object GetObject(    long objectID );

objectID

The ID of the requested object.

Return Value:

The object with the specified object ID if it has been previously stored, or null if no such object has been registered.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The objectID parameter is less than or equal to zero.

An object can be registered and issued an object ID with a call to the ObjectManager.RegisterObject method.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Raises the deserialization event to any registered object that implements IDeserializationCallback.

C# Syntax:

public virtual void RaiseDeserializationEvent();

Return to top

Summary

Records a fixup for one element in an array.

C# Syntax:

public virtual void RecordArrayElementFixup(    long arrayToBeFixed,    int index,    long objectRequired );

arrayToBeFixed

The ID of the array used to record a fixup.

index

The index within arrayFixup that a fixup is requested for.

objectRequired

The ID of the object that the current array element will point to after fixup is completed.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The arrayToBeFixed or objectRequired parameter is less than or equal to zero.
ArgumentNullException	The index parameter is null.

The fixup is for a specified element of a specified array. The value used during the fixup process is provided in the objectRequired parameter.

Return to top

Summary

Records fixups for the specified elements in an array to be executed later.

C# Syntax:

public virtual void RecordArrayElementFixup(    long arrayToBeFixed,    int[] indices,    long objectRequired );

arrayToBeFixed

The ID of the array used to record a fixup.

indices

The indexes within the multidimensional array that a fixup is requested for.

objectRequired

The ID of the object the array elements will point to after fixup is completed.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The arrayToBeFixed or objectRequired parameter is less than or equal to zero.
ArgumentNullException	The indices parameter is null.

The fixup is for specified elements of a specified array. The value used during the fixup process is provided in the objectRequired parameter.

Return to top

Summary

Records a fixup for an object member to be executed later.

C# Syntax:

public virtual void RecordDelayedFixup(    long objectToBeFixed,    string memberName,    long objectRequired );

objectToBeFixed

The ID of the object that needs the reference to objectRequired.

memberName

The member name of objectToBeFixed where the fixup will be performed.

objectRequired

The ID of the object required by objectToBeFixed.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	objectToBeFixed or objectRequired parameter is less than or equal to zero.
ArgumentNullException	The memberName parameter is null.

The fixup is for a specified member of a specified object. The value to be used during the fixup process is provided as the objectRequired argument.

Return to top

Summary

Records a fixup for a member of an object to be executed later.

C# Syntax:

public virtual void RecordFixup(    long objectToBeFixed,    MemberInfo member,    long objectRequired );

objectToBeFixed

The ID of the object that needs the reference to the objectRequired object.

member

The member of objectToBeFixed where the fixup will be performed.

objectRequired

The ID of the object required by objectToBeFixed.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The objectToBeFixed or objectRequired parameter is less than or equal to zero.
ArgumentNullException	The member parameter is null.

The fixup is for a specified member of a specified object. The value to be used during the fixup process is provided as the objectRequired parameter.

Return to top

Summary

Registers an object as it is deserialized, associating it with objectID.

C# Syntax:

public virtual void RegisterObject(    object obj,    long objectID );

obj

The object to register.

objectID

The ID of the object to register.

Exceptions

Exception Type	Condition
ArgumentNullException	The obj parameter is null.
ArgumentOutOfRangeException	The objectID parameter is less than or equal to zero.
SerializationException	The objectID has already been registered for an object other than obj.

ObjectManager retains information about both the object and its ID. Later during deserialization, ObjectManager.GetObject can be used to determine whether a particular object ID has already been deserialized, or whether it is a forward reference to an object that has not yet been deserialized.

Return to top

Summary

Registers an object as it is deserialized, associating it with objectID, and recording the SerializationInfo used with it.

C# Syntax:

public void RegisterObject(    object obj,    long objectID,    SerializationInfo info );

obj

The object to register.

objectID

The ID of the object to register.

info

The SerializationInfo used if obj implements ISerializable or has an ISerializationSurrogate.info will be completed with any required fixup information and then passed to the required object when that object is completed.

Exceptions

Exception Type	Condition
ArgumentNullException	The obj parameter is null.
ArgumentOutOfRangeException	The objectID parameter is less than or equal to zero.
SerializationException	The objectID has already been registered for an object other than obj.

ObjectManager retains the information about both the object and its ID. Later during deserialization, you can use ObjectManager.GetObject to discover whether a particular object ID has already been deserialized, or if it is a forward reference to an object that has not yet been deserialized.

Return to top

Summary

Registers a member of an object as it is deserialized, associating it with objectID, and recording the SerializationInfo.

C# Syntax:

public void RegisterObject(    object obj,    long objectID,    SerializationInfo info,    long idOfContainingObj,    MemberInfo member );

obj

The object to register.

objectID

The ID of the object to register.

info

The SerializationInfo used if obj implements ISerializable or has an ISerializationSurrogate.info will be completed with any required fixup information and then passed to the required object when that object is completed.

idOfContainingObj

The ID of the object that contains obj. This parameter is required only if obj is a value type.

member

The field in the containing object where obj exists. This parameter has meaning only if obj is a value type.

Exceptions

Exception Type	Condition
ArgumentNullException	The obj parameter is null.
ArgumentOutOfRangeException	The objectID parameter is less than or equal to zero.
SerializationException	The objectID has already been registered for an object other than obj, or member is not a FieldInfo and member is not null.

You need to provide the member and idOfContainingObj parameters if obj is a ValueType because of the way fixups are performed on ValueType objects. The space to store the information for a ValueType is allocated inline with its containing object. However, when the ValueType is boxed to be registered with the ObjectManager, it loses the connection with its containing object. To guarantee that fixups occur in the instance of the ValueType stored in the containing object and not in the boxed instance, the ObjectManager retains some additional information.

ObjectManager retains information about both the object and its ID. Later during deserialization, ObjectManager.GetObject can be used to discover whether a particular object ID has already been deserialized, or whether it is a forward reference to an object not yet deserialized.

Return to top

Summary

Registers a member of an array contained in an object while it is deserialized, associating it with objectID, and recording the SerializationInfo.

C# Syntax:

public void RegisterObject(    object obj,    long objectID,    SerializationInfo info,    long idOfContainingObj,    MemberInfo member,    int[] arrayIndex );

obj

The object to register.

objectID

The ID of the object to register.

info

The SerializationInfo used if obj implements ISerializable or has an ISerializationSurrogate.info will be completed with any required fixup information and then passed to the required object when that object is completed.

idOfContainingObj

The ID of the object that contains obj. This parameter is required only if obj is a value type.

member

The field in the containing object where obj exists. This parameter has meaning only if obj is a value type.

arrayIndex

If obj is a ValueType and a member of an array, arrayIndex contains the index within that array where obj exists.arrayIndex is ignored if obj is not both a ValueType and a member of an array.

Exceptions

Exception Type	Condition
ArgumentNullException	The obj parameter is null.
ArgumentOutOfRangeException	The objectID parameter is less than or equal to zero.
SerializationException	The objectID has already been registered for an object other than obj, or member is not a FieldInfo and member isn't null.

You need to provide the member and idOfContainingObj parameters if obj is a ValueType because of the way fixups are performed on ValueType objects. The space to store the information for a ValueType is allocated inline with its containing object. However, when the ValueType is boxed to be registered with the ObjectManager, it loses the connection with its containing object. To guarantee that fixups occur in the instance of the ValueType stored in the containing object and not in the boxed instance, the ObjectManager retains some additional information.

ObjectManager retains information about both the object and its ID. Later during deserialization, ObjectManager.GetObject can be used to discover whether a particular object ID has already been deserialized, or whether it is a forward reference to an object not yet deserialized.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page