State Persistence in WPF Docking (DockingManager)

31 Mar 20237 minutes to read

State persistence is the combined process of serialization and deserialization.

DockingManager provides built-in state persistence functionality to save and load at different states and sides. It also provides DeleteDockState and ResetState Method to work on state functionality.

To reset the DockingManager state, call ResetState method of DockingManager instance.

NOTE

DockingManager serializes and de-serializes the controls using Name property. So, ensure to set Name property for all child controls. The name of children in saved layout should be same as the name of children in DockingManager to load the saved layout. LoadDockState returns true or false to notify whether de-serialization process has been successful.

DockingManager1.ResetState();
DockingManager1.ResetState()

To delete the DockState of the DockingManager, call DeleteDockState of DockingManager instance

DockingManager1.DeleteDockState();
DockingManager1.DeleteDockState()

Auto Save / Load functionalities

DockingManager supports AutoSave support, that allows to persist its state automatically. To enable this functionality, set the PersistState property as True. The default value of the PersistState property is False. It saves the state of the DockingManager in an isolated storage format while WindowClosing.

DockingManager1.PersistState = true;
DockingManager1.PersistState = True

To load the AutoPersist state of the DockingManager, call the LoadDockState method of the DockingManager in its loaded event.

void DockingManager1_Loaded(object sender, RoutedEventArgs e)
{
	DockingManager1.LoadDockState();
}
Private Sub DockingManager1_Loaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
	DockingManager1.LoadDockState()
End Sub

Manipulating Save / Load functionalities

Serialize a complex layout

DockingManager allows to save a complex layout also. For example, it also saves the complex layout like Nested DockingManager.

Serialize the dynamically added children

By default, DockingManager cannot de-serialize its Saved Layout properly, when its child collection is modified after DockState is saved.

Since the DockingManager state persistence feature implemented in such a way that the DockingManager matches the child collection of saved layout with current DockingManager layout internally and loads properly when DockingManager children collection remains same, so when any child collection changes dynamically, it results in an improper layout.

Notification for load DockState

When the children collection of DockingManager is changed dynamically after persisting the layout, incorrect layout may load. Success of loading of persisted state can be decided by return value of LoadDockState method. When the child count is same and then DockingManager checks the Name of the child in the collection. if the Name of the child in loaded state is different from the persisted child in the collection, DockingManager fails to load the saved layout. In such cases, false value will be returned by the LoadDockState method of DockingManager.

Various formats to Save / Load states

DockingManager allows to save and load the DockStates of windows in DockingManager in different format.

Some of the formats are:

  • IsolatedStorage
  • BinaryFormat
  • XML file
  • XmlWriter

Load and save the DockState using Isolated Storage:

DockingManager allows to save and load the dock state from isolated storage.

// Shows the Isolated storage format.

DockingManager1.LoadDockState();

DockingManager1.SaveDockState();

DockingManager1.ResetState();
' Shows the Isolated storage format.

DockingManager1.LoadDockState()

DockingManager1.SaveDockState()

DockingManager1.ResetState()

Save and Load using XML file

DockingManager allows to save and load the XML file. It is done using binary formatter and soap formatter. The code example is below:

//Shows serialization methods using XML file.

BinaryFormatter formatter =  new BinaryFormatter();

DockingManager1.LoadDockState(formatter, StorageFormat.Xml, "\\docking_xml.xml");

BinaryFormatter formatter =  new BinaryFormatter();

DockingManager1.SaveDockState(formatter, StorageFormat.Xml, "\\docking_xml.xml");

SoapFormatter formatter1 = new SoapFormatter();

DocContainer.SaveDockState(formatter1, StorageFormat.Xml, "\\docking_xml_soap.xml"); 

SoapFormatter formatter1 = new SoapFormatter();

DocContainer.SaveDockState(formatter1, StorageFormat.Xml, "\\docking_xml_soap.xml");
'Shows serialization methods using XML file.

Dim formatter As New BinaryFormatter()

DockingManager1.LoadDockState(formatter, StorageFormat.Xml, "\docking_xml.xml")

Dim formatter As New BinaryFormatter()

DockingManager1.SaveDockState(formatter, StorageFormat.Xml, "\docking_xml.xml")

Dim formatter1 As New SoapFormatter()

DocContainer.SaveDockState(formatter1, StorageFormat.Xml, "\docking_xml_soap.xml")

Dim formatter1 As New SoapFormatter()

DocContainer.SaveDockState(formatter1, StorageFormat.Xml, "\docking_xml_soap.xml")

Save and Load using Binary

DockingManager allows to load and save the dock state in the binary format file.

//Shows the load and save dock state in binary formatter.

BinaryFormatter format = new BinaryFormatter();

DockingManager1.LoadDockState(format, StorageFormat.Binary, "\\docking_bin.bin");

BinaryFormatter format = new BinaryFormatter();

DockingManager1.SaveDockState(format, StorageFormat.Binary, "\\docking_bin.bin");
'Shows the load and save dock state in binary formatter.

BinaryFormatter format = new BinaryFormatter()

DockingManager1.LoadDockState(format, StorageFormat.Binary, "\docking_bin.bin")

BinaryFormatter format = new BinaryFormatter()

DockingManager1.SaveDockState(format, StorageFormat.Binary, "\docking_bin.bin")

Save and Load using XmlWriter

DockingManager allows to load and save the DockState using XMLWriter.

//Shows the SaveDockState method using XmlWriter.

XmlWriter writer = XmlWriter.Create("DockStates.xml");          

DockingManager.SaveDockState(writer);  

writer.Close()


//Shows the LoadDockState method using XmlWriter

XmlReader reader = XmlReader.Create("DockStates.xml");

DockingManager.LoadDockState(reader);     
       
reader.Close();
'Shows the SaveDockState method using XmlWriter.

Dim writer As XmlWriter = XmlWriter.Create("DockStates.xml")

DockingManager.SaveDockState(writer)

writer.Close() XmlReader reader = XmlReader.Create("DockStates.xml")
'Shows the LoadDockState method using XmlWriter

DockingManager.LoadDockState(reader)

reader.Close()

Restrict state persistence for specific child

The CanSerialize attached property of DockingManager decides whether the child can be serialized or not. The default value of the CanSerialize property is true. When the property is false, while performing deserialization the non-serialized child will move to its default state. This can also be done programmatically by using the SetCanSerialize function of DockingManager.

<syncfusion:DockingManager x:Name="DockingManager1" UseDocumentContainer="True">

<ContentControl syncfusion:DockingManager.Header="Solution Explorer" x:Name="solutionExplorer" syncfusion:DockingManager.SideInDockedMode="Right" syncfusion:DockingManager.CanSerialize="False"/>

<ContentControl syncfusion:DockingManager.Header="Start Page" x:Name="startPage" syncfusion:DockingManager.State="Document" />

<ContentControl syncfusion:DockingManager.Header="Toolbox" x:Name="toolBox" syncfusion:DockingManager.State="AutoHidden"/>

</syncfusion:DockingManager>
DockingManager.SetCanSerialize(solutionExplorer, false);

NOTE

Restrict state persistence does not support to children that were added at run time in DockingManager when performing serialization and de-serialization using XmlWriter.

NOTE

Docking State persistence will be applied to active Docking Children. So it must to load dynamically added controls into DockingManager before applying Deserialization process.

NOTE

The LoadDockState method will return true only when all the children in DockingManager match precisely with the children in the serialized file.