Quick guide: HeuristicLab persistence

In HeuristicLab 3.3.16 the persistence has been changed. Instead of using the previous XML-based serialization and deserialization a new binary format is used based on protocol buffers. The persistence is now also open sourced as a standalone project: ​HEAL.Attic.

HeuristicLab 3.3.16 supports loading files in the XML format, but stores those in the new format when saved. Thus, it can be used to convert files from the old format to the new format. In order to use the new conversion you have to adapt any new types that you introduced to the new 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 [StorableType("<INSERT GUID>")] attribute to a new class, interface, and enum.
• 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.

[StorableType("00000000-0000-0000-0000-000000000000")]
public class SomeClass : Item {
  [Storable]
  private int field;

  [StorableConstructor]
  protected SomeClass(StorableConstructorFlag _) : base(_) { }
  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.

[StorableType("00000000-0000-0000-0000-000000000000")]
public class SomeClass {
  ...

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

For further information you are refered to the ​documentation of HEAL.Attic.