menu

WinForms

  • Code Examples
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class AppStateSerializer - WindowsForms API Reference | Syncfusion

    Show / Hide Table of Contents

    Class AppStateSerializer

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

    Inheritance
    System.Object
    AppStateSerializer
    Inherited Members
    System.Object.Equals(System.Object)
    System.Object.Equals(System.Object, System.Object)
    System.Object.GetHashCode()
    System.Object.GetType()
    System.Object.MemberwiseClone()
    System.Object.ReferenceEquals(System.Object, System.Object)
    System.Object.ToString()
    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, Object) 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
    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
    System.Globalization.CultureInfo
    Remarks

    This is applicable only for Grid Control.

    Properties

    CustomBinder

    Declaration
    public static CustomSerializationBinder CustomBinder { get; }
    Property Value
    Type
    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, Object).

    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.

    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, Object).

    DeserializeObject(String, Object)

    Deserializes the object from the persistent store.

    Declaration
    public object DeserializeObject(string strname, object objToDeserialize = null)
    Parameters
    Type Name Description
    System.String strname

    The object descriptor.

    System.Object objToDeserialize
    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

    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.

    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.

    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, Object) methods to persist information. Make sure to call PersistNow() when done persisting.

    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.

    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, Object) methods to persist information. Make sure to call PersistNow() when done persisting.

    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
    System.EventHandler
    Back to top Generated by DocFX
    Copyright © 2001 - 2025 Syncfusion Inc. All Rights Reserved