Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-06 17:36:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/events/initialize-ishandled-to-false-before-publishing.md
Jesper Schulz-Wedde 0ad92cad86 Refine events articles after review feedback 
Correct wording in five events articles to reflect that AL event
subscribers bind by parameter name, not position:

- add-new-event-parameters-at-the-end: drop the inaccurate claim that
  appending a parameter forces subscribers to be updated or causes wrong
  values; keep the append-at-end best practice.
- do-not-add-ishandled-to-an-existing-event: reframe from "breaking
  change" to the semantic/purpose shift that leaves existing subscribers
  pointless; rename the breaking-change keyword to semantic-change.
- name-events-by-publisher-position: extend the good sample with
  position-named publishers raised from table and report trigger
  contexts.
- initialize-ishandled-to-false-before-publishing: scope the detection
  and best practice to events that actually carry a var IsHandled, so an
  OnBefore with no IsHandled is not flagged.
- do-not-bypass-critical-operations-with-ishandled: add a litmus-test
  definition of a critical operation (code that cannot stand as an
  independent, self-contained unit).

Knowledge-only; no contract or wiring change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-25 11:59:00 +02:00

2 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
events
ishandled
initialization
deterministic
onbefore
reset
integration-event
control-flow
al
w1
all

Initialize IsHandled to false before publishing

Description

A routine that raises an OnBefore… integration event with a var IsHandled: Boolean parameter passes that variable in by reference, so its incoming value decides whether the default logic is skipped. A freshly declared Boolean starts as false, but the same variable is frequently reused to raise several events in one routine, and after the first raise it may already be true. Assigning IsHandled := false; on the line immediately before every raise makes the control flow deterministic and self-documenting, and prevents a stale true from silently suppressing logic the author never meant to make skippable. Generated code often reuses one IsHandled across several raises without resetting it.

Best Practice

Set IsHandled := false; immediately before each OnBeforeX(…, IsHandled) raise, then guard the default logic with if IsHandled then exit; or if not IsHandled then …. Do this even when the variable was just declared: the explicit reset documents intent and stays correct if a second event raise is added to the routine later. This applies only to events that carry a var IsHandled: Boolean; an OnBefore event with no IsHandled parameter needs no reset.

See sample: initialize-ishandled-to-false-before-publishing.good.al.

Anti Pattern

Raising OnBeforeX(…, IsHandled) with a variable whose value carries over from an earlier raise, so a subscriber that handled the first event unintentionally suppresses the second routine's default logic. Detection: an IsHandled variable passed to more than one event in a routine without an intervening IsHandled := false;, or any OnBefore… raise that passes an IsHandled variable without an intervening IsHandled := false;.

See sample: initialize-ishandled-to-false-before-publishing.bad.al.