mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-08 02:16:52 +01:00
faeacb2484
Add 12 atomic knowledge articles under microsoft/knowledge/events covering general AL event-design best practices: IsHandled initialization and OnAfter preservation, appending new event parameters, position-based event naming, reusing/extending events, avoiding per-iteration publishing, Temp-prefixing temporary record parameters, unabbreviated parameter names, preferring the this keyword over IncludeSender, avoiding loosely typed parameters, not mutating existing event contracts, and not bypassing critical operations with IsHandled. Each article ships a .good.al and .bad.al demonstration sample (object IDs 50240-50296; not compiled by CI). Extend the al-events-review leaf Worklist with one targeted check per new rule. Additive only; no contract or wiring change (events leaf already wired). 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: [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, and every subscriber must be updated to match. Appending the new parameter at the end of the parameter list keeps the change easy to review and minimizes churn: existing subscribers still bind to the leading parameters, and the diff is a single clean addition. Inserting a parameter in the middle shifts every following argument, makes diffs noisy, and is error-prone to reconcile across many subscribers — a subscriber that compiles can still receive the wrong values because positions moved. 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`.
|