Add per-row performance guidance

Document SetAutoCalcFields for per-row FlowFields and direct writes on iterated records, with focused reviewer retrieval cues.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 85be3fc4-5253-47b8-ba1b-6b8fd188fcea

microsoft/knowledge/performance/avoid-cloning-records-before-modify-delete-in-loops.bad.al

@@ -0,0 +1,19 @@
+codeunit 50493 "Perf Record Clone Bad"
+{
+    procedure IncreaseCustomerCreditLimits(Percent: Decimal)
+    var
+        Customer: Record Customer;
+        CustomerCopy: Record Customer;
+    begin
+        Customer.SetLoadFields("Credit Limit (LCY)");
+        Customer.SetFilter("Credit Limit (LCY)", '>0');
+        if Customer.FindSet(true) then
+            repeat
+                CustomerCopy.Copy(Customer);
+                CustomerCopy.Validate(
+                    "Credit Limit (LCY)",
+                    Round(CustomerCopy."Credit Limit (LCY)" * (1 + Percent / 100)));
+                CustomerCopy.Modify(true);
+            until Customer.Next() = 0;
+    end;
+}

microsoft/knowledge/performance/avoid-cloning-records-before-modify-delete-in-loops.good.al

@@ -0,0 +1,17 @@
+codeunit 50492 "Perf Record Clone Good"
+{
+    procedure IncreaseCustomerCreditLimits(Percent: Decimal)
+    var
+        Customer: Record Customer;
+    begin
+        Customer.SetLoadFields("Credit Limit (LCY)");
+        Customer.SetFilter("Credit Limit (LCY)", '>0');
+        if Customer.FindSet(true) then
+            repeat
+                Customer.Validate(
+                    "Credit Limit (LCY)",
+                    Round(Customer."Credit Limit (LCY)" * (1 + Percent / 100)));
+                Customer.Modify(true);
+            until Customer.Next() = 0;
+    end;
+}

microsoft/knowledge/performance/avoid-cloning-records-before-modify-delete-in-loops.md

@@ -0,0 +1,26 @@
+---
+bc-version: [all]
+domain: performance
+keywords: [clone, copy, recordref, gettable, by-value, modify, delete, loop]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Avoid cloning records before Modify or Delete in loops
+
+## Description
+
+Microsoft's [AL database-method performance guidance](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/optimize-sql-al-database-methods-and-performance-on-server#insert-modify-delete-and-locktable) states that cloning an iterated record before `Modify` or `Delete` restarts the SQL `SELECT` and issues an extra SQL statement for every row. The runtime treats `Record.Copy`, `RecordRef.GetTable`, and passing a record by value to a writing helper as clones in this situation.
+
+## Best Practice
+
+Use `FindSet(true)` when the loop writes the traversed rows, and call `Modify` or `Delete` on that iterating record variable. If generic code is required, open and iterate the `RecordRef` directly instead of calling `GetTable` for each typed record. Keep a per-row loop when validation or row-specific behavior is required; this rule does not imply that `ModifyAll` or `DeleteAll` is equivalent.
+
+See sample: `avoid-cloning-records-before-modify-delete-in-loops.good.al`.
+
+## Anti Pattern
+
+Inside an active traversal, copy the current row, convert it with `RecordRef.GetTable`, or pass it without `var` to a helper, then call `Modify` or `Delete` on that clone. Do not flag read-only snapshots, temporary records, or copies used to write a different target table; the documented extra-statement concern is clone-before-write on the traversed table.
+
+See sample: `avoid-cloning-records-before-modify-delete-in-loops.bad.al`.

microsoft/knowledge/performance/use-setautocalcfields-for-per-row-flowfields.bad.al

@@ -0,0 +1,16 @@
+codeunit 50491 "Perf AutoCalcFields Bad"
+{
+    procedure CollectOverLimitCustomers(var CustomerNos: List of [Code[20]])
+    var
+        Customer: Record Customer;
+    begin
+        Customer.SetLoadFields("Credit Limit (LCY)");
+        Customer.SetFilter("Credit Limit (LCY)", '>0');
+        if Customer.FindSet() then
+            repeat
+                Customer.CalcFields("Balance (LCY)");
+                if Customer."Balance (LCY)" > Customer."Credit Limit (LCY)" then
+                    CustomerNos.Add(Customer."No.");
+            until Customer.Next() = 0;
+    end;
+}

microsoft/knowledge/performance/use-setautocalcfields-for-per-row-flowfields.good.al

@@ -0,0 +1,16 @@
+codeunit 50490 "Perf AutoCalcFields Good"
+{
+    procedure CollectOverLimitCustomers(var CustomerNos: List of [Code[20]])
+    var
+        Customer: Record Customer;
+    begin
+        Customer.SetLoadFields("Credit Limit (LCY)");
+        Customer.SetFilter("Credit Limit (LCY)", '>0');
+        Customer.SetAutoCalcFields("Balance (LCY)");
+        if Customer.FindSet() then
+            repeat
+                if Customer."Balance (LCY)" > Customer."Credit Limit (LCY)" then
+                    CustomerNos.Add(Customer."No.");
+            until Customer.Next() = 0;
+    end;
+}

microsoft/knowledge/performance/use-setautocalcfields-for-per-row-flowfields.md

@@ -0,0 +1,26 @@
+---
+bc-version: [all]
+domain: performance
+keywords: [setautocalcfields, calcfields, calcsums, flowfield, loop, per-row]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Use SetAutoCalcFields when each iterated row needs a FlowField
+
+## Description
+
+`Record.SetAutoCalcFields` has been available since runtime 1.0 and makes the specified FlowFields calculate as records are retrieved. Microsoft's [AL database-method performance guidance](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/optimize-sql-al-database-methods-and-performance-on-server#setautocalcfields) uses it to remove an explicit `CalcFields` call from every iteration when each row's FlowField drives a branch. This is different from `CalcSums`, which returns a total for the filtered set rather than a value for each row.
+
+## Best Practice
+
+Call `SetAutoCalcFields` before `FindSet` when every returned row needs the same FlowField for a comparison, branch, or per-record action. Use `CalcSums` instead when the required result is one aggregate over the filtered set (see `calcsums-instead-of-calcfields-in-loop.md`).
+
+See sample: `use-setautocalcfields-for-per-row-flowfields.good.al`.
+
+## Anti Pattern
+
+Calling `CalcFields` inside the loop when every iteration reads the same FlowField. Each `CalcFields` request requires a separate SQL statement unless a compatible recent result is cached. Do not replace row-specific decisions with `CalcSums`; an aggregate cannot preserve which rows met the condition.
+
+See sample: `use-setautocalcfields-for-per-row-flowfields.bad.al`.