There are a bunch of things you want to happen when an extension is installed in a tenant: Seed some setup, create default records, or run a process.

That’s what install codeunits are for.

This post is specifically about codeunits with SubType = Install; and how (and when) Business Central runs them.

What Is an Install Codeunit?

An install codeunit is a codeunit whose SubType is set to Install and includes AL methods for performing operations with the extension code itself:

• When an extension is installed for the first time
• When an uninstalled version is installed again (reinstall)

Install code is not part of an upgrade. If you publish a newer version and run a data upgrade, that’s upgrade codeunit territory.

Learn more about writing extension install code here.

The SubType Property (And What It Really Means)

The SubType property tells the platform what kind of codeunit you’re creating.

For install logic, the important bit is:

codeunit 50100 "DVLPR Install"
{
    SubType = Install;
}

Microsoft’s reference page for the property is here.

The Two Install Triggers: Per-Company vs. Per-Database

Install codeunits have two system triggers:

• OnInstallAppPerCompany()
• OnInstallAppPerDatabase()

The names are telling:

• Per-company runs once for each company.
• Per-database runs once for the whole tenant/database as part of the install.

A simple skeleton:

codeunit 50100 "DVLPR Install"
{
    SubType = Install;

    trigger OnInstallAppPerCompany()
    begin
        // Company-specific setup
    end;

    trigger OnInstallAppPerDatabase()
    begin
        // Tenant-wide setup
    end;
}

You Can Have More than One Install Codeunit (But Don’t Assume Order)

You can have multiple install codeunits in the same extension version.

But there’s an important catch from the docs: There’s no guaranteed execution order between different install codeunits.

So if you split install logic across multiple codeunits, design them so they can run independently (or at least safely if they run in any order).

Fresh Install vs. Reinstall: Use ModuleInfo.DataVersion()

A really practical pattern is to detect whether this is:

• A true first-time install (no prior data)
• A reinstall (data exists from a previous install)

The docs call out a convention: In install code, a DataVersion of 0.0.0.0 means “fresh/new install”.

You can access this using NavApp.GetCurrentModuleInfo and ModuleInfo:

codeunit 50100 "DVLPR Install"
{
    SubType = Install;

    trigger OnInstallAppPerDatabase()
    var
        CurrentModuleInfo: ModuleInfo;
    begin
        NavApp.GetCurrentModuleInfo(CurrentModuleInfo);

        if CurrentModuleInfo.DataVersion() = Version.Create(0, 0, 0, 0) then
            HandleFreshInstall()
        else
            HandleReinstall();
    end;

    local procedure HandleFreshInstall()
    begin
        // First install of this app in this tenant
        // e.g. create default setup, seed templates, etc.
    end;

    local procedure HandleReinstall()
    begin
        // App was installed before, removed, and installed again
        // e.g. validate/patch baseline records
    end;
}

If you want to go deeper into what you can read from ModuleInfo, the NavApp datatype docs are a good jumping-off point: Learn more about NavApp and ModuleInfo here

What Belongs in Install Code?

My rule of thumb: Install code should be idempotent and fast.

Good candidates:

• Create extension setup records if missing
• Initialize default values (like templates, configurations, default dimensions)
• Seed reference data that your app expects to exist
• Register things that prevent “first upgrade surprises” (more on that below)

Less-than-ideal candidates:

• Long-running data migrations (that’s upgrade code)
• Anything that depends on user interaction (install runs in a system context)
• Anything that can’t be safely retried

Install Code + Upgrade Tags (So Your First Upgrade Doesn’t Re-run Old Steps)

If you use upgrade tags to guard upgrade steps, a recommended approach is to register the tag(s) during install.

That way, when the customer upgrades later, your upgrade code doesn’t run a migration step just because the tag table is empty.

I covered upgrade tags (and version gating) in a separate post:

• See: 2026-01-06-upgrading-extensions-and-upgrade-tags.md

Wrapping Up

Install codeunits are one of those features you don’t think about much—until you need them.

