mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-08 02:16:52 +01:00
0ad92cad86
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>
26 lines
1.6 KiB
Markdown
26 lines
1.6 KiB
Markdown
---
|
|
bc-version: [all]
|
|
domain: events
|
|
keywords: [ishandled, semantic-change, event-contract, backward-compatibility, onbefore, integration-event, subscribers]
|
|
technologies: [al]
|
|
countries: [w1]
|
|
application-area: [all]
|
|
---
|
|
|
|
# Do not add IsHandled to an existing event
|
|
|
|
## Description
|
|
|
|
Adding a `var IsHandled: Boolean` parameter to an event that already shipped without one silently changes the event's purpose — from a plain notification into an overridable seam. Existing subscribers were written against a "notify" contract they never agreed to make skippable, so their behaviour can quietly become wrong or pointless. The safe move is to leave the existing event untouched and introduce a new `OnBefore…` event carrying `IsHandled` at the point you want to make overridable. Existing subscribers keep working against the original event; new subscribers opt into the override seam through the new one.
|
|
|
|
## Best Practice
|
|
|
|
Keep the existing event as-is and add a separate `OnBeforeX(…; var IsHandled: Boolean)` before the logic you want to make overridable. Two events with distinct, stable contracts are safer than one event whose meaning and signature were changed under its subscribers.
|
|
|
|
See sample: `do-not-add-ishandled-to-an-existing-event.good.al`.
|
|
|
|
## Anti Pattern
|
|
|
|
Mutating a shipped event — for example adding `var IsHandled` to `OnAfterCalculateTotal` — to retrofit override behaviour, which overloads the event's meaning and undermines existing subscribers. Detection: an `IsHandled` parameter added to a pre-existing event signature rather than introduced through a new dedicated `OnBefore` publisher.
|
|
|
|
See sample: `do-not-add-ishandled-to-an-existing-event.bad.al`.
|