Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 22:56:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
bcquality/custom/knowledge/ui/page-background-tasks.md
Michael Dieringer d4e351f333 Adopt 11 community rules into custom always-on layer 
Promotes rules that are already published in community/ to custom/knowledge/,
so they load at every session start instead of only on keyword relevance.
Each file carries extends: pointing back to its community source.

Passed Immanuel's four-test Categorical Imperative validation on 2026-08-07.
2026-08-07 08:04:12 +02:00

2.5 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area extends
all
ui
enqueuebackgroundtask
async-calculation
child-session
factbox
cue-tile
onaftergetcurrrecord
responsive-page
read-only
al
w1
all
community/ui/page-background-tasks.md

Offload Slow Read-Only Page Calculations To Background Tasks

Contributions welcome — open a PR to refine or extend this article.

Description

Pages that compute statistics, aggregates, or external lookups inline block the page from rendering until the calculation finishes, producing a visible freeze on FactBoxes, cue tiles, and calculated fields. Business Central provides page background tasks: CurrPage.EnqueueBackgroundTask runs a dedicated codeunit in a read-only child session and returns values via OnPageBackgroundTaskCompleted, so the page opens immediately and fills in computed values as they arrive. This matters because users should never wait on a calculation they may not need. The mechanism has specific rules that are easy to get wrong, which is why it warrants an explicit pattern.

Best Practice

Move any noticeable read-only computation off the synchronous render path into a background task. Enqueue from OnAfterGetCurrRecord so the task is tied to the currently focused record, and pass small payloads through the Dictionary of [Text, Text] input/output, converting types with Format and Evaluate. Keep each task focused on one value or a small related set rather than one large task, and show a placeholder until results land. Because tasks auto-cancel when the page closes, the record changes, or a same-ID task is re-enqueued, always supply sensible defaults and handle the timeout path in OnPageBackgroundTaskError — never let critical functionality depend on completion. For tests, drive the task synchronously with RunPageBackgroundTask.

Anti Pattern

Enqueuing from OnAfterGetRecord on a list page fires the task for every row, and each cancels the instant the selection moves to the next row — pure wasted child-session churn; a reviewer spots EnqueueBackgroundTask called from OnAfterGetRecord (or from OnOpenPage, where the record context is not yet stable). The other tell is a task codeunit attempting a database write or Modify: background tasks run read-only and the write fails at runtime. Inline heavy calculation directly in OnAfterGetCurrRecord with no task at all is the baseline smell — it reintroduces the page freeze the feature exists to remove.