Class AppStateSerializer

Provides a mechanism for coordinating the serialization behavior of multiple components.

Inheritance

System.Object

AppStateSerializer

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: Syncfusion.Runtime.Serialization

Assembly: Syncfusion.Shared.Base.dll

Syntax

public sealed class AppStateSerializer

Remarks

The AppStateSerializer class is a serialization utility that allows multiple components in an application to access a common disk I/O medium for state persistence. Using the same storage medium for persisting the state information across components, without overtly tying them together, helps avoid the file clutter that is bound to occur by components using distinct files. Though primarily developed for use by Syncfusion products, the AppStateSerializer is generic enough to be availed of by other components as well.

The AppStateSerializer supports serializing into the system's Isolated Storage, Windows Registry, an XML file, a binary file or to an externally provided Stream. Take a look at the SerializeMode enumeration for more information on these different supported modes.

To use the services of this class, you can create a new instance or use the global Singleton instance. These two usage patterns are explained below:

1) Using the Singleton: The AppStateSerializer class provides you a singleton instance (through the GetSingleton()) using which you can persist all your app. info into a single medium. This singleton, by default, is configured to persist in the Isolated Storage (with the scope IsolatedStorageScope.Assembly|IsolatedStorageScope.Domain|IsolatedStorageScope.User). This usage pattern is akin to creating an instance of this class and using the same instance to persist all your app information. But, note that this Singleton is also used by the Controls and Components in Essential Tools to persist their information. The default Storage medium of this Singleton instance can also be customized using the static InitializeSingleton(SerializeMode, Object) method. In short, use the Singleton whenever you want all your persistence information to be stored in a single medium (along with the persistence information of the Controls and Components in Essential Tools).

2) Using an instance: As an alternative you could create a custom instance of this class, configuring it to use one of the above storage mediums and persist one or more information into it. You can use this in tandem with the above Singleton instance if you wish. Make sure to call PersistNow() method when you are done writing into the serializer.

In both the above cases use the method's SerializeObject(String, Object) and DeserializeObject(String) to persist or depersist from the storage medium set for that instance.

Note that the AppStateSerializer class uses "Simple" type names (not strongly typed) to serialize types. This is necessary to enable usage of persisted information across different but compatible versions of an assembly. This will however cause the deserialization process to convert the serialized data to the type from the latest version of the assembly installed in the GAC, instead of the version that your app is linking to. You can overcome this by using the SetBindingInfo(String, Assembly) method.

Examples

Serializing using an instance:

// To Save
AppStateSerializer serializer = new AppStateSerializer(SerializeMode.XMLFile, "myfile");
serializer.SerializeObject("MyLabel", mydata);
serializer.PersistNow();
// To Load
AppStateSerializer serializer = new AppStateSerializer(SerializeMode.XMLFile, "myfile");
object loadedObj = serializer.DeserializeObject("MyLabel");
if(loadedObj != null && loadedObj is MyData)
{
	MyData myData = (MyData)loadedObj;
}

Serializing using Singleton:

// To Save
AppStateSerializer.GetSingleton().SerializeObject("MyLabel", mydata, true);
// To Load
object loadedObj = AppStateSerializer.GetSingleton().DeserializeObject("MyLabel");

Constructors

AppStateSerializer(SerializeMode, Object)

Overloaded. Creates an instance of the AppStateSerializer class.

Declaration

public AppStateSerializer(SerializeMode mode, object persistpath)

Parameters

Type	Name	Description
SerializeMode	mode	The SerializeMode in which to create.
System.Object	persistpath	The persistence path to be used for this mode. See remarks for more info.

Remarks

The persistpath argument should be based on the SerializationMode property, as follows:

A string representing the file name (an .XML suffix will be added) in which to store.
A string representing the file name (a .bin suffix will be added) in which to store.
A Microsoft.Win32.RegistryKey under which to persist.
A string representing the file name (a .bin suffix will be added) in which to store within the Isolated Storage.
An instance of a System.IO.Stream derived class with Read, Write, and Seek capability.

If using the IsolatedStorage mode, then the default isolated storage scope (Domain | Assembly | User) will be used. Use the three argument constructor to specify a custom scope.

AppStateSerializer(SerializeMode, Object, IsolatedStorageScope)

Creates an instance of the AppStateSerializer class.

Declaration

public AppStateSerializer(SerializeMode mode, object persistpath, IsolatedStorageScope scope)

Parameters

