Upraviť

Zdieľať cez


DesignerSerializationManager Class

Definition

Provides an implementation of the IDesignerSerializationManager interface.

public ref class DesignerSerializationManager : IServiceProvider, System::ComponentModel::Design::Serialization::IDesignerSerializationManager
public class DesignerSerializationManager : IServiceProvider, System.ComponentModel.Design.Serialization.IDesignerSerializationManager
type DesignerSerializationManager = class
    interface IDesignerSerializationManager
    interface IServiceProvider
Public Class DesignerSerializationManager
Implements IDesignerSerializationManager, IServiceProvider
Inheritance
DesignerSerializationManager
Implements

Remarks

The IDesignerSerializationManager interface is designed to be a format-independent interface to an object that controls serialization. It essentially provides context and services to serializers, which actually perform the deserialization. IDesignerSerializationManager assists in the deserialization process by keeping track of objects. This is similar in technique to the IDesignerHost interface: designers actually provide the user interface (UI), and IDesignerHost provides the glue that allows different designers to work together.

The DesignerSerializationManager class implements IDesignerSerializationManager. It's designed to provide a generic form of deserialization that is similar to run-time serializers like the BinaryFormatter.

The DesignerSerializationManager class achieves three goals:

  • It is a simple, turnkey object that can be used to deserialize a variety of formats.

  • It is generic and not tied to any particular format. It can be used equally for CodeDOM deserialization as well as markup deserialization.

  • It is extensible and supports different serialization methods that are used in copy/paste and undo/redo scenarios.

Design-time serialization has the following differences from run-time object serialization:

  • The object performing the serialization is generally separate from the run-time object, so that design-time logic can be removed from a component.

  • The serialization scheme assumes the object will be created fully initialized, and then modified through property and method invocations during deserialization.

  • Properties of an object that have values that were never set on the object (the properties contain the default values) are not serialized. Conversely, the deserialization stream may have holes.

  • Emphasis is placed on the quality of the content within the serialization stream, rather than the full serialization of an object. This means that if there is no defined way to serialize an object, that object may be skipped rather than throwing an exception. The serialization engine may provide heuristics here to decide which failures can be ignored and which are unrecoverable.

  • The serialization stream may have more data than is needed for deserialization. Source code serialization, for example, has user code mixed in with the code needed to deserialize an object graph. This user code must be ignored on deserialization and preserved on serialization.

Because of these differences, a different serialization model applies to design-time serialization. This model utilizes a separate serializer object for each data type being serialized. Each serializer provides its small contribution to the problem as a whole. These serializers are all coordinated through a common serialization manager. The serialization manager is responsible for maintaining state between these different serializers. As an example, consider the following class:

public class SampleObject
{
    private string stringValue = null;
    private int intValue = int.MinValue;

    public string StringProperty 
    { 
        get { return this.stringValue; }

        set { this.stringValue = value; }
    }

    public int IntProperty 
    {
        get { return this.intValue; }

        set{ this.intValue = value; }
    }
}
Public Class SampleObject
   Private stringValue As String = Nothing
   Private intValue As Integer = Integer.MinValue
   
   
   Public Property StringProperty() As String
      Get
         Return Me.stringValue
      End Get 
      Set
         Me.stringValue = value
      End Set
   End Property 
   
   Public Property IntProperty() As Integer
      Get
         Return Me.intValue
      End Get 
      Set
         Me.intValue = value
      End Set
   End Property
End Class

An instance of this class would utilize three different serializers: one for SampleObject, one for strings, and another for integers. The serializer for SampleObject is called the root serializer because SampleObject is the root of the serialization graph. More complex object graphs can be created as well. For example, consider what would happen if SampleObject were changed as follows:

public class SampleObject
{
    private string stringValue = null;
    private int intValue = int.MinValue;
    private SampleObject childValue = null;

    public string StringProperty
    {
        get { return this.stringValue; }

        set { this.stringValue = value; }
    }

    public int IntProperty
    {
        get { return this.intValue; }

        set { this.intValue = value; }
    }

    public SampleObject Child
    {
        get { return this.childValue; }

        set { this.childValue = value; }
    }
}
Public Class SampleObject
   Private stringValue As String = Nothing
   Private intValue As Integer = Integer.MinValue
   Private childValue As SampleObject = Nothing
   
   
   Public Property StringProperty() As String
      Get
         Return Me.stringValue
      End Get 
      Set
         Me.stringValue = value
      End Set
   End Property 
   
   Public Property IntProperty() As Integer
      Get
         Return Me.intValue
      End Get 
      Set
         Me.intValue = value
      End Set
   End Property 
   
   Public Property Child() As SampleObject
      Get
         Return Me.childValue
      End Get 
      Set
         Me.childValue = value
      End Set
   End Property
End Class

This allows SampleObject to have a child that is another instance of itself. The following code fills in the object graph:

class Program
{
    static void Main(string[] args)
    {
        SampleObject root = new SampleObject();

        SampleObject currentObject = root;

        for (int i = 0; i < 10; i++)
        {
            SampleObject o = new SampleObject();

            currentObject.Child = o;

            currentObject = o;
        }
    }
}
Class Program
   
   Public Overloads Shared Sub Main()
      Main(System.Environment.GetCommandLineArgs())
   End Sub
   
   Overloads Shared Sub Main(args() As String)
      Dim root As New SampleObject()
      
      Dim currentObject As SampleObject = root
      
      Dim i As Integer
      For i = 0 To 9
         Dim o As New SampleObject()
         
         currentObject.Child = o
         
         currentObject = o
      Next i
   End Sub 
End Class

When root is serialized, there will be four serializers used: one root serializer, one serializer for the child SampleObject, one serializer for int, and one serializer for string. Serializers are cached based on type, so there is no need to create a serializer for each instance of SampleObject.

The DesignerSerializationManager class is based on the idea of a serialization session. A session maintains state that can be accessed by the various serializers. When a session is disposed, this state is destroyed. This helps to ensure that serializers remain largely stateless, and helps to clean up serializers that are have been corrupted. The following tables describe how state is managed in and among sessions.

Global State

This state is owned by the serialization manager object, but is independent of the current serialization session.

Object Usage
Serialization providers Objects can add themselves as custom serialization providers. Because these providers are used to locate serializers, they outlive a serialization session.

Session-Owned State

This state is owned by a session and is destroyed when a session is destroyed. Consequently, accessing any properties or methods that would manipulate this state will throw an exception if the serialization manager is not in an active session.

Object Usage
ResolveName event The ResolveName event is attached by a serializer to provide additional resolution of names. All handlers are detached from this event when a session terminates.
SerializationComplete event The SerializationComplete event is raised just before a session is disposed. Then, all handlers are detached from this event.
Name table The serialization manager maintains a table that maps between objects and their names. Serializers may give objects names for easy identification. This name table is cleared when the session terminates.
Serializer cache The serialization manager maintains a cache of serializers it has been asked to supply. This cache is cleared when the session terminates. The public GetSerializer method can safely be called at any time, but its value is cached only if it is called from within a session.
Context stack The serialization manager maintains an object called the context stack, which you can access with the Context property. Serializers can use this stack to store additional information that is available to other serializers. For example, a serializer that is serializing a property value can push the property name on the serialization stack before asking the value to serialize. This stack is cleared when the session is terminated.
Error list The serialization manager maintains a list of errors that occurred during serialization. This list, which is accessed through the Errors property, is cleared when the session is terminated. Accessing the Errors property between sessions will result in an exception.

Constructors

DesignerSerializationManager()

Initializes a new instance of the DesignerSerializationManager class.

DesignerSerializationManager(IServiceProvider)

Initializes a new instance of the DesignerSerializationManager class with the given service provider.

Properties

Container

Gets or sets to the container for this serialization manager.

Errors

Gets the list of errors that occurred during serialization or deserialization.

PreserveNames

Gets or sets a value indicating whether the CreateInstance(Type, ICollection, String, Boolean) method should check for the presence of the given name in the container.

PropertyProvider

Gets the object that should be used to provide properties to the serialization manager's Properties property.

RecycleInstances

Gets or sets a value that indicates whether CreateInstance(Type, ICollection, String, Boolean) will always create a new instance of a type.

ValidateRecycledTypes

Gets or sets a value that indicates whether the CreateInstance(Type, ICollection, String, Boolean) method will verify that matching names refer to the same type.

Methods

CreateInstance(Type, ICollection, String, Boolean)

Creates an instance of a type.

CreateSession()

Creates a new serialization session.

Equals(Object)

Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetHashCode()

Serves as the default hash function.

(Inherited from Object)
GetRuntimeType(String)

Gets the type corresponding to the specified type name.

GetSerializer(Type, Type)

Gets the serializer for the given object type.

GetService(Type)

Gets the requested service.

GetType()

Gets the Type of the current instance.

(Inherited from Object)
GetType(String)

Gets the requested type.

MemberwiseClone()

Creates a shallow copy of the current Object.

(Inherited from Object)
OnResolveName(ResolveNameEventArgs)

Raises the ResolveName event.

OnSessionCreated(EventArgs)

Raises the SessionCreated event.

OnSessionDisposed(EventArgs)

Raises the SessionDisposed event.

ToString()

Returns a string that represents the current object.

(Inherited from Object)

Events

SessionCreated

Occurs when a session is created.

SessionDisposed

Occurs when a session is disposed.

Explicit Interface Implementations

IDesignerSerializationManager.AddSerializationProvider(IDesignerSerializationProvider)

Adds a custom serialization provider to the serialization manager.

IDesignerSerializationManager.Context

Gets the context stack for this serialization session.

IDesignerSerializationManager.CreateInstance(Type, ICollection, String, Boolean)

Implements the CreateInstance(Type, ICollection, String, Boolean) method.

IDesignerSerializationManager.GetInstance(String)

Retrieves an instance of a created object of the specified name.

IDesignerSerializationManager.GetName(Object)

Retrieves a name for the specified object.

IDesignerSerializationManager.GetSerializer(Type, Type)

Gets a serializer of the requested type for the specified object type.

IDesignerSerializationManager.GetType(String)

Gets a type of the specified name.

IDesignerSerializationManager.Properties

Implements the Properties property.

IDesignerSerializationManager.RemoveSerializationProvider(IDesignerSerializationProvider)

Removes a previously added serialization provider.

IDesignerSerializationManager.ReportError(Object)

Used to report a recoverable error in serialization.

IDesignerSerializationManager.ResolveName

Occurs when IDesignerSerializationManager.GetName(Object) cannot locate the specified name in the serialization manager's name table.

IDesignerSerializationManager.SerializationComplete

Occurs when serialization is complete.

IDesignerSerializationManager.SetName(Object, String)

Sets the name for the specified object.

IServiceProvider.GetService(Type)

For a description of this member, see the GetService(Type) method.

Applies to

See also