Add 18 more community AL/BC patterns across appsource, data-modeling, error-handling, security, style, testing, ui, upgrade, and web-services

Second contribution from CURABIS ApS, generalized from patterns observed across real AppSource/PTE development. Cross-checked against the current microsoft/knowledge corpus before opening; several originally-drafted candidates were dropped as duplicates of existing files.

microsoft/knowledge/data-modeling/code-must-not-change-workdate.bad.al

@@ -0,0 +1,9 @@
+codeunit 50101 "Batch Job Runner"
+{
+    procedure AdvanceToNextBusinessDay()
+    begin
+        // Anti-pattern: repurposes the user's session WorkDate as a
+        // scratch variable for unrelated business logic.
+        WorkDate(CalcDate('<1D>', WorkDate()));
+    end;
+}

microsoft/knowledge/data-modeling/code-must-not-change-workdate.good.al

@@ -0,0 +1,11 @@
+codeunit 50100 "Posting Date Helper"
+{
+    procedure GetDefaultPostingDate(): Date
+    var
+        PostingDate: Date;
+    begin
+        // Read the work date to default a value; never write to it.
+        PostingDate := WorkDate();
+        exit(PostingDate);
+    end;
+}

microsoft/knowledge/data-modeling/code-must-not-change-workdate.md

@@ -0,0 +1,40 @@
+---
+bc-version: [all]
+domain: data-modeling
+keywords: [workdate, session-setting, user-control, side-effect]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Application code must not change the WorkDate
+
+## Description
+
+The work date is a per-user session setting the user controls from the
+client (the date shown in the top-right corner, used to default posting
+dates and date filters). Application code must never call the `WorkDate`
+function to set a new value. Doing so changes what the user sees and
+defaults to for the rest of their session, as a side effect of running
+unrelated business logic — a surprising, hard-to-trace behavior change the
+user never asked for and has no visibility into.
+
+This is a call-direction distinction: reading the current work date via
+`WorkDate` (or `WorkDate()` with no argument) is fine and common — it is
+only the assignment form, `WorkDate(NewDate)`, that is the anti-pattern.
+
+## Best Practice
+
+Read the work date to default a value; never write to it.
+
+See sample: `code-must-not-change-workdate.good.al`.
+
+## Anti Pattern
+
+Setting the work date from within a codeunit, report, or page action
+changes session state the user owns, for the duration of a call that has
+nothing to do with the user's date preference. If a scenario genuinely
+needs a specific date for a calculation, pass or compute that date as a
+local variable — never repurpose the session's `WorkDate`.
+
+See sample: `code-must-not-change-workdate.bad.al`.

microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.bad.al

@@ -0,0 +1,11 @@
+table 50111 "Sample Item Card"
+{
+    fields
+    {
+        field(1; "No."; Code[20]) { }
+        field(50; Picture; BLOB)
+        {
+            Caption = 'Picture';
+        }
+    }
+}

microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.good.al

@@ -0,0 +1,11 @@
+table 50110 "Sample Item Card"
+{
+    fields
+    {
+        field(1; "No."; Code[20]) { }
+        field(50; Picture; Media)
+        {
+            Caption = 'Picture';
+        }
+    }
+}

microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.md

@@ -0,0 +1,44 @@
+---
+bc-version: [all]
+domain: data-modeling
+keywords: [blob, media, mediaset, picture-field, image-field, table-design]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Pictures must be stored in a Media/MediaSet field, not BLOB
+
+## Description
+
+`BLOB` is still a valid AL field type for arbitrary binary data, but it is
+not the right choice for storing pictures or images. The current
+recommendation is the `Media` field type for a single image, or
+`MediaSet` when a record needs several image variants (e.g. multiple
+sizes). Media/MediaSet integrate with the platform's picture control, the
+media repository, image caching, and thumbnail generation — none of which
+a plain `BLOB` field gets. A `BLOB` field storing a picture works, but it
+is the legacy approach: no caching, no thumbnail support, and no
+integration with the standard picture controls used across Business
+Central pages.
+
+`BLOB` remains the correct choice for genuinely arbitrary binary payloads
+that are not images and don't benefit from the media pipeline (e.g. a raw
+file attachment blob unrelated to picture rendering).
+
+## Best Practice
+
+Use `Media` (or `MediaSet` for multiple image variants) for any field that
+holds a picture.
+
+See sample: `pictures-must-use-media-not-blob.good.al`.
+
+## Anti Pattern
+
+A `BLOB` field named "Picture" compiles and stores the image bytes, but
+it misses the picture control integration, caching, and thumbnail
+generation that a `Media`/`MediaSet` field provides for free — the anti
+pattern is choosing `BLOB` for image storage out of habit rather than
+recognizing that the field is holding a picture, not generic binary data.
+
+See sample: `pictures-must-use-media-not-blob.bad.al`.

microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.bad.al

@@ -0,0 +1,17 @@
+table 50121 "Sample Ledger Entry"
+{
+    fields
+    {
+        // Anti-pattern: a Ledger table's key must never be user-editable.
+        field(1; "Entry No."; Integer) { }
+        field(2; "Posting Date"; Date) { }
+        field(3; Amount; Decimal) { }
+    }
+    keys
+    {
+        key(PK; "Entry No.") { Clustered = true; }
+    }
+    // No AutoIncrement, no guard against manual insert/delete — a user or
+    // integration can renumber or remove entries, breaking the Ledger
+    // type's audit-trail guarantee.
+}

microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.good.al

@@ -0,0 +1,16 @@
+table 50120 "Sample Ledger Entry"
+{
+    fields
+    {
+        // Ledger primary key: Integer "Entry No.", set only by posting.
+        field(1; "Entry No."; Integer) { AutoIncrement = true; }
+        field(2; "Posting Date"; Date) { }
+        field(3; Amount; Decimal) { }
+    }
+    keys
+    {
+        key(PK; "Entry No.") { Clustered = true; }
+    }
+    // No user-facing Insert/Delete/Modify path is exposed; rows are
+    // created exclusively by the posting routine.
+}

microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.md

@@ -0,0 +1,81 @@
+---
+bc-version: [all]
+domain: data-modeling
+keywords: [tables, table-design, naming-conventions, primary-key, master-table, ledger-table, journal-table, register-table, document-table, setup-table, subsidiary-table, supplemental-table]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Tables must match one of Business Central's nine table-type conventions
+
+## Description
+
+Business Central's Base Application follows nine recurring table types —
+Master, Supplemental, Subsidiary, Ledger, Register, Journal, Document,
+Document History, and Setup. Each type fixes a naming pattern, a
+primary-key shape, and a set of associated pages. A new or extended table
+whose design doesn't match the conventions of its own type is either
+misclassified or built inconsistently with the rest of the application,
+and should be flagged in review even if it compiles. Before assigning a
+primary key or naming a new table, first identify which of the nine types
+it is — that answer fixes almost every other design decision.
+
+## Best Practice
+
+Match the table's design to its type:
+
+1. **Master** (Customer, Item) — one record is the subject; primary key
+   `Code[20]` named `No.`; description field in `DataCaptionFields`; Card +
+   List (+ Statistics) pages.
+2. **Supplemental** (Currency, Language) — used across functional areas;
+   primary key `Code[10]` named `Code`; one List page, plural name, set as
+   `LookupPageID`.
+3. **Subsidiary** (Item Vendor) — subsidiary to a Master/Supplemental
+   table; primary key is the parent key field(s), optionally + `Line No.`;
+   Worksheet or Tabular page, always filtered by the calling page.
+4. **Ledger** (Cust. Ledger Entry) — transactional record of a functional
+   area; primary key `Integer` `Entry No.`, always auto-generated by
+   posting, never user-editable, no free add/delete; List page as
+   `LookupPageID`/`DrillDownPageID`.
+5. **Register** (G/L Register) — table of contents for its Ledger, one row
+   per posting run; primary key `Integer` `No.`, auto-generated; carries
+   `From Entry No.`/`To Entry No.`; List page with a link to the Ledger.
+6. **Journal** (Resource Journal Line) — where users enter data before
+   posting to a Ledger; primary key Template + Batch + `Integer` `Line No.`;
+   Worksheet page with `AutoSplitKey`, a Posting action, and a link to the
+   Ledger.
+7. **Document** (Sales Header/Line) — posts to Ledgers via Journals, not
+   directly; Header primary key `Code[20]` `No.` (or + `Option Document
+   Type`); Line primary key = Header key renamed `<Document> No.` +
+   `Integer Line No.`; Document/Card page with a Posting action and a lines
+   subpage.
+8. **Document History** (Posted Sales Invoice Header/Line) — posted copy of
+   a Document table, created during posting; mirrors the source table's
+   fields; never user-editable; same page shape but the Line-equivalent is
+   a List page, not a Worksheet.
+9. **Setup** (General Ledger Setup) — exactly one record for a functional
+   area; primary key `Code[10]` named `Primary Key`, always blank; one page
+   with the key field hidden, whose `OnOpenPage` creates the singleton the
+   first time it's opened (`Reset()` → `Get()` → if not found, `Init()` →
+   `Insert()`) rather than assuming the record pre-exists.
+
+A table named "Setup" that holds more than one record follows Subsidiary
+rules instead — the name alone is not proof of type. When a table's
+identity can't be resolved from its definition alone (e.g. a "Setup"-named
+table with a real business-field key and no page), say so explicitly
+rather than forcing a classification; settling it requires checking actual
+row cardinality or call sites, not just the object definition.
+
+See sample: `table-design-must-match-bc-table-type-conventions.good.al`.
+
+## Anti Pattern
+
+A table that mixes conventions from two types — for example, a "Ledger"
+table with a user-editable primary key that lets users freely insert or
+delete rows — is not "flexible", it is either misclassified or has skipped
+a design step. A Ledger table's `Entry No.` must come only from the
+posting routine; exposing it as an editable field breaks the type's core
+guarantee that entries are an immutable, sequential audit trail.
+
+See sample: `table-design-must-match-bc-table-type-conventions.bad.al`.