WPF Dock Layout Manager – Upgrade the Application Layout Between Versions

When you change the application layout (for example, adding new panels, enabling MDI mode, or rearranging groups) previously saved layouts may become outdated or incompatible. This example saves and restores layouts while supporting structural changes across different versions of the application.

Use this example to:

• Detect the version of the layout being restored.
• Apply upgrade logic to adjust the layout for both DockLayoutManager and nested controls like GridControl.
• Preserve backward compatibility while keeping layouts aligned with the current application structure.

Implementation Details

Version Management

The DXSerializer.LayoutVersion property specifies the version of the current layout. In this example, the ComboBoxEdit control allows the user to change the current layout version:

<dxe:ComboBoxEdit EditValue="{Binding ElementName=dockLayoutManager, Path=(dx:DXSerializer.LayoutVersion)}">
    <sys:String>1.0</sys:String>
    <sys:String>2.0</sys:String>
</dxe:ComboBoxEdit>

Save and Restore Layouts

Use the WorkspaceManager component to save the application layout to an XML file and restore it when needed:

manager.CaptureWorkspace("TestWorkspace");
manager.SaveWorkspace("TestWorkspace", layoutPath);
manager.LoadWorkspace("TestWorkspace", layoutPath);
manager.ApplyWorkspace("TestWorkspace");

Upgrade Logic

When a layout from an older version is restored, the GridControl and DockLayoutManager raise the DXSerializer.LayoutUpgrade event to apply custom upgrade logic and adapt the layout to the current version of the application.

• For the DockLayoutManager, the handler switches the MDI style if the layout version is "1.0":

void OnDockLayoutManagerLayoutUpgrade(object sender, LayoutUpgradeEventArgs e) {
    if (e.RestoredVersion == "1.0") {
        documentGroup1.MDIStyle = MDIStyle.MDI;
    }
}

• For the GridControl, the handler applies grouping based on the restored version:

void OnGridControlLayoutUpgrade(object sender, LayoutUpgradeEventArgs e) {
    if (e.RestoredVersion == "1.0") {
        ((GridControl)sender).GroupBy("Group");
    }
}

This logic ensures that older layouts can be upgraded to match the latest application structure and behavior.

Files to Review

• MainWindow.xaml (VB: MainWindow.xaml)
• MainWindow.xaml.cs (VB: MainWindow.xaml.vb)

Documentation

• DockLayoutManager
• Layout Management
• DXSerializer.LayoutVersion
• DXSerializer.LayoutUpgradeEvent
• Save/Restore Control Layout

More Examples

• WPF Dock Layout Manager – Move a Layout Item in Code
• WPF Dock Layout Manager – Serialize Custom Panels and Their Properties
• WPF Dock Layout Manager – Serialize DockLayoutManager When You Use the TabbedDocumentUIService
• WPF Dock Layout Manager – Populate a LayoutGroup with ViewModel Collection
• WPF Dock Layout Manager – Bind the View Model Collection with LayoutAdapters

Does this example address your development requirements/objectives?

(you will be redirected to DevExpress.com to submit your response)