Use them to make your extension feel polished on day one: Create the defaults, seed the data you know you’ll need, and put guard rails in place so later upgrades stay predictable.

Learn more:

• Writing Extension Install Code
• Initialize data during extension installation (training module)
• Upgrading extensions and upgrade tags

Note: This content is for informational and demonstration purposes only. Always test installation logic in a sandbox and make sure it’s safe to run repeatedly.

If you’ve developed extensions for any length of time, you’ve probably learned the hard way that “upgrade code” is not where you want surprises.

You’re running in a system session, on customer data, in an environment update window, and whatever you do needs to be repeatable, safe, and fast.

Today, we’ll look at two common ways to control upgrade logic in Business Central:

• Checking versions (What version am I upgrading from?)
• Using upgrade tags (Has this upgrade step already run?)

Both approaches work, and you may often use a mix.

What Is an Upgrade Codeunit?

An upgrade codeunit is a codeunit with SubType = Upgrade; that Business Central executes as part of an extension upgrade.

There are two important scopes:

• Per-company upgrade: Runs once per company.
• Per-database upgrade: Runs once for the whole tenant/database.

A typical upgrade codeunit is structured around the upgrade triggers (preconditions → upgrade → validation). You’ll see these in Microsoft’s “Upgrading extensions” documentation.

Learn more about upgrading extensions and Upgrade codeunit here.

Controlling Upgrade Logic with Version Checks

The “classic” approach is to gate each upgrade step by checking the version you’re upgrading from.

In upgrade code, you can read version information using NavApp.GetCurrentModuleInfo and then compare against ModuleInfo.DataVersion() (commonly interpreted as the data version you’re upgrading from).

Example (simplified):

codeunit 50160 "DVLPR Upgrade"
{
    SubType = Upgrade;

    trigger OnUpgradePerCompany()
    var
        CurrentModuleInfo: ModuleInfo;
    begin
        NavApp.GetCurrentModuleInfo(CurrentModuleInfo);

        // Only run this step when upgrading from versions older than 2.0.0.0
        if CurrentModuleInfo.DataVersion() < Version.Create(2, 0, 0, 0) then
            UpgradeStep_200();
    end;

    local procedure UpgradeStep_200()
    begin
        // data transformation, backfill, etc.
    end;
}

This pattern is straightforward and works well when:

• You have a small number of versions to support.
• Each upgrade step cleanly maps to a specific “from version” range.

Where it gets messy is when you’ve shipped many versions, had hotfixes, or need to make upgrade code resilient against partial runs.

The Problem with Pure Version Checks

Version checks alone don’t tell you whether the step has already executed successfully.

For example:

• A tenant may have attempted an update, failed halfway through, and then retried.
• You may ship a fix that needs to run even if the version comparison still matches.
• You may be backporting an upgrade step into a servicing build.

In those cases, “Did we already run this exact step?” is a better question than, “What version are we upgrading from?”

Upgrade Tags: A Reliable Way to Make Upgrade Steps Idempotent

Upgrade tags are essentially a durable marker that says: “This specific upgrade step has been completed.”

Business Central provides the System.Upgrade codeunit “Upgrade Tag” (ID 9999) for this.

If you ever need to see what tags currently exist in an environment, you can open page 9985 Upgrade Tags to view the stored upgrade tags.

Microsoft Learn reference: Codeunit “Upgrade Tag”

The two methods you’ll use most often are:

• HasUpgradeTag(Tag: Code[250]): Boolean
• SetUpgradeTag(NewTag: Code[250])

(There are also database-scoped methods like HasDatabaseUpgradeTag and SetDatabaseUpgradeTag when you need a tag that applies at the database level.)

Example: Using HasUpgradeTag / SetUpgradeTag in an Upgrade Codeunit

Here’s the basic pattern:

1. Check if the tag exists.
2. If it does, exit (step already completed).
3. Run the upgrade logic.
4. Set the tag.

