Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-06 09:26:52 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/ui/prefer-actionref-syntax-for-promoted-actions.md
Jesper Schulz-Wedde c9d90ac605 Promote validated community knowledge 
Move eight net-new rules into the Microsoft layer, remove six overlapping articles, and update review skill discovery and references.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0b130227-d418-4bc0-9e7d-ec6a37adf039
2026-07-14 14:14:07 +02:00

2 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
21..
ui
actionref
promoted-actions
area-promoted
promotedcategory
promotedonly
action-bar
legacy-syntax
al
w1
all

Promote Actions With The Modern actionref Syntax, Never The Legacy Promoted Properties

Description

Business Central 2022 release wave 2 (v21) introduced the area(Promoted) block with actionref as the way to promote page actions, separating an action's definition from its promotion. The older approach set Promoted, PromotedCategory, PromotedOnly, and PromotedIsBig directly on each action. The two syntaxes cannot be mixed within a single page or page extension, and choosing the legacy one entangles definition with presentation, making the action bar harder to maintain and to extend.

Best Practice

For new pages and page extensions, define actions in their normal area, then promote selected ones with actionref inside area(Promoted), grouping them under explicit categories such as Category_Process and entity-named groups. This keeps each action defined once and referenced where it should appear, supports split buttons via ShowAs, and lets an extension promote a base action without redefining it. When extending a page, you may use modern syntax even if the base page used legacy properties (and vice versa) — the no-mixing rule is per-object, not per-dependency-tree.

Anti Pattern

Setting Promoted = true (with PromotedCategory, PromotedOnly, or PromotedIsBig) on actions in new code, or attempting to combine those properties with an area(Promoted) block in the same object — the latter fails to compile. The reviewer signal is any Promoted-prefixed property on an action in a newly authored page or page extension; flag it and convert to actionref (VS Code offers an automated conversion). Note separately that once an action is promoted in a published app, removing the promotion is a breaking change (AS0031/AW0013), so promote conservatively rather than walking it back later.