From daa85f20e33070a9e89a92593b9d92c3a7191429 Mon Sep 17 00:00:00 2001 From: Kilian Seizinger <56249171+pri-kise@users.noreply.github.com> Date: Fri, 2 Oct 2026 14:30:51 +0200 Subject: [PATCH 1/2] knowledge(error-handling): a bare [TryFunction] call propagates its error The review agent repeatedly flagged bare calls to [TryFunction] procedures (e.g. the System Application "Xml Validation" Try* APIs) as defects, including claims that the failure is "silently swallowed". A bare call is an ordinary call: the error propagates as usual. - Add negative knowledge bare-tryfunction-call-propagates-errors.md. - Narrow ignored-tryfunction-return-disables-try-semantics to code that visibly expects the failure to be caught; the bad sample now shows that in code, and the good sample includes an intentional bare call as the clean control. - Qualify "TryFunction catches all errors" in the events article and the "must be consumed" wording in the performance article. - Error-handling leaf worklists both articles for bare [TryFunction] calls and requires the same evidence before flagging. - Add the three paired articles to the evaluation overrides. --- evaluation/review-fixtures.json | 9 ++++-- ...bare-tryfunction-call-propagates-errors.md | 31 +++++++++++++++++++ ...ction-return-disables-try-semantics.bad.al | 8 +++-- ...tion-return-disables-try-semantics.good.al | 13 ++++++-- ...yfunction-return-disables-try-semantics.md | 18 ++++++++--- ...oid-raising-events-inside-try-functions.md | 2 +- ...unction-for-error-catching-not-rollback.md | 2 +- .../skills/review/al-error-handling-review.md | 5 +-- 8 files changed, 71 insertions(+), 17 deletions(-) create mode 100644 microsoft/knowledge/error-handling/bare-tryfunction-call-propagates-errors.md diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index e3a6069d..5636506b 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -68,7 +68,8 @@ "collect-validation-errors-with-errorbehavior", "declined-confirm-must-abort-not-partially-apply", "defensive-vs-offensive-code-must-match-blast-radius", - "log-writes-must-survive-rollback" + "log-writes-must-survive-rollback", + "ignored-tryfunction-return-disables-try-semantics" ] }, "events": { @@ -77,7 +78,8 @@ "changecompany-runs-triggers-in-the-calling-company", "database-trigger-setup-flags-may-only-be-set-to-true", "isolated-events-are-isolated-only-outside-a-write-transaction", - "isolated-event-rollback-does-not-undo-var-parameters" + "isolated-event-rollback-does-not-undo-var-parameters", + "avoid-raising-events-inside-try-functions" ] }, "finance": { @@ -128,7 +130,8 @@ "al-methods-limited-during-write-transactions", "avoid-user-prompts-inside-transactions", "use-grouped-query-for-distinct-values-and-duplicates", - "compute-role-center-headlines-in-the-background" + "compute-role-center-headlines-in-the-background", + "use-tryfunction-for-error-catching-not-rollback" ] }, "privacy": { diff --git a/microsoft/knowledge/error-handling/bare-tryfunction-call-propagates-errors.md b/microsoft/knowledge/error-handling/bare-tryfunction-call-propagates-errors.md new file mode 100644 index 00000000..a9cf99a4 --- /dev/null +++ b/microsoft/knowledge/error-handling/bare-tryfunction-call-propagates-errors.md @@ -0,0 +1,31 @@ +--- +bc-version: [all] +domain: error-handling +keywords: [tryfunction, try-method, bare-call, error-propagation, swallowed-error, try-prefix, false-positive] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# A bare call to a [TryFunction] propagates its error; it is not a swallowed failure + +## Description + +A bare call to a `[TryFunction]` procedure propagates errors like any ordinary method call. When the caller ignores the Boolean result, the platform does not treat the invocation as a try-method call: an error raised inside it stops the caller exactly as an unattributed procedure would, and nothing is caught or converted to `false`. Calling a try-API this way — for example the System Application `Xml Validation` procedures `TrySetValidatedDocument`, `TryAddValidationSchema`, and `TryValidateAgainstSchema` — is therefore a legitimate way to let a validation error reach the user. Reviewers who know only that try methods "catch errors" misread such a call as a silent failure. + +## Best Practice + +Treat a bare call to a `[TryFunction]` as a throwing call. Do not report that its failure is swallowed, ignored, or invisible to the caller, and do not ask the author to capture the result only to re-raise it: when the error should propagate, the bare call already does so and keeps the original error text, code, and call stack. Recommend consuming the result only when the surrounding code visibly expects to continue past or handle the failure; that case is owned by `microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.md`. + +A `Try` name prefix is a convention, not a semantic. Resolve the called procedure's declaration before reasoning about its error behaviour. A `Try`-named procedure without `[TryFunction]` is an ordinary Boolean method; whether ignoring its result loses a failure depends on its body, not on its name. + +## Anti Pattern + +Review findings that flag a bare `[TryFunction]` call whose surrounding code and documentation intend the error to propagate, for example: "the Try-prefixed calls ignore their Boolean return value, so a parse or validation failure is silently swallowed", "the caller can never learn whether validation succeeded", or "the try semantics never activate, so errors escape as ordinary exceptions". The first two claims are false; the third describes the intended behaviour, not a defect. + +Recommending `if not Try...() then Error(GetLastErrorText())` as the fix is part of the same false positive. It adds code, replaces the original error with a re-raised copy, and can move unsanitized customer content into the error message (see `microsoft/knowledge/privacy/getlasterrortext-customer-content-in-errors.md`). + +## References + +- [Handling errors using try methods](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-handling-errors-using-try-methods): "If a try method call doesn't use the return value, the try method operates like an ordinary method, and errors are exposed as usual." +- [System Application `Xml Validation` codeunit](https://github.com/microsoft/BCApps/blob/main/src/System%20Application/App/XML%20Validation/src/XmlValidation.Codeunit.al): every `Try*` procedure is declared `[TryFunction]`. diff --git a/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.bad.al b/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.bad.al index 8d6df99e..edc8b8a0 100644 --- a/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.bad.al +++ b/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.bad.al @@ -1,9 +1,13 @@ codeunit 50301 "Try Return Bad" { - procedure ImportDocument() + procedure ImportDocument(): Boolean begin - // Ignoring the Boolean result makes this an ordinary, throwing call. + // The bare call is not a try-method call: the error stops this procedure here, + // so the check below never sees it. TryImportDocument(); + if GetLastErrorText() <> '' then + exit(false); + exit(true); end; [TryFunction] diff --git a/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.good.al b/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.good.al index d369d279..b5c45a1b 100644 --- a/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.good.al +++ b/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.good.al @@ -1,9 +1,17 @@ codeunit 50300 "Try Return Good" { - procedure ImportDocument() + procedure ImportDocument(): Boolean begin + // The caller continues on failure, so the result is consumed. if not TryImportDocument() then - Error(ImportFailedErr); + exit(false); + exit(true); + end; + + procedure ImportRequiredDocument() + begin + // The error should reach the user, so a bare call is correct. + TryImportDocument(); end; [TryFunction] @@ -13,6 +21,5 @@ codeunit 50300 "Try Return Good" end; var - ImportFailedErr: Label 'The document could not be imported.'; SourceRejectedErr: Label 'The source document was rejected.'; } diff --git a/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.md b/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.md index 902528bc..1c58e453 100644 --- a/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.md +++ b/microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.md @@ -1,30 +1,38 @@ --- bc-version: [13..] domain: error-handling -keywords: [tryfunction, try-method, boolean-return, ignored-return-value, error-propagation] +keywords: [tryfunction, try-method, boolean-return, ignored-return-value, error-propagation, dead-failure-branch] technologies: [al] countries: [w1] application-area: [all] --- -# Consume a TryFunction return value to enable try semantics +# Consume a TryFunction return value when the caller handles the failure ## Description -A procedure marked `[TryFunction]` catches errors only when the caller uses its Boolean return value. An assignment or conditional makes the invocation a try-method call; a bare call is treated as an ordinary procedure call and exposes errors as usual. The attribute alone does not make every invocation non-throwing. +A `[TryFunction]` catches errors only when the caller uses its Boolean return value. An assignment or conditional makes the invocation a try-method call; a bare call is treated as an ordinary procedure call and exposes errors as usual. The attribute alone does not make every invocation non-throwing, so code that handles the failure of a bare call never sees that failure: the error leaves the procedure before the handling runs. ## Best Practice -Consume the result directly: assign it to a Boolean or use the call in an `if` condition. Handle `false` immediately while the last-error state still describes that failure. +When the caller must continue, log, count, or translate the failure, consume the result directly: assign it to a Boolean or use the call in an `if` condition. Handle `false` immediately while the last-error state still describes that failure. + +When the error should simply propagate, a bare call is correct and needs no change; see `microsoft/knowledge/error-handling/bare-tryfunction-call-propagates-errors.md`. See sample: [`ignored-tryfunction-return-disables-try-semantics.good.al`](ignored-tryfunction-return-disables-try-semantics.good.al). ## Anti Pattern -Calling a `[TryFunction]` procedure as a standalone statement and assuming the attribute suppresses its errors. The call has ordinary error semantics because its Boolean result is ignored. +Calling a `[TryFunction]` procedure as a standalone statement while the surrounding code expects the failure to be caught. Detect it from code, not from the call shape alone: the bare call is followed by a `GetLastErrorText`, `GetLastErrorCode`, or `GetLastErrorObject` check, a failure branch, failure logging, or a `false`/failure result; or it sits in a loop that is meant to continue past failed items. None of that handling sees the call's error, because the error stops the procedure first. + +A bare call with no such handling is intended propagation, not this anti-pattern. See sample: [`ignored-tryfunction-return-disables-try-semantics.bad.al`](ignored-tryfunction-return-disables-try-semantics.bad.al). ## See also `microsoft/knowledge/performance/use-tryfunction-for-error-catching-not-rollback.md` owns transaction rollback expectations after a try method has actually caught an error. + +## References + +- [Handling errors using try methods](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-handling-errors-using-try-methods): "If a try method call uses the return value in an `OK:=` statement or a conditional statement such as `if-then`, errors are caught." diff --git a/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md b/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md index 80b3b344..8b6dd878 100644 --- a/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md +++ b/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md @@ -11,7 +11,7 @@ application-area: [all] ## Description -A `TryFunction` catches all errors — including errors thrown by event subscribers. When an `[IntegrationEvent]` is raised inside a `TryFunction` body, any error a subscriber raises is silently swallowed by the TryFunction's error boundary. The subscriber's logic fails, the caller sees no error, and the calling code continues as if nothing happened. Subscribers have no way to signal failure to the caller. +A `TryFunction` whose caller consumes its Boolean result catches all errors raised during its execution — including errors thrown by event subscribers. When an `[IntegrationEvent]` is raised inside a `TryFunction` body, any error a subscriber raises is silently swallowed by the TryFunction's error boundary. The subscriber's logic fails, the caller sees no error, and the calling code continues as if nothing happened. Subscribers have no way to signal failure to the caller. ## Best Practice diff --git a/microsoft/knowledge/performance/use-tryfunction-for-error-catching-not-rollback.md b/microsoft/knowledge/performance/use-tryfunction-for-error-catching-not-rollback.md index 41f751fb..6d566f2f 100644 --- a/microsoft/knowledge/performance/use-tryfunction-for-error-catching-not-rollback.md +++ b/microsoft/knowledge/performance/use-tryfunction-for-error-catching-not-rollback.md @@ -29,4 +29,4 @@ See sample: [`use-tryfunction-for-error-catching-not-rollback.bad.al`](use-tryfu ## See also -`microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.md` owns the separate call-site rule that a try method's Boolean result must be consumed. +`microsoft/knowledge/error-handling/ignored-tryfunction-return-disables-try-semantics.md` owns the separate call-site rule that only a call that consumes the Boolean result catches errors; `microsoft/knowledge/error-handling/bare-tryfunction-call-propagates-errors.md` records that a bare call propagates them as intended. diff --git a/microsoft/skills/review/al-error-handling-review.md b/microsoft/skills/review/al-error-handling-review.md index 2af0cf42..243774a3 100644 --- a/microsoft/skills/review/al-error-handling-review.md +++ b/microsoft/skills/review/al-error-handling-review.md @@ -48,7 +48,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed procedures and triggers, weighted toward `OnValidate`/`OnInsert`/`OnModify` triggers, posting and validation routines, and procedures attributed with `[ErrorBehavior(...)]` or `[TryFunction]`. - Tokens extracted from the diff that relate to error surfacing and diagnostics (`Error`, `ErrorInfo`, `FieldError`, `TestField`, `Title`, `Message`, `DetailedMessage`, `AddAction`, `AddNavigationAction`, `RecordId`, `PageNo`, `ErrorBehavior`, `Collect`, `HasCollectedErrors`, `GetCollectedErrors`, `ClearCollectedErrors`, `ErrorType`, `Internal`, `Client`, `TryFunction`, `GetLastErrorText`, `Confirm`, `xRec`, Boolean assignment). - For the outbound HTTP call paths identified in Source, include `HttpClient`, `Get`, `Post`, `HttpResponseMessage`, response use, and caller failure handling (including `[TryFunction]` call sites) in keyword and topic matching. -- Resolve changed standalone call targets; when the target declaration has `[TryFunction]`, worklist the ignored-return rule even if the declaration itself is unchanged. Only assignment and conditional use activate try semantics. +- Resolve changed standalone call targets; when the target declaration has `[TryFunction]`, worklist both `ignored-tryfunction-return-disables-try-semantics` and `bare-tryfunction-call-propagates-errors` even if the declaration itself is unchanged. Only assignment and conditional use activate try semantics. A `Try` name prefix does not establish `[TryFunction]`; resolve the declaration. A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -61,7 +61,8 @@ The following targeted checks cover every current `error-handling` article: - Developer-only invariant text is raised with default client visibility, or a user-actionable validation is hidden as `ErrorType::Internal` — `errortype-internal-vs-client-for-diagnostics`. - `FieldError` receives a complete capitalized sentence, repeats the field caption/value, or ends the predicate with punctuation — `fielderror-default-message-logic`. - An unguarded `FieldError` is used as though it performed a comparison, or `TestField` is forced onto a complex rule needing a tailored predicate — `fielderror-vs-testfield`. -- A resolved call target is marked `[TryFunction]` but the call is a standalone statement whose Boolean result is ignored — `ignored-tryfunction-return-disables-try-semantics`. This call-site rule supersedes the performance TryFunction article unless writes and rollback expectations are also visible. +- A resolved call target is marked `[TryFunction]`, the call is a standalone statement whose Boolean result is ignored, and the surrounding code expects the failure to be caught (a later last-error check, failure branch or result, or a loop meant to continue past failures) — `ignored-tryfunction-return-disables-try-semantics`. This call-site rule supersedes the performance TryFunction article unless writes and rollback expectations are also visible. +- A bare `[TryFunction]` call without such handling is intended propagation — `bare-tryfunction-call-propagates-errors`. It suppresses findings, including agent findings, that call the failure swallowed or ask for the result to be captured and re-raised. - A plain `Error` represents a known actionable correction that can be expressed through `ErrorInfo` actions/navigation, or an `ErrorInfo` omits the context needed for that action — `prefer-errorinfo-for-actionable-errors`. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. From 609ef4d7605a88e7c93db23e0180aa5e0a168dd5 Mon Sep 17 00:00:00 2001 From: Kilian Seizinger <56249171+pri-kise@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:48:33 +0100 Subject: [PATCH 2/2] knowledge(events): qualify try-function event rule by consumed-result call sites Address review on #211: the Best Practice and Anti Pattern of avoid-raising-events-inside-try-functions now apply only when a call site consumes the TryFunction's Boolean result. A publisher helper that is only invoked as a bare statement activates no try boundary, so subscriber errors propagate; it is explicitly exempt and the good sample adds it as a clean control. --- ...-raising-events-inside-try-functions.good.al | 17 +++++++++++++++++ ...avoid-raising-events-inside-try-functions.md | 10 +++++++--- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.good.al b/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.good.al index 10f331cf..233caa6c 100644 --- a/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.good.al +++ b/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.good.al @@ -24,6 +24,23 @@ codeunit 50114 "Payment Processor" Error('Payment gateway call failed. Check connectivity and retry.'); end; + procedure ConfirmPayment(PaymentAmount: Decimal) + begin + // Bare call: no try boundary is active, so subscriber errors propagate to the caller. + TryPublishPaymentConfirmed(PaymentAmount); + end; + + [IntegrationEvent(false, false)] + local procedure OnAfterConfirmPayment(PaymentAmount: Decimal) + begin + end; + + [TryFunction] + local procedure TryPublishPaymentConfirmed(PaymentAmount: Decimal) + begin + OnAfterConfirmPayment(PaymentAmount); + end; + [TryFunction] local procedure TryCallPaymentGateway(PaymentAmount: Decimal) var diff --git a/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md b/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md index 8b6dd878..d81d5540 100644 --- a/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md +++ b/microsoft/knowledge/events/avoid-raising-events-inside-try-functions.md @@ -7,7 +7,7 @@ countries: [w1] application-area: [all] --- -# Do not raise integration events inside a TryFunction +# Do not raise integration events inside a TryFunction whose result the caller consumes ## Description @@ -15,12 +15,16 @@ A `TryFunction` whose caller consumes its Boolean result catches all errors rais ## Best Practice -Raise the integration event before entering the TryFunction scope. The event and its subscribers execute outside the error boundary, so subscriber errors propagate normally to the caller. Move only the operation that genuinely needs error isolation (such as an HTTP call or a posting step) inside the TryFunction. +When a call site uses the TryFunction's Boolean result, raise the integration event before entering the TryFunction scope. The event and its subscribers execute outside the error boundary, so subscriber errors propagate normally to the caller. Move only the operation that genuinely needs error isolation (such as an HTTP call or a posting step) inside the TryFunction. + +A TryFunction that is only ever invoked as a bare statement, with its Boolean result ignored, activates no error boundary: subscriber errors raised in its body propagate like those of any ordinary procedure. Such a publisher path needs no change; see `microsoft/knowledge/error-handling/bare-tryfunction-call-propagates-errors.md`. See sample: [`avoid-raising-events-inside-try-functions.good.al`](avoid-raising-events-inside-try-functions.good.al). ## Anti Pattern -Raising an integration event inside a TryFunction body. Subscriber failures are caught and discarded by the TryFunction. The subscriber contract — that a subscriber can signal failure to the caller — is silently broken. +Raising an integration event inside a TryFunction body that is invoked through an assignment or a conditional (for example `Success := TryDoWork();` or `if not TryDoWork() then`). Only that consumed-result call catches errors, so subscriber failures are caught and discarded and the subscriber contract — that a subscriber can signal failure to the caller — is silently broken. Resolve each call site of the TryFunction before flagging. + +The event raise alone is not this anti-pattern. When every call site of the TryFunction is a bare statement, no try boundary is active and subscriber errors reach the caller as usual. See sample: [`avoid-raising-events-inside-try-functions.bad.al`](avoid-raising-events-inside-try-functions.bad.al).