D365FO – AX – X++ –Refresh, Reread, Research, and ExecuteQuery

 D365FO – AX – X++ – Tutorial: Choosing Between Refresh, Reread, Research, and ExecuteQuery

X++ developers often face challenges with the four datasource methods—refresh, reread, research, and executeQuery—in Dynamics 365 Finance and Operations (D365FO). Regardless of their seniority in AX, developers frequently make mistakes in the sequence of calling these methods. To address this, I've created a brief hands-on tutorial illustrating the typical use cases for each method. I've organized the methods based on their impact on the displayed grid rows.

1. Common Mistakes:

Developers often incorrectly call two of these methods in the following order:

- formDataSource.refresh() followed by formDataSource.research(), or

- formDataSource.reread() followed by formDataSource.research(), or

- formDataSource.research() followed by formDataSource.executeQuery(), or

- formDataSource.research() followed by formDataSource.refresh() / formDataSource.reread().

These sequences are either entirely wrong or, at the very least, partially redundant. I aim to clarify the reasons behind these issues in the full post. If any of them remain unclear after reading, please leave a comment, and I'll provide additional explanations.

2. Refresh:

The refresh() method updates the data displayed in the form controls with what is stored in the form cache for that specific datasource record. It does not reread the record from the database, so changes from another process will not be reflected after calling refresh().

- refreshEx: This method redraws grid rows based on an optional argument specifying the record number to refresh. Use it sparingly, especially when multiple rows are updated, resulting in changes in display options. Note that refreshEx() only redraws the grid, leaving controls outside the grid with potentially outdated values.

3. Reread:

Calling reread() queries the database, reloading the current record into the datasource form cache. Changes won't be displayed until a grid redraw occurs (e.g., navigating away from the row or reopening the form). Avoid using reread() to refresh form data when adding or removing records through code.

- SaveRecord Property: Buttons with SaveRecord set to Yes save changes to the database. Calling reread will not restore the original record values; set SaveRecord to No if that behavior is expected.

4. Research:

The research() method reruns the existing form query against the database, updating the list with new/removed records and updating existing rows based on user-set filters and sorting.

- Research(true): Starting from AX 2009, research(true) retains cursor position in the grid after data refresh, solving cursor positioning problems.

5. ExecuteQuery:

Calling executeQuery() reruns the query, updating/adding/deleting rows in the grid. Unlike research, executeQuery uses the original query as the basis, removing any user filters.

- formDataSource.queryRun().query() vs formDataSource.query(): Understand the distinction between the original datasource query (formDataSource.query()) and the current query with user filters (formDataSource.queryRun().query()). When using research/executeQuery, prevent collisions with user filters by recognizing which query instance to utilize.