Quick guide: HeuristicLab persistence

Invocation

If you want to save to a file you are advised to use the ContentManager static class of the HeuristicLab.Common namespace. A concrete content manager is set when the MainForm is initializing, by default this is the PersistenceContentManager in HeuristicLab.Core.

The HeuristicLab persistence can be used directly in case the output should be a stream. Use the classes XmlGenerator and XmlParser in the HeuristicLab.Persistence.Default.Xml namespace to transform an object graph into XML and read it back again.

Custom Classes

Content types that should be saved and restored have to be decorated with attributes.

• Add the [StorableClass] attribute to a new class
• Add the [Storable] attribute to any fields or properties you would like to be persisted
• If the default constructor takes longer to initialize, persistence can be directed to use a different constructor by decorating it with the [StorableConstructor] attribute. This constructor has to have a single boolean parameter which will be set to true.

[Storable]
public class SomeClass : Item {
  [StorableConstructor]
  protected SomeClass(bool deserializing) : base(deserializing) { }
  public SomeClass() {
    // a lot of initialization code that should be skipped during deserialization
  }
}

If you need more control you can add a [StorableHook] attribute to a parameterless method that will be called after deserialization finishes or before serialization starts.

[StorableClass]
public class SomeClass {
  [StorableHook(HookType.AfterDeserialization)]
  private void AfterDeserialization() {
    // backwards-compatible code (loading files stored with previous versions)
    // register event handlers
  }
}

Support for Other Classes

• An IPrimitiveSerializer directly transforms an object and its components into serialized form. This is mainly used for primitive types such as int or float.
• An ICompositeSerializer does not directly transform an object into serialized form but decomposes it into other objects that can then be used to recompose the same object.

Other Formats

You can use the core persistence components to generate other formats. This is done through a stream of serialization tokens. The Serializer and Deserializer use classes of type ISerializationToken to talk to the back end. They describes a hierarchical format of composites that can contain other composites, primitives or references. Additionally, type information is conveyed in type information tokens.