UIPSnap - Windows Forms "serialization" (C# / .NET)

 

Saving and restoring a form's state is an important requirement in many applications (e.g. to remember application settings). If a form hosts many controls this can result in huge amounts of code. This code needs to be maintained if the form changes. It's obvious that a general approach would ease this task.

If you try to serialize a windows form object, you will notice that in the .NET world these classes don't support serialization per se. This makes sense, since in a MVC designed architecture, it's usually the model's data you'd want to serialize, not the control itself. The usual approach would be to use databindings for the model and serialize / deserialize the model using formats like JSON or XML. However, the data model usually only represents a selected value and not the appearance of the UI element at the time of the selection. Many users however also prefer to find an application to appear the exact way as they left it before.

Since many controls are fairly simple, like a checkbox, radiobutton or a slidercontrol, their behaviour and appearance can be described by a number of properties  (e.g. size, visibility state or the selection index of a combo box). These properties have no complex data structures and can easily be serialized to save the form's state. So in this case, you would actually serialize a representation of the view instead of the model. Both ways can be combined, of course.

UIPSnap (User Interface Property Snap) is a library for serializing the state of windows forms and controls recursively to XML by reading and writing properties of certain types on a best-effort basis using reflection. It's very simple to use and yet provides some interesting possibilities of customizing.

Take a look at this example code:

UIPSnap snap = new UIPSnap();
string xml = snap.toXML(this);
File.WriteAllText("uistate.xml", xml);

Putting these 3 lines into a form's closing event handler will do the trick and save the form's state into an XML file. Similar code is needed to restore the form (e.g. in the form's shown event handler):

string xml = File.ReadAllText("uistate.xml");
snap.fromXML(this, xml);

 

Here is a screenshot of an example GUI whose state can be handled by UIPSnap:

 

So, which properties are actually saved? There are some rules:

  1. Properties that have simple data types (such as integer, double, string, datetime) or collections of these types.
  2. All properties that actually can be saved and restored (e.g., if a property describes a read-only collection, it will be skipped)
  3. Properties of controls (or child-controls) that are tagged. Tagging a control is done in the visual studio form's property grid by entering an integer number into the property field Tag. The number also defines the order in which controls are handled!
  4. Properties that you want to be saved. Filters can be defined.

There are some special cases that need to be handled properly in case of certain control types (e.g. UIPSnap handles also item collections of list and comboboxes and saves and restores multiple selection indices).

 Download

The above code is part of a visual studio example project bundled with the UIPSnap library binaries.

To download now, use this link. The software is shareware, but fully functional.

 How to obtain a license key

UIPSnap is shareware. You may test it for a duration of 30 days. After that you need to register to get a registration key against a small fee of 3,49 EUR (including VAT). Registered users are granted permission to bundle and distribute the UIPSnap library binaries along with any of their applications.

To order a key now, use this link.

The license key will be sent by email to the address provided by PayPal. If you don't want that, please use the optional message box of PayPal to provide another address or write a separate email before payment!

 Learn how to use UIPSnap in 5 minutes

How to get started

Download the library and copy the UIPSnap.dll into your VS Windows Forms project folder. Then add a project reference to the dll.

How to save and restore a form's state

Use the methods toXML and fromXML, as described before. See this complete example in the userguide and the UIPSnap class description.

Note that only properties of tagged controls are handled! You need to select each control in the form's edtior and enter a number into the Tag field. The number defines the order in which controls are handled! If the order is not important, just set every tag field to 0 (see fig. below).

Another thing: Each control must have a unique Name in the UI tree!

How to use the license key

Use the methods register and provide the key  sent to you by mail after you ordered it.

Example:

UIPSnap snap = new UIPSnap();
snap.register("<key>");  // UIPSnap won't display a "not registered" message.

How to include or exclude properties by names

You may define filters by the IncludeList and ExcludeList properties to control which properties are

Example (exclude width properties):

UIPSnap snap = new UIPSnap();
snap.ExcludeList.Add("Width");

How to add or remove types

You may access the type list by the TypeList property to control which property types are handled.

Example (remove string type):

UIPSnap snap = new UIPSnap();
snap.TypeList.Remove(typeof(string));

Further resources

Need more details? Take a look at the API documentation which also includes further examples.