Type	Name	Description
SerializeMode	mode	The SerializeMode in which to create.
System.Object	persistpath	The persistence path to be used for this mode. See remarks for more info.
System.IO.IsolatedStorage.IsolatedStorageScope	scope	The System.IO.IsolatedStorage.IsolatedStorageScope to be used if the mode is set to SerializeMode.IsolatedStorage.

Remarks

The persistpath argument should be based on the SerializationMode property, as follows:

A string representing the file name (an .XML suffix will be added) in which to store.
A string representing the file name (a .bin suffix will be added) in which to store.
A Microsoft.Win32.RegistryKey under which to persist.
A string representing the file name (a .bin suffix will be added) in which to store within the Isolated Storage.
An instance of a System.IO.Stream derived class with Read, Write, and Seek capability.

The scope parameter will be referred to if using the IsolatedStorage mode.

Fields

AppendFileExtension

Declaration

public static bool AppendFileExtension

Field Value

Type	Description
System.Boolean

SerializationCulture

Gets or sets the System.Globalization.CultureInfo value to serialize or deserialize the properties based on either current UI culture or invariant culture. Default value is null.

Declaration

public static CultureInfo SerializationCulture

Field Value

Type	Description
System.Globalization.CultureInfo

Remarks

This is applicable only for Grid Control.

Properties

CustomBinder

Declaration

public static CustomSerializationBinder CustomBinder { get; }

Property Value

Type	Description
CustomSerializationBinder

DeserializedInfoApplicationVersion

Returns the version of the application (got through the Application.ProductVersion property) whose state has now been deserialized.

Declaration

public string DeserializedInfoApplicationVersion { get; }

Property Value

Type	Description
System.String	The version as string if available. String.Empty otherwise.

Remarks

This gives you some information about the state of the deserialized information - as to which version of the application it belonged to.

Enabled

Indicates whether serialization and deserialization is enabled.

Declaration

public bool Enabled { get; set; }

Property Value

Type	Description
System.Boolean	True to enable serialization; false otherwise. This property is set to True by default.

Remarks

This property allows you to temporarily enable / disable serialization.

IsoStorageScope

Returns the IsolatedStorageScope used by the AppStateSerializer.

Declaration

public IsolatedStorageScope IsoStorageScope { get; }

Property Value

Type	Description
System.IO.IsolatedStorage.IsolatedStorageScope	An System.IO.IsolatedStorage.IsolatedStorageScope value.

Remarks

This property is used only if the mode is set to SerializeMode.IsolatedStorage.

SerializationMode

Returns the persistence mode set for the AppStateSerializer.

Declaration

public SerializeMode SerializationMode { get; }

Property Value

Type	Description
SerializeMode	A SerializeMode value.

SerializationPath

Returns the persistence path set for the AppStateSerializer.

Declaration

public object SerializationPath { get; }

Property Value

Type	Description
System.Object	An object of type varying based on the the SerializationMode.

Remarks

The persistence path is contextual and is interpreted based on the SerializationMode property value.

ShouldThrowException

Gets or sets a bool value to indicate whether the exception should throw while reading the file from stream or not.

Declaration

public static bool ShouldThrowException { get; set; }

Property Value

Type	Description
System.Boolean	`true` if it should throw the exception to handle it while reading the file stream; otherwise, `false`.

Methods

DeserializeIsolatedObject(SerializeMode, Object, String)

Overloaded. Deserializes an object from the specified persistent store.

Declaration

[Obsolete("This method will be removed in a future version. Please check the class reference for an alternative.", false)]
public static object DeserializeIsolatedObject(SerializeMode mode, object persistpath, string strname)

Parameters

Type	Name	Description
SerializeMode	mode	A SerializeMode value describing the persistence medium.
System.Object	persistpath	Represents the persistence medium.
System.String	strname	A string descriptor for the object.

Returns

Type	Description
System.Object	The deserialized object.

Remarks

If Enabled is False, then this method will not deserialize.

This method has been replaced and will be removed form a future version. Instead, create a new instance of the AppStateSerializer class (with the mode and persist path) and then use the SerializeObject(String, Object, Boolean) and DeserializeObject(String).

DeserializeIsolatedObject(Object, IsolatedStorageScope, String)

Deserializes an object from Isolated Storage.

Declaration

[Obsolete("This method will be removed in a future version. Please check the class reference for an alternative.", false)]
public static object DeserializeIsolatedObject(object persistpath, IsolatedStorageScope scope, string strname)

Parameters

Type	Name	Description
System.Object	persistpath	The name of the IsolatedStorageFile.
System.IO.IsolatedStorage.IsolatedStorageScope	scope	The IsolatedStorageScope to be used.
System.String	strname	A string descriptor for the object.

