Protected Variables in Business Central (AL)

I’ve been writing Business Central extensions for many years and one thing I’ve always wanted is a clean way to access the “working” variables inside the objects I’m extending. Too often, you end up re-implementing the same logic in a pageextension or reportextension just to get at a flag, buffer, or calculated value. Fortunately, there’s a solution for that: protected variables.

What Are Protected Variables?

Protected variables are global variables that an AL object intentionally exposes to extensions in a controlled way.

In AL, you declare them in a protected var section. That makes them accessible to extension objects that extend the source object, such as:

• tables ↔ table extensions
• pages ↔ page extensions
• reports ↔ report extensions
• dependent apps (extensions) when there is an explicit app dependency

This is especially useful when you have internal states (flags, buffers, counters, temporary records) that extensions legitimately need to read or toggle—without forcing everyone into copy/paste base logic.

Why Protected Variables Exist (And What They Replace)

Before protected variables, developers typically had to choose between:

• Making a variable not accessible (so extensions can’t reuse it), or
• Reworking the design into events/procedures, or
• Duplicating logic in extensions (fragile and expensive)

Protected variables fill a pragmatic gap: they let the base object expose “just enough” internal states to extension objects.

Syntax: protected var vs var

The syntax is simple, but important:

protected var
    MyProtectedValue: Boolean;

var
    MyLocalOnlyValue: Integer;

• Variables in protected var are accessible to extension objects that extend the source object.
• Variables in var are local to the object and not accessible from extensions.

If you want to expose only some variables, you must split declarations into two sections (as shown above).

Example: Exposing a Page Flag to a Page Extension

This is a common real-world pattern: a base page maintains a flag that controls visibility or behavior and the extension needs to reuse that same flag.

Base page:

page 50100 "DVLPR My Page"
{
    SourceTable = Customer;
    PageType = Card;

    layout
    {
        area(Content)
        {
            group(Advanced)
            {
                Visible = ShowBalance;

                field(Balance; Balance)
                {
                    ApplicationArea = All;
                }
            }
        }
    }

    actions
    {
        area(Processing)
        {
            action(ToggleBalance)
            {
                ApplicationArea = All;
                trigger OnAction()
                begin
                    ShowBalance := not ShowBalance;
                end;
            }
        }
    }

    protected var
        ShowBalance: Boolean;
}

Page extension:

pageextension 50101 "DVLPR My Page Ext" extends "DVLPR My Page"
{
    layout
    {
        addlast(Content)
        {
            group(MoreBalance)
            {
                Visible = ShowBalance;

                field("Balance (LCY)"; "Balance (LCY)")
                {
                    ApplicationArea = All;
                }
            }
        }
    }
}

This is the difference between a clean extension and one that has to reimplement the base page’s behavior.

Benefits (What You Actually Gain)

• Better extensibility contracts: You can intentionally expose state that is useful to extensions.
• Less copy/paste logic: Extensions can build on the base behavior without recreating it.
• Cleaner page/report extensions: You can reuse the base object’s “working variables” (visibility flags, buffer values, temporary records).
• Cross-app collaboration: If App B depends on App A, App B can access App A’s protected variables when extending App A’s objects.

What Protected Variables Are

• They are shared mutable states. An extension can change the value, potentially causing side effects.
• They create coupling: If the base object later changes or removes the variable, dependent extensions may need to be updated.

If you need strict validation, invariants, or long-term stability, a protected/public procedure (or an event with parameters) is often a better design than exposing the variable directly.

Rules of Thumb and When to Use Them

I tend to reach for protected var when:

• The variable is part of the object’s internal UI/state (visibility flags, cached totals, temporary buffers).
• The extension genuinely needs to share the same state as the base object.
• Exposing an entire public procedure would be overkill.

I avoid protected var when:

• The extension should not mutate the value (prefer a procedure).
• The value represents a business invariant (prefer validation + procedures/events).

Version Notes and Gotchas

Protected variables have been around for several Business Central versions, but you should still test your specific pattern on the oldest version you support.

A couple of practical lessons from the community:

• If you’re binding values in a page extension and the source is “complex” (arrays, temporary buffers, etc.), it can be safer to stage the value into your own variable in a trigger (for example, OnAfterGetRecord) instead of binding directly.
• Keep protected var focused on state you expect extensions to use. When the value needs validation or invariants, expose a procedure/event instead.

Further Reading

• Microsoft Learn (protected variables): here

Wrapping Up

Protected variables are one of those small AL features that make extension design feel much more natural. When used intentionally, they allow page/report/table extensions to integrate tightly with the base object’s state.

Use them as a targeted extensibility tool: expose only what’s needed, keep the surface area small, and choose procedures/events when you need validation or a long-term stable API.

Note: The information in this article is for informational and demonstration purposes only. Protected variables apply to Business Central 2019 release wave 2 and later. Always test on the lowest supported Business Central version.