codeunit 50161 "DVLPR Upgrade With Tags"
{
    SubType = Upgrade;

    trigger OnUpgradePerCompany()
    var
        UpgradeTag: Codeunit "Upgrade Tag";
        Tag: Code[250];
    begin
        Tag := 'DVLPR-50161-PerformUpgradeSomething-20260105';
        if UpgradeTag.HasUpgradeTag(Tag) then
            exit;

        PerformUpgradeSomething();

        UpgradeTag.SetUpgradeTag(Tag);
    end;

    local procedure PerformUpgradeSomething()
    begin
        // data transformation, backfill, etc.
    end;
}

A few notes:

• The tag format is up to you, but make it unique and traceable. A common pattern is CompanyPrefix-WorkItem-Description-YYYYMMDD.
• The critical part is when you set the tag—set it only after the step is complete.

Version Checks + Upgrade Tags Together

In many real upgrades, the best solution is a hybrid:

• Use version checks to decide whether a step is relevant.
• Use an upgrade tag to ensure the step runs once, at most.

Example:

trigger OnUpgradePerCompany()
var
    CurrentModuleInfo: ModuleInfo;
    UpgradeTag: Codeunit "Upgrade Tag";
    Tag: Code[250];
begin
    NavApp.GetCurrentModuleInfo(CurrentModuleInfo);

    if CurrentModuleInfo.DataVersion() >= Version.Create(2, 0, 0, 0) then
        exit;

    Tag := 'DVLPR-200-UpgradeStep-20260105';
    if UpgradeTag.HasUpgradeTag(Tag) then
        exit;

    UpgradeStep_200();
    UpgradeTag.SetUpgradeTag(Tag);
end;

A Practical Reminder: Order Isn’t Guaranteed Across Upgrade Codeunits

One important design point from the platform: If you have multiple upgrade codeunits, the execution order between different upgrade codeunits is not something you should rely on.

Keep upgrade steps independent, or consolidate logically dependent work into a single upgrade codeunit.

Wrapping Up

You can control upgrade code in Business Central by checking versions, but upgrade tags add a second layer of safety: They let you make individual upgrade steps idempotent and resilient across retries and long-lived version histories.

If you’re building an extension that you expect to ship and maintain for years, upgrade tags are one of the best tools you can adopt early on.

Learn more:

• Upgrade tags (HasUpgradeTag, SetUpgradeTag, and more)
• Upgrading extensions (upgrade triggers, version checks, best practices)
• SubType = Upgrade property reference

Note: The code and information discussed in this article are for informational and demonstration purposes only. Always test upgrade code in a sandbox and make sure it behaves correctly on a copy of production data. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online.

If you build extensions long enough, you eventually get burned by a dependency you didn’t mean to create: another app starts calling into your “helper” codeunit, or relies on a table/field you never intended as public API. Later, you refactor—and everything breaks.

That’s the real value of the Access property: it lets you define (at compile time) what’s part of your supported surface area versus what’s strictly internal implementation.

What Is the Access Property?

The Access property sets the compile-time visibility of an AL object (and, for tables, of individual fields). In practice, it controls whether other AL code can take a direct reference to that symbol.

Think of it as the AL equivalent of “public vs internal” in other languages, but scoped to apps (modules) and extension objects.

What the Access Property Applies To

Access applies to:

• Codeunit
• Query
• Table
• Table field
• Enum
• Interface
• PermissionSet

Object-Level Access: Public vs Internal

For most objects (tables, codeunits, queries, interfaces, enums), you’ll typically use:

• Access = Public; (default): Other apps that reference your app can use the object.
• Access = Internal;: Only code inside your app can reference the object.

Example: keep a table internal so nobody else compiles against it:

table 50111 "DVLPR Internal Staging"
{
    DataClassification = CustomerContent;
    Access = Internal;

    fields
    {
        field(1; "Entry No."; Integer) { }
        field(2; Payload; Blob) { }
    }
}

Table Field Access: Local, Protected, Internal, Public

Table fields add two extra options that are incredibly useful for designing clean extensibility:

• Local: Only code in the same table or the same table extension object where the field is defined can reference the field.
• Protected: Code in the base table and table extensions of that table can reference the field.
• Internal: Anything inside the same app can reference the field.
• Public (default): Any referencing app can reference the field.

Example: Table with different field access levels:

table 50140 "DVLPR Access Property"
{
    Access = Public;
    Caption = 'DVLPR';
    DataClassification = CustomerContent;

    fields
    {
        field(1; "Code"; Code[10])
        {
            Caption = 'Code';
            ToolTip = 'Specifies the value of the Code field.';
        }
        field(2; "Local Code"; Code[10])
        {
            Access = Local;
            Caption = 'Local Code';
            ToolTip = 'Specifies the value of the Local Code field.';
        }
        field(3; "Protected Code"; Code[10])
        {
            Access = Protected;
            Caption = 'Protected Code';
            ToolTip = 'Specifies the value of the Protected Code field.';
        }
        field(4; "Public Code"; Code[10])
        {
            Access = Public;
            Caption = 'Public Code';
            ToolTip = 'Specifies the value of the Public Code field.';
        }
        field(5; "Internal Code"; Code[10])
        {
            Access = Internal;
            Caption = 'Internal Code';
            ToolTip = 'Specifies the value of the Internal Code field.';
        }
    }
    keys
    {
        key(PK; "Code")
        {
            Clustered = true;
        }
    }
}

The Access levels for table fields are especially useful when you want to allow controlled extensibility without opening up everything.

If, for example, you have a field with Access = Local, you won’t be able to reference it by name from a page, report, or codeunit—even inside the same app.

One more practical detail from the platform: table and field accessibility affects the in-client Designer. Only Public table fields can be added to pages using Designer.

Sharing Internals Between Your Own Apps: internalsVisibleTo

Sometimes you do want internals shared—but only with your own “companion” apps. That’s where internalsVisibleTo in app.json comes in.

It allows specific friend modules to compile against your Access = Internal objects.

Example app.json snippet:

{
  "internalsVisibleTo": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "DVLPR Companion App",
      "publisher": "DVLPRLIFE"
    }
  ]
}

Important: Access Is Compile-Time Only (Not Security)

This is the part that’s easy to misunderstand.

Access is enforced at compile time. It is not a runtime security boundary.

One way to think about it: Access controls who can compile against your symbols, not who can ultimately interact with data at runtime. Business Central still has reflection-style mechanisms (such as RecordRef, FieldRef, and TransferFields) that can work with tables/fields without a direct symbol reference.

For example, even though the Local Code field is marked as Access = Local, you can still technically read and write it using RecordRef and FieldRef (because those APIs work by field number rather than a compile-time field reference):

    procedure GetLocalCode(): Code[10]
    var
        RecordRef: RecordRef;
        FieldRef: FieldRef;
        LocalCode: Code[10];
    begin
        RecordRef.GetTable(Rec);
        FieldRef := RecordRef.Field(2);
        LocalCode := FieldRef.Value;
        RecordRef.Close();

        exit(LocalCode);
    end;

    procedure SetLocalCode(NewLocalCode: Code[10])
    var
        RecordRef: RecordRef;
        FieldRef: FieldRef;
    begin
        RecordRef.GetTable(Rec);
        FieldRef := RecordRef.Field(2);
        FieldRef.Value := NewLocalCode;
        RecordRef.Modify();
        RecordRef.Close();
    end;

When I Reach for Each Level

My personal defaults:

• Public: Objects/fields I’m willing to support as a stable contract.
• Internal: Implementation objects I expect to refactor freely.
• Protected (fields): When I want controlled extensibility through table extensions.
• Local (fields): Fields that are strictly internal to the table logic.

Wrapping Up

The Access property is one of the most practical tools you have for keeping an extension maintainable over time. It helps you draw a clear line between API and implementation, reduces accidental coupling between apps, and makes your intent obvious to anyone reading your symbols.

Learn more about access modifiers here.

Learn more about the Access property here.

Learn more about internalsVisibleTo in the app.json schema here.

Note: The code and information discussed in this article are for informational and demonstration purposes only. The Access property is available from runtime version 4.0.

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.