Using The Data Serializer

Making a Class Serializable

There is no special attribute to be applied to a class to make it serializable. The only requirement for a class to be serializable is to have a default constructor (which can be private).

The DataItemAttribute attribute can be used to set the name of the type in the serialized data model. By default it's the name of the class. This attribute is optional. Here is an example of how this attribute can be used:

[DataItem ("DataTest")]
public class SerializationTest
{
    ...
}

<DataTest>
   ...
</DataTest>

Fields and Properties

An important difference between DataSerializer and other serializers is that fields and properties are not serialized by default. For a field or property to be serialized, the ItemPropertyAttribute attribute has to be explicitly applied to it.

The serializer generates a DataNode for each serializable member. This DataNode will be a DataValue if the member has a primitive value, or a DataItem if the member is a class (members of the class will be serialized as children of that DataItem).

ItemPropertyAttribute has several properties (all of them optional) that can be set to change the default serialization behavior:

• Name: Name of the property in the serialized model. It's the member name by default. You can specify a nested element name. For example, the name "Data/Name" will create the property as a child of the Data element, and it will be named "Name".
• DefaultValue: Default value of the member. A property won't be serialized if the assigned value is the default value.
• ReadOnly: true if the member will be read but never written.
• WriteOnly: true if the member will be written but never read.
• Scope: When added to a collection or array member, it specifies the nesting level to which the ItemPropertyAttribute applies. This is explained in more detail below.
• ValueType: Specifies the type to use for serialization, if the one declared in the member is too generic.

For example:

public class SerializationTest
{
    // This field won't be serialized
    int someInt;

    // This field will be serialized
    [ItemProperty]
    string someString = "Hi";

    // This field will be serialized with a custom name
    [ItemProperty ("CustomName")]
    int value = 44;

    // This field will be serialized, but only if its value
    // is not "Bye" (so it won't be serialized in this example)
    [ItemProperty (DefaultValue = "Bye")]
    string someDefaultString = "Bye";

    // This field will be serialized as a child element of "Data"
    [ItemProperty ("Data/Info")]
    string someInfo = "some info";
}

<SerializationTest
      someString = "Hi"
      CustomName = "44">
    <Data Info = "some info" />
</SerializationTest>

Serializing Lists

The DataSerializer will serialize an object as a collection of items if:

• the object is an array
• the type of the object implements IList, with a public Add method.

Lists are serialized as a DataItem which has a DataNode for each element of the list. The root DataItem can be customized using the ItemPropertyAttribute just like any other member of a type.

For example:

public class SerializationTest
{
    // A simple collection of strings
    [ItemProperty ("Names")]
    List<string> names = new List<string> ();

    public SerializationTest ()
    {
        names.Add ("Jordi");
        names.Add ("Maria");
    }
}

<SerializationTest>
    <Names>
        <String>Jordi</String>
        <String>Maria</String>
    </Names>
</SerializationTest>

public class SerializationTest
{
    // A collection of strings with a custom name for the elements
    [ItemProperty ("ExtraNames")]
    [ItemProperty ("Name", Scope="*")]
    List<string> extraNames = new List<string> ();

    // This property will be serialized as a collection of strings.
    // The element name will be "Objects" (instead of "array"),
    // and there will be an "Id" element for each item of the list.
    // Also, the ValueType property is set to tell the serializer
    // that the elements of the collection are strings.
    [ItemProperty ("Objects")]
    [ItemProperty ("Id", Scope="*", ValueType=typeof(string))]
    ArrayList array = new ArrayList ();

    public SerializationTest ()
    {
        extraNames.Add ("Jordi");
        extraNames.Add ("Maria");
        array.Add ("Jordi3");
        array.Add ("Maria3");
    }
}

<SerializationTest>
    <ExtraNames>
        <Name>Jordi</Name>
        <Name>Maria</Name>
    </ExtraNames>
    <Objects>
        <Id>Jordi3</Id>
        <Id>Maria3</Id>
    </Objects>
</SerializationTest>

public class SerializationTest
{
    // When using nested collections, the scope can be aggregated
    [ItemProperty ("User", Scope="*")]
    [ItemProperty ("Name", Scope="*/*")]
    List<List<string>> nestedNames = new List<List<string>> ();

    public SerializationTest ()
    {
        List<string> nested1 = new List<string> ();
        nested1.Add ("Jordi1");
        nested1.Add ("Maria1");
        nestedNames.Add (nested1);
        List<string> nested2 = new List<string> ();
        nested2.Add ("Jordi2");
        nested2.Add ("Maria2");
        nestedNames.Add (nested2);
    }
}

<SerializationTest>
    <nestedNames>
        <User>
            <Name>Jordi1</Name>
            <Name>Maria1</Name>
        </User>
        <User>
            <Name>Jordi2</Name>
            <Name>Maria2</Name>
        </User>
    </nestedNames>
</SerializationTest>

public class SerializationTest
{
    [ItemProperty]
    int SomeInteger = 32;

    // This property will be serialized as a set of Value elements
    // There won't be a "values" root element.
    [ItemProperty ("Value")]
    [ExpandedCollection]
    string[] values;

    public SerializationTest ()
    {
        values = new string[] { "One", "Two" };
    }
}

<SerializationTest SomeInteger="32">
    <Value>One</Value>
    <Value>Two</Value>
</SerializationTest>

Serializing Dictionaries

The serializer can serialize objects implementing the IDicionary interface. Dictionaries are serialized as a DataItem node which has a list of dictionary entries as children. Each dictionary entry is also a DataItem (named Item by default) which has two child items: the Key item, which holds the key of the entry, and the Value item, which holds the value of the entry.

The scopes 'item', 'key' and 'value' can be used to customize the serialization of the corresponding elements.

Some examples:

public class SerializationTest
{
    // A simple dictionary, with no customizations
    [ItemProperty]
    Dictionary<string,int> data = new Dictionary<string,int> ();
    // A dictionary containing objects, using custom names
    // for the items, keys and values
    [ItemProperty ("Users")]
    [ItemProperty ("User", Scope="item")]
    [ItemProperty ("Id", Scope="key")]
    [ItemProperty ("Data", Scope="value")]
    Dictionary<string,User> userData = new Dictionary<string,User> ();

    public SerializationTest ()
    {
        data ["One"] = 1;
        data ["Two"] = 2;
        userData ["jd"] = new User ("Jordi", "jordi@here.com");
        userData ["ma"] = new User ("Maria", "maria@here.com");
    }
}

public class User
{
    [ItemProperty ("Name")]
    string name;
    [ItemProperty ("EMail")]
    string email;

    public User (string name, string email) { ... }
}

<SerializationTest>
    <data>
        <Item Key="One" value="1" />
        <Item Key="Two" value="2" />
    </data>
    <Users>
        <User Id="jd">
            <Data Name="Jordi" EMail="jordi@here.com" />
        </User>
        <User Id="maria">
            <Data Name="Maria" EMail="maria@here.com" />
        </User>
    </data>
</SerializationTest>