Returns

Type	Description
System.Object	The deserialized object.

Remarks

If Enabled is False, then this method will not deserialize.

DeserializeObject(String)

Deserializes the object from the persistent store.

Declaration

public object DeserializeObject(string strname)

Parameters

Type	Name	Description
System.String	strname	The object descriptor.

Returns

Type	Description
System.Object	The deserialized object.

Remarks

If the Enabled is False, then this method will not deserialize.

FlushSerializer()

Clears the serialization map and deletes the persistent store.

If the persistent store is an external stream, then FlushSerializer just clears the serialization map and returns without affecting the stream.

Declaration

public void FlushSerializer()

GetInstance()

Returns a reference to the unique AppStateSerializer instance.

Declaration

[Obsolete("This method will be removed in a future version. Please use the GetSingleton method instead.", false)]
public static AppStateSerializer GetInstance()

Returns

Type	Description
AppStateSerializer	The AppStateSerializer instance.

Remarks

This method will be removed in a future version. Please use the GetSingleton method instead.

GetSingleton()

Returns a reference to the unique AppStateSerializer instance.

Declaration

public static AppStateSerializer GetSingleton()

Returns

Type	Description
AppStateSerializer	The AppStateSerializer instance.

InitializeSerializer(SerializeMode, Object, IsolatedStorageScope)

Sets the persistence mode and persistence path for the singleton instance of AppStateSerializer.

Declaration

[Obsolete("This method will be removed in a future version. Please use the InitializeSingleton method instead.", false)]
public static void InitializeSerializer(SerializeMode mode, object persistpath, IsolatedStorageScope scope)

Parameters

Type	Name	Description
SerializeMode	mode	A SerializeMode value.
System.Object	persistpath	An object that represents the persistence medium.
System.IO.IsolatedStorage.IsolatedStorageScope	scope	The IsolatedStorageScope to be used.

Remarks

The singleton's parameters can only be changed before it gets created. It gets created in the first call to the GetSingleton() method. You can force the serializer to clear its serialization map by using the FlushSerializer() method.

This method will be removed in a future version. Please use the InitializeSingleton method instead.

InitializeSingleton(SerializeMode, Object)

Sets the persistence mode and persistence path for the singleton instance of AppStateSerializer.

Declaration

public static void InitializeSingleton(SerializeMode mode, object persistpath)

Parameters

Type	Name	Description
SerializeMode	mode	A SerializeMode value.
System.Object	persistpath	An object that represents the persistence medium.

Remarks

If the mode is set to Isolated Storage, then the default isolated storage scope will be used.

The persistpath argument should be based on the SerializationMode property, as follows:

A string representing the file name (an .XML suffix will be added) in which to store.
A string representing the file name (a .bin suffix will be added) in which to store.
A Microsoft.Win32.RegistryKey under which to persist.
A string representing the file name (a .bin suffix will be added) in which to store within the Isolated Storage.
An instance of a System.IO.Stream derived class with Read, Write and Seek capability.

Examples

public Form1()
{
	// To make the singleton use an XML file:
	AppStateSerializer.InitializeSingleton(SerializeMode.XMLFile, "GlobalState");

	InitializeComponent();
}

InitializeSingleton(SerializeMode, Object, IsolatedStorageScope)

Overloaded. Sets the persistence mode and persistence path for the singleton instance of AppStateSerializer.

Declaration

public static void InitializeSingleton(SerializeMode mode, object persistpath, IsolatedStorageScope scope)

Parameters

Type	Name	Description
SerializeMode	mode	A SerializeMode value.
System.Object	persistpath	An object that represents the persistence medium.
System.IO.IsolatedStorage.IsolatedStorageScope	scope	The IsolatedStorageScope to be used. Referred only when the mode is IsolatedStorage.

Remarks

The singleton's parameters can only be changed before it gets created. It gets created in the first call to GetSingleton() method. You can force the serializer to clear its serialization map by using the FlushSerializer() method.

OnApplicationExit(Object, EventArgs)

Declaration

public void OnApplicationExit(object sender, EventArgs e)

Parameters

Type	Name	Description
System.Object	sender
System.EventArgs	e

PersistNow()

Writes the AppStateSerializer's contents to the persistent storage.

Declaration

public void PersistNow()

Remarks

If Enabled is False, then this method will not persist.

RemoveInfoForObject(String)

Declaration

public void RemoveInfoForObject(string strName)

Parameters

Type	Name	Description
System.String	strName

SerializeIsolatedObject(SerializeMode, Object, String, Object)

Overloaded. Serializes the object to the specified persistence medium.

Declaration

[Obsolete("This method will be removed in a future version. Please check the class reference for an alternative.", false)]
public static void SerializeIsolatedObject(SerializeMode mode, object persistpath, string strname, object obj)

Parameters

Type	Name	Description
SerializeMode	mode	A SerializeMode value describing the persistence medium.
System.Object	persistpath	Represents the persistence medium.
System.String	strname	A string descriptor for the object.
System.Object	obj	The object to be serialized. Use NULL to delete the object's store.

Remarks

If Enabled is False, then this method will not serialize.

SerializeIsolatedObject(Object, IsolatedStorageScope, String, Object)

Serializes the object to Isolated Storage.

Declaration

[Obsolete("This method will be removed in a future version. Please check the class reference for an alternative.", false)]
public static void SerializeIsolatedObject(object persistpath, IsolatedStorageScope scope, string strname, object obj)

Parameters

Type	Name	Description
System.Object	persistpath	The name of the IsolatedStorageFile.
System.IO.IsolatedStorage.IsolatedStorageScope	scope	The IsolatedStorageScope to be used.
System.String	strname	A string descriptor for the object.
System.Object	obj	The object to be serialized. Use NULL to delete the object's store.

Remarks

If Enabled is False, then this method will not serialize.

SerializeObject(String, Object)

Overloaded. Writes the object to persistent storage under the specified tag.

Declaration

public void SerializeObject(string strname, object obj)

Parameters

Type	Name	Description
System.String	strname	A descriptor tag for the object.
System.Object	obj	The object to be persisted. If NULL, an existing object is removed from the serialization map.

Remarks

If the Enabled is False, then this method will not serialize.

SerializeObject(String, Object, Boolean)

Writes the object to persistent storage under the specified tag.

Declaration

public void SerializeObject(string strname, object obj, bool infinalize)

Parameters

Type	Name	Description
System.String	strname	A descriptor tag for the object.
System.Object	obj	The object to be persisted. Use NULL to remove an existing object from the serialization map.
System.Boolean	infinalize	When this parameter is True, the object is serialized only at the point when it is being written to the persistent storage medium. This usually happens only when the serializer is being finalized.

Remarks

If the Enabled is False, then this method will not serialize.

SetBindingInfo(String, Assembly)

Controls the binding of an assembly name to a specific System.Reflection.Assembly.

Declaration

public static void SetBindingInfo(string assemblyName, Assembly assembly)

Parameters

Type	Name	Description
System.String	assemblyName	The assembly name string.
System.Reflection.Assembly	assembly	The corresponding Assembly to bind to.

Remarks

The AppStateSerializer class, by default, uses "Simple" assembly names (not strongly typed) to serialize types. This renders the deserialization process unpredictable because the resultant type of an object after deserialization is dependent upon the latest version of that assembly installed in the GAC, if any. This will usually result in casting errors during the deserialization process when the app is linking to an older version of the assembly and when a newer version of the assembly is installed in the GAC.

This method allows you to overcome this limitation by associating a "Simple" assembly name with a specific System.Reflection.Assembly.

Examples

This example will bind the assembly that the app is linking to, to the "Simple" assembly name. Do this from the static constructor of the class that uses the AppStateSerializer class:

static MyType()
{
        AppStateSerializer.SetBindingInfo("MyNameSpace.MyType", typeof(MyType).Assembly);
}

SetTypeBindingInfo(String, String, Assembly)

Binds a type in the specified assembly to the same type in a different assembly. Typically useful in supporting backward compatibility.

Declaration

public static void SetTypeBindingInfo(string assemblyName, string typeName, Assembly assembly)

Parameters

Type	Name	Description
System.String	assemblyName	The assembly name string.
System.String	typeName	The type name string.
System.Reflection.Assembly	assembly	The corresponding Assembly to bind to.

Remarks

This method is useful when you renamed your assembly and you want to map the old types to the new types in the new assembly. If you didn't rename the assembly, then just consider using the SetBindingInfo(String, Assembly) method.

SetTypeToTypeBindingInfo(String, String)

Binds the oldtypename type to the newtypename type. This method comes in handy when serialized types have undergone a name change and backward compatibility is to be retained.

Declaration

public static void SetTypeToTypeBindingInfo(string oldtypename, string newtypename)

Parameters

Type	Name	Description
System.String	oldtypename	The old name of the type.
System.String	newtypename	The new name of the type.

Events

BeforePersist

Occurs just before the contents of the AppStateSerializer are persisted.

Declaration

public event EventHandler BeforePersist

Event Type

Type	Description
System.EventHandler