= 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: [https://github.com/heal-research/HEAL.Attic 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.

{{{
#!csharp
[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.

{{{
#!csharp
[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 [https://github.com/heal-research/HEAL.Attic/tree/master/docs documentation of HEAL.Attic].