Asynchronous Data Loading (Windows Forms)

Dec 04, 2025
3 minutes to read

This article describes how to load View data asynchronously in WinForms applications. This capability allows you to keep the UI responsive while the application fetches required data. End users can navigate to another View while the operation is in progress. They can also close the tab before the View loads all data, which would then cancel the data load operation.

Prerequisites

You should use ThreadSafeDataLayer in your application to enable asynchronous data loading. To use this data layer, follow the steps below:

Open the Startup.cs file and locate the AddXpo method.
Set the ThreadSafe option to true.

YourSolutionName.Win\Startup.cs

csharp

builder.ObjectSpaceProviders
    .AddXpo((application, options) => {
        options.ConnectionString = connectionString;
        options.ThreadSafe = true;
    })
    // ...

You can enable this feature for Views that fit all the conditions below.

List View

Detail View

| | --- | --- | |

IModelListView.EditorType = GridListEditor,
PivotGridListEditor, or ChartListEditor
IModelListView.DataAccessMode = Client
View.IsRoot = true
displays persistent objects

DetailView.UseAsyncLoading = true
View.IsRoot = true
displays a persistent object

Enable Asynchronous Loading

Set the UseAsyncLoading property to true. The following Model Editor nodes allow you to specify this property for supported Views:

Navigate to the Options node to enable this feature for all Views in your application. The value you specified in this node is the default for UseAsyncLoading in the View-specific nodes.
Navigate to the Views | <ListView> node to enable this feature for a specific List View.
Navigate to the Views | <DetailView> node to enable this feature for a Detail View.

Important Notes

Detail Views

Detail Views always load associated collections in the main thread. These operations lock the UI. If you enable the UseAsyncLoading option, the View loads only its current object asynchronously. In other words, this option only helps you resolve high load times for the current object (for example, when this object has properties with complex logic or you use a remote database).

If DetailView.UseAsyncLoading is set to true , note the following:

when IModelAsync.UseAsyncLoading is true , the DetailView.CurrentObject property is set to null in the Controller.OnActivate method;
when you open a Detail View from the Navigation, the DetailViewCreatingEventArgs.Obj argument of the ViewCreating and DetailViewCreating events is set to null;
when you open a Detail View from a List View (by double-clicking a record or using the OpenObject Action), the DetailViewCreatingEventArgs.Obj argument of the ViewCreating and DetailViewCreating events is set to the object from the List View’s Object Space;
when IModelAsync.UseAsyncLoading is true and you use DetailView.ObjectSpace before the Detail View’s object is initialized (for example, in Controller.OnActivated ), an exception occurs. Move the logic that depends on this property to the CurrentObjectChanged handler.

List Views

If you enable the UseAsyncLoading option, do not manipulate a List View’s IObjectSpace until all data is loaded.