mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-08 10:26: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.5 KiB
Markdown
26 lines
1.5 KiB
Markdown
---
|
|
bc-version: [all]
|
|
domain: events
|
|
keywords: [event-parameters, signature, backward-compatibility, append, onbefore, integration-event, versioning]
|
|
technologies: [al]
|
|
countries: [w1]
|
|
application-area: [all]
|
|
---
|
|
|
|
# Add new event parameters at the end
|
|
|
|
## Description
|
|
|
|
Adding a parameter to an existing event publisher changes its signature. Appending the new parameter at the end of the parameter list keeps the change easy to review and track: existing subscribers still bind to the leading parameters, and the diff is a single clean addition. Inserting a parameter in the middle makes diffs noisy and harder to review, and obscures the history of how the signature evolved. New parameters belong after the existing ones.
|
|
|
|
## Best Practice
|
|
|
|
When extending an existing publisher, append the new parameter after all existing ones, including after a trailing `var IsHandled: Boolean` when present. Subscribers that already match keep working against the leading parameters, and the change stays a one-line addition that is trivial to review.
|
|
|
|
See sample: `add-new-event-parameters-at-the-end.good.al`.
|
|
|
|
## Anti Pattern
|
|
|
|
Inserting a new parameter in the middle of an existing event's signature, shifting the position of every subsequent argument and forcing a careful re-map of all subscribers. Detection: a changed event signature where an added parameter appears before existing parameters rather than at the tail of the list.
|
|
|
|
See sample: `add-new-event-parameters-at-the-end.bad.al`.
|