Merge latest main into performance guidance

Preserve the reviewed performance package while incorporating the strengthened deterministic review-fixture coverage contract.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

microsoft/knowledge/performance/al-methods-limited-during-write-transactions.bad.al

@@ -0,0 +1,18 @@
+codeunit 50258 "Perf Sample RunModalInTxn Bad"
+{
+    procedure ChangeShippingAgent(DocNo: Code[20])
+    var
+        SalesHeader: Record "Sales Header";
+        ShippingAgent: Record "Shipping Agent";
+    begin
+        SalesHeader.Get(SalesHeader."Document Type"::Order, DocNo);
+        SalesHeader."Shipment Date" := WorkDate();
+        SalesHeader.Modify(true); // a write transaction is now open
+
+        // Runtime error: RunModal is not allowed in write transactions.
+        if Page.RunModal(Page::"Shipping Agents", ShippingAgent) = Action::LookupOK then begin
+            SalesHeader.Validate("Shipping Agent Code", ShippingAgent.Code);
+            SalesHeader.Modify(true);
+        end;
+    end;
+}

microsoft/knowledge/performance/al-methods-limited-during-write-transactions.good.al

@@ -0,0 +1,18 @@
+codeunit 50259 "Perf Sample RunModalInTxn Good"
+{
+    procedure ChangeShippingAgent(DocNo: Code[20])
+    var
+        SalesHeader: Record "Sales Header";
+        ShippingAgent: Record "Shipping Agent";
+    begin
+        // User interaction first, while no write transaction is open.
+        if Page.RunModal(Page::"Shipping Agents", ShippingAgent) <> Action::LookupOK then
+            exit;
+
+        // All writes after the choice is made; the transaction ends with the trigger.
+        SalesHeader.Get(SalesHeader."Document Type"::Order, DocNo);
+        SalesHeader."Shipment Date" := WorkDate();
+        SalesHeader.Validate("Shipping Agent Code", ShippingAgent.Code);
+        SalesHeader.Modify(true);
+    end;
+}

microsoft/knowledge/performance/al-methods-limited-during-write-transactions.md

@@ -0,0 +1,46 @@
+---
+bc-version: [all]
+domain: performance
+keywords: [limited-during-write-transactions, write-transaction, runmodal, report-run, page-runmodal, report-runmodal, xmlport-run, codeunit-run, commit, requestpage]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# AL methods limited during write transactions: commit before RunModal and Codeunit.Run
+
+## Description
+
+Once AL code has written to the database in the current transaction — an `Insert`, `Modify`, or `Delete` with no `Commit` since — the platform restricts four methods until that transaction is committed. The exact conditions, as enforced:
+
+- `Page.RunModal` — not allowed in a write transaction, under any circumstances.
+- `Report.RunModal` and `Report.Run` — both allowed only if the request page is suppressed: `Report.RunModal(ReportId, false)` / `Report.Run(ReportId, false)` (the second argument is `RequestWindow` in both), or `UseRequestPage(false)` on a report instance. With a request page shown, either fails identically — `Run` and `RunModal` differ only in whether the report instance is cleared afterward, not in this guard.
+- `Xmlport.Run` — same rule when it would show a request page: allowed only if the request page is suppressed, `Xmlport.Run(XmlPortId, false)` (the second argument is `RequestWindow`) or the `UseRequestPage = false;` object property. With a request page shown it fails. There is no `XmlPort.RunModal` method — see the note on the platform's error text below.
+- `Codeunit.Run` — allowed only if its Boolean return value is not used. `OK := Codeunit.Run()` and `if Codeunit.Run() then` fail, because that form commits — see `codeunit-run-requires-prior-commit-inside-transaction.md`.
+
+This is a runtime error, not a compiler diagnostic: the code builds, and the first execution that reaches the call with an open write transaction dies. The guard keys on transaction state alone, not on any relation between what was written and what is opened: an `Item.Insert()` followed by `Page.RunModal(Page::"Customer Card")` — an unrelated table — fails on the `RunModal` line, and because the error stops the transaction, the insert rolls back with it.
+
+The platform's message (Business Central 26, reproduced 2026-09-07) reads: "The following AL methods are limited during write transactions because one or more tables will be locked: Form.RunModal, Codeunit.Run, Report.RunModal, XmlPort.RunModal. Form.RunModal is not allowed in write transactions. Codeunit.Run is allowed in write transactions only if the return value is not used. For example, 'OK := Codeunit.Run()' is not allowed. Report.RunModal is allowed in write transactions only if 'RequestForm = false'. For example, 'Report.RunModal(...,false)' is allowed. XmlPort.RunModal is allowed in write transactions only if 'RequestForm = false'. For example, 'XmlPort.RunModal(...,false)' is allowed. Use the commit method to save the changes before this call, or structure the code differently." The message still uses the legacy names `Form.RunModal` and `RequestForm` even though the AL method is `Page.RunModal` and the report parameter is `RequestWindow`; older versions said "C/AL functions" instead of "AL methods" (microsoft/AL#5452, 2019). The message also names `XmlPort.RunModal`, which is legacy phrasing too — there is no such AL method; the actual API the guard applies to is `Xmlport.Run`, and the message's `RequestForm = false` condition corresponds to `Xmlport.Run`'s `RequestWindow` argument or the `UseRequestPage` property. The behavior is unchanged across versions.
+
+The reason is the same one behind `avoid-user-prompts-inside-transactions.md`: a modal object waits for the user, and the platform will not let a write transaction — and every lock it holds — sit open for as long as that takes. The difference is enforcement. `Confirm` and `StrMenu` are *allowed* inside a write transaction and silently hold the locks; `RunModal` is *refused*. Both point at the same design fix.
+
+## Best Practice
+
+Sequence the work so the modal interaction happens before the write phase: run the lookup or dialog page first, then perform the writes the user's choice requires, and let the transaction end. When a modal object genuinely must follow a write, `Commit()` first — but only when the state written so far is complete and safe to persist on its own, because that Commit is a real transaction boundary, not a formality. Microsoft's own Base Application follows exactly this pattern where the preceding state is final (`ActivityLog.Table.al` commits the log entry before `Page.RunModal(Page::"Activity Log", Rec)`; `DocumentSendingProfile.Table.al` commits before `Page.RunModal(Page::"Select Sending Options", …)`). For a report, suppressing the request page — `Report.UseRequestPage(false)` on a report instance, or `false` as the `RequestWindow` argument to `Run`/`RunModal` — is a legitimate way to run it inside a write transaction when no user input is needed. For an XMLport, the equivalent is `false` as the `RequestWindow` argument to `Xmlport.Run`, or the `UseRequestPage = false;` object property; XMLports have no instance `UseRequestPage` method. `Database.IsInWriteTransaction()` (runtime 11.0+) lets library code that cannot control its caller detect the state, with the same caveat as the Codeunit.Run article: branching production flow on it usually signals unclear transaction ownership.
+
+See sample: [`al-methods-limited-during-write-transactions.good.al`](al-methods-limited-during-write-transactions.good.al).
+
+## Anti Pattern
+
+Writing to the database and then calling `Page.RunModal` (or a report/XMLport with its request page) in the same trigger — the first production run hits the runtime error. The reflexive fixes are worse than the error: dropping in `Commit()` to silence it persists a half-finished state that can no longer roll back with the rest of the operation, and swapping the page for a `Confirm` or `StrMenu` to "avoid the error" trades a loud failure for the silent lock-holding that `avoid-user-prompts-inside-transactions.md` warns about.
+
+See sample: [`al-methods-limited-during-write-transactions.bad.al`](al-methods-limited-during-write-transactions.bad.al).
+
+## Source
+
+- Microsoft Learn, `Codeunit.Run` transaction semantics ("If you're already in a transaction you must commit first before calling Codeunit.Run"): https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/codeunit/codeunit-run-method
+- Microsoft Learn, `Xmlport.Run(Integer [, Boolean] [, Boolean] [, var Record])` (the `RequestWindow` argument; confirms the XMLport data type has no `RunModal` method, static or instance): https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/xmlport/xmlport-run-method
+- Microsoft Learn, `UseRequestPage` property ("Applies to: Xml Port, Report" — an object property, not an XMLport instance method; the instance method of the same name exists only on `Report`): https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/properties/devenv-userequestpage-property
+- microsoft/AL issue #5452 (verbatim English error text, reproduced on "any current version of Business Central", 2019-11-13): https://github.com/microsoft/AL/issues/5452
+- Reproduced 2026-09-07 on Business Central 26 (runtime error dialog, English and Danish clients): a page `OnAction` doing `Item.Insert()` then `Page.RunModal(Page::"Customer Card")` fails with the text quoted in the Description, the AL call stack pointing at the `RunModal` line, and the dialog stating that the transaction was stopped.
+- Microsoft Base Application (BCApps, W1): the `Commit(); … Page.RunModal(…)` pattern in `Modules/System/Logging/ActivityLog.Table.al`, `Foundation/Reporting/DocumentSendingProfile.Table.al`, `Bank/Setup/PaymentServiceSetup.Table.al`, and others; BCApps test suites annotate the same guard as "COMMIT is required for Write Transaction Error" (`Tests/General Journal/ERMTestMultipleGenJnlLines.Codeunit.al`).

microsoft/knowledge/performance/avoid-get-inside-loop-on-large-table.md

@@ -1,7 +1,7 @@
 ---
 bc-version: [all]
 domain: performance
-keywords: [n-plus-one, get, findfirst, loop, inner-lookup, large-table]
+keywords: [n-plus-one, get, findfirst, loop, inner-lookup, large-table, item-get, query]
 technologies: [al]
 countries: [w1]
 application-area: [all]

microsoft/knowledge/performance/avoid-user-prompts-inside-transactions.md

@@ -11,7 +11,7 @@ application-area: [all]
 
 ## Description
 
-A `Confirm`, `StrMenu`, modal page, or other user prompt issued from inside a write transaction stalls the transaction — and therefore every lock it holds — until the user responds. Per the upstream guidance, "Avoid user interactions (Confirm, StrMenu) inside transactions — they hold locks while waiting for user input." The wait is bounded only by the user; meanwhile other sessions block on whatever this transaction has acquired.
+A `Confirm`, `StrMenu`, or other user prompt issued from inside a write transaction stalls the transaction — and therefore every lock it holds — until the user responds. Per the upstream guidance, "Avoid user interactions (Confirm, StrMenu) inside transactions — they hold locks while waiting for user input." The wait is bounded only by the user; meanwhile other sessions block on whatever this transaction has acquired.
 
 ## Best Practice
 

microsoft/knowledge/performance/document-report-word-layout.bad.al

@@ -0,0 +1,16 @@
+report 50105 "Sales Quote Confirmation"
+{
+    UsageCategory = Documents;
+    ApplicationArea = All;
+
+    rendering
+    {
+        layout(RDLC)
+        {
+            Type = RDLC;
+            LayoutFile = './Layouts/SalesQuoteConfirmation.rdl';
+        }
+    }
+
+    DefaultRenderingLayout = RDLC;
+}

microsoft/knowledge/performance/document-report-word-layout.good.al

@@ -0,0 +1,17 @@
+report 50105 "Sales Quote Confirmation"
+{
+    UsageCategory = Documents;
+    ApplicationArea = All;
+
+    rendering
+    {
+        layout(Word)
+        {
+            Type = Word;
+            LayoutFile = './Layouts/SalesQuoteConfirmation.docx';
+            Caption = 'Word Layout';
+        }
+    }
+
+    DefaultRenderingLayout = Word;
+}

microsoft/knowledge/performance/document-report-word-layout.md

@@ -0,0 +1,34 @@
+---
+bc-version: [all]
+domain: performance
+keywords: [report-layout, word-layout, rdlc, document-report, sandbox-app-domain, rendering]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Document reports should default to a Word layout, not RDLC
+
+> Contributions welcome — open a PR to refine or extend this article.
+
+## Description
+
+For a document report — an invoice, statement, order confirmation, or any report meant to be printed, emailed, or exported as a single-record document — Microsoft's own guidance recommends a `Word` rendering layout over `RDLC`: "RDL layouts can result in slower performance with document reports, regarding actions that are related to the user interface (for example, like sending emails) compared to Word layouts," and "we recommend that you design Word layouts instead of RDL" for this report shape (see Sources). This is a documented recommendation, not a universal guarantee that Word outperforms RDLC for every workload, and it does not apply to every report: tabular/list reports with heavy aggregation or calculated columns are still often a better fit for RDLC or Excel.
+
+## Best Practice
+
+For document reports, prefer a `Word` layout (`DefaultRenderingLayout = Word`) over RDLC unless specific layout requirements favor RDLC. Reserve RDLC (or Excel) for reports that represent a data listing rather than a document.
+
+## Sources
+
+- [Report Design Overview](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-report-design-overview)
+- [Creating an RDL layout report](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-report-performance)
+- [Troubleshooting reports / Report performance](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-reports-troubleshooting)
+
+See sample: [`document-report-word-layout.good.al`](document-report-word-layout.good.al).
+
+## Anti Pattern
+
+Defaulting a document report's layout to RDLC out of habit or because a template happened to use it. This inherits RDLC's sandboxed-app-domain performance cost with no benefit tied to the report's actual content or calculation needs.
+
+See sample: [`document-report-word-layout.bad.al`](document-report-word-layout.bad.al).