Dynamics 365 Business Central: AL extension development basics

Set up VS Code and AL, understand table/page extensions, events and app.json dependencies, and publish an extension to a Business Central sandbox.

Business Central is customised exclusively through AL extensions — no more base-code modifications. The model is simple once you internalise three ideas: you extend objects, you subscribe to events, and everything ships as a versioned app.

Getting the environment ready

1. Install Visual Studio Code and the AL Language extension.
2. Create a sandbox environment in the Business Central admin centre (or use a Docker container image for on-prem work).
3. Ctrl+Shift+P → AL: Go! scaffolds a project with app.json and launch.json.
4. Download symbols (AL: Download Symbols) before writing any code.

Extending an object

tableextension 50100 "Customer Ext" extends Customer
{
    fields
    {
        field(50100; "Loyalty Tier"; Enum "Loyalty Tier")
        {
            Caption = 'Loyalty Tier';
            DataClassification = CustomerContent;
        }
    }
}

pageextension 50100 "Customer Card Ext" extends "Customer Card"
{
    layout
    {
        addlast(General)
        {
            field("Loyalty Tier"; Rec."Loyalty Tier") { ApplicationArea = All; }
        }
    }
}

Events instead of modifications

Business logic hooks into published events rather than editing base code:

codeunit 50100 "Loyalty Subscribers"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post", 'OnAfterPostSalesDoc', '', false, false)]
    local procedure UpdateTierOnPost(var SalesHeader: Record "Sales Header")
    begin
        // award points, update tier
    end;
}

Use [IntegrationEvent] in your own code so other apps can extend yours the same way. If a required event does not exist in the base app, request it through the Microsoft ALAppExtensions repository rather than working around it.

app.json essentials

• id — a stable GUID; never change it after publishing.
• version — four-part; increment for every deployment.
• idRanges — must match your assigned object range (50000–99999 for per-tenant customisations).
• application / platform — the minimum BC version you support.
• dependencies — other apps you extend, with their IDs and minimum versions.

Publishing and lifecycle

Press F5 to publish to your sandbox. For production, build the .app file in a pipeline (AL-Go for GitHub is the supported template), sign it if required, and upload it via the Extension Management page or the admin centre API. Always test against the next major version in a preview sandbox before Microsoft's forced update window — Business Central updates twice a year and will not wait for you.

Common pitfalls

• Missing DataClassification on new fields blocks AppSource validation.
• Adding fields to posted tables — do not; extend the setup or ledger instead.
• Long-running code in OnAfterGetRecord destroys list performance.
• Forgetting ApplicationArea hides your controls from users.