Events Subscriptions in Business Central

In Business Central, event subscriptions allow extensions to hook into core application logic, enabling customization without modifying base code. The publisher declares an event at an occurrence in the application. An event publisher method has a signature only and doesn’t execute any code. The publisher exposes an event to subscribers, providing them with a hook into the application. A subscriber listens for and processes a published event. When an event is triggered, the subscriber method is executed, and its code runs.

However, there are scenarios where you need more granular control over when and how these subscriptions are active—such as in background sessions, conditional logic, or performance-optimized codeunits. I have seen many instances and creative ways in which developers have tried to determine when their even subscription code is executed selectively.

Binding Subscriptions

The need to selectively execute subscriber event code is where the Session.BindSubscription and Session.UnbindSubscription procedures come into play, offering dynamic binding of event subscribers at runtime. These methods let you attach or detach codeunit instances containing event subscribers to the current session programmatically. Binding subscriptions is particularly useful when they should apply only in specific contexts. In this post, we’ll explore binding subscriptions, including the important EventSubscriberInstance property on Codeunits.

For a complete code sample, check out this sample on GitHub.

The EventSubscriberInstance Property

The EventSubscriberInstance property on a Codeunit specifies how event subscriber functions in a Codeunit are bound to the Codeunit instance and the events that they subscribe to. There are two options:

StaticAutomatic: Subscribers are automatically bound to the events that they subscribe to.

Manual: Subscribers are bound to an event only if the BindSubscription method is called from the code that raises the event.

The default property value is StaticAutomatic. When the property value is set to StaticAutomatic, the code in the event subscribers in the Codeunit will always execute. When the property is set to Manual, the code will only execute when the Session is bound to the codeunit.

What Are Session.BindSubscription and Session.UnbindSubscription?

Session.BindSubscription and Session.UnbindSubscription are methods on the Session data type that allow runtime management of event subscribers. At their core:

BindSubscription: Attaches a Codeunit instance containing event subscribers to the current session, making the subscribed events active immediately.
UnbindSubscription: Detaches the Codeunit instance, pausing event handling until rebound.

Dynamic binding gives you control over the lifecycle by limiting active subscribers. The EventSubscriberInstance property is central here—it’s a property set on the subscriber codeunit itself. When set to Manual, it allows the codeunit to be bound and unbound dynamically. This property must be set to Manual for BindSubscription and UnbindSubscription to work; otherwise, an error occurs.

How Session Subscription Binding Works

Under the hood, Business Central sessions maintain a registry of active event subscribers. When you call BindSubscription, the system registers the codeunit instance in the current session’s event queue, allowing it to receive and process published events. UnbindSubscription removes it from the queue, effectively pausing it. Bindings are automatically removed when the codeunit instance goes out of scope (e.g., end of a procedure), but explicit unbinding allows for earlier cleanup. Key mechanics:

• • Binding happens synchronously in the current session.
  • Events published after binding will trigger the subscriber’s method.
  • Unbinding is also immediate, but any in-flight events may still process.
  • The EventSubscriberInstance property set to Manual ensures the subscribers are not automatically bound.
  • Bindings are session-specific and static from the publisher’s perspective: once bound, all publisher instances trigger the subscribers.

This approach integrates seamlessly with Business Central’s event model, supporting publishers from base app Codeunits to custom extensions.

Creating and Using Dynamic Subscriptions

In this sample, two new actions will be added to the customer list that display the Customer Card for the selected record. One action will have a bound event that displays ‘Hello World,’ and the other will display the card without the event.

To get started, you’ll need to:

1. Create a Codeunit and set the  EventSubscriberInstance property to Manual.
2. In the Codeunit, create the Event Subscriber method.
3. In the code where you’d like to enable the events in the Codeunit, create a variable for the Codeunit.
4. In the place where you’d like the events to become active, call the Session.BindSubscription method, with the Codeunit variable as the parameter.
5. Trigger events to test.
6. When done, call the SessionUnbindSubscription method, passing the Codeunit variable as the parameter to explicitly remove the event binding.

codeunit 50130 "DVLPR Subscription Management"
{
    EventSubscriberInstance = Manual;

    [EventSubscriber(ObjectType::Page, Page::"Customer Card", 'OnOpenPageEvent', '', false, false)]
    local procedure OnOpenPageCustomerCard()
    begin
        Message('Hello world');
    end;
}

codeunit 50131 "DVLPR BindSubscription Example"
{
    procedure OpenCustomerCard(Rec: Record "Customer")
    var
        CustomerCardPage: Page "Customer Card";
    begin
        CustomerCardPage.SetRecord(Rec);
        CustomerCardPage.RunModal();
    end;

    procedure OpenCustomerCardBinding(Rec: Record "Customer")
    var
        SubscriptionManagement: Codeunit "DVLPR Subscription Management";
        CustomerCardPage: Page "Customer Card";
    begin
        Session.BindSubscription(SubscriptionManagement);
        CustomerCardPage.SetRecord(Rec);
        CustomerCardPage.RunModal();
        Session.UnbindSubscription(SubscriptionManagement);
    end;
}

Wrapping Up

Dynamic subscription binding with Session.BindSubscription, Session.UnbindSubscription and setting the EventSubscriberInstance property to Manual unlocks finer control over AL event handling, making your extensions more efficient and adaptable. Whether optimizing background jobs or implementing conditional customizations, these tools are essential for modern Business Central development.

For the full sample, visit GitHub.

What Is A Page Background Task In Business Central?

A Page Background task is a technique for enhancing performance in Business Central. This method allows us to execute lengthy or resource-intensive reading processes asynchronously in the background without disrupting the user interface. Page Background tasks speed up page load times; as a result, users can continue their work while operations are carried out in the background. This approach helps create faster and more responsive pages in Business Central, leading to a better user experience. Typical places where you might use background tasks are on cues and pages in FactBoxes or statistical pages that show many totals.

If you want to jump to the code sample on GitHub go here.

How Page Background Tasks Work

When a page is opened in the client, a session is established between the Page and the Business Central Server instance. This session can be considered the parent session. As users interact with the Page, they may encounter lengthy calculations that prevent them from continuing until the calculations are completed. A Page Background task operates as a child session that executes processes from a codeunit in the background. While this task is running, the user can continue working on the Page. The key difference is that when the background process finishes, the child session ends, and the parent session is notified of the task’s results. Subsequently, the client will handle these results on the Business Central Server instance.

Characteristics of a Background Task

• It can only perform read-only operations and cannot write to or lock the database.
• It operates on the same Business Central Server instance as the parent session.
• The parameters passed to and returned from the Page Background task are in the form of a Dictionary of [Text, Text].
• The callback triggers are limited to executing UI operations related to notifications and control updates.
• If the calling page or session is closed or if the current record is changed, the background task will be canceled.
• There is a default and maximum timeout for Page Background tasks, which will also result in automatic cancellation.
• The background task runs independently from the parent session. Aside from completion and error triggers, it cannot communicate back to the parent session.
• Page Background tasks do not count towards the license calculation.
• You can have multiple background sessions running for a parent session.

Creating a Page Background task

You create a codeunit, the child, to run the computations you want in the background. You’ll also have to include code that collects the results of computations and passes them back to the calling page for handling.
The background task Codeunit is a standard Codeunit with the following characteristics:

• The OnRun() trigger is invoked without a record.It can’t display any UI.
• It can only read from the database, not write to the database.
• Casting must be manually written in code by using Format() and Evaluate() methods.

In the Codeunit, you call the Page.GetBackgroundParameters procedure to read the parameter dictionary that was passed when enqueuing the task. The Page.SetBackgroundTaskResult procedure is used to set the page background task result as a dictionary. 

procedure GetBackgroundParameters(): Dictionary of [Text, Text]
procedure SetBackgroundTaskResult(Results: Dictionary of [Text, Text])

You create a page, the parent, that tells Business Central to start a child session. The parent signals the start of the background task with the CurrPage.EnqueueBackgroundTask. The codeunit to run and its parameters are passed to the x. BusinessCentral will assign a TaskID to the var parameter, which can be used for tracking purposes.

local procedure EnqueueBackgroundTask(var TaskId: Integer, CodeunitId: Integer, var [Parameters: Dictionary of [Text, Text]], [Timeout: Integer], [ErrorLevel: PageBackgroundTaskErrorLevel]): Boolean

When the child session completes, it uses the OnPageBackgroundTaskCompleted trigger to signal the parent page that it is done. Any information that the child Codeunit needs to pass back to the parent is passed in a ‘Result‘ Dictionary of [Text.Text].

local trigger OnPageBackgroundTaskCompleted(TaskId: Integer, Results: Dictionary of [Text, Text])

Example Page Background Task

In a  Business Central environment, companies often have millions of records across core tables, for example:

• Master data: Customer, Vendor, Item, G/L Account
• Transactional data: G/L Entry, Item Ledger Entry, Value Entry, Customer Ledger Entry, Vendor Ledger Entry

Suppose you need to create a simple Role Center page that shows the total count of records in each of these tables. Most developers will add code to the OnAfterGetRecord or OnOpenPage trigger using the TableName.COUNT() procedure, which will execute all counts sequentially on the client session. On a large database this can easily take 10–30 seconds or more, during which the page appears frozen — a classic user-experience complaint.

1. Create a Page Background Task Codeunit to count the records in the table specified in a background parameter.

       trigger OnRun()
       var
           RecordRef: RecordRef;
           Result: Dictionary of [Text, Text];
           TableNo: Integer;
       begin
           if not Evaluate(TableNo, Page.GetBackgroundParameters().Get('TableNo')) then
               Error('TableNo parameter is missing or invalid');
   
           RecordRef.Open(TableNo);
           Result.Add('Count', Format(RecordRef.Count, 0, 9));
           Result.Add('TableNo', Format(TableNo));
           RecordRef.Close();
   
           Page.SetBackgroundTaskResult(Result);
       end;

2. Perform the calculation, then set the result.
3. Create a page that displays record count information for Cues, which can be added to a RoleCenter.

   page 50121 "DVLPR Cue Activities"
   {
       Caption = 'Background Activities';
       PageType = CardPart;
       RefreshOnActivate = true;
       ShowFilter = false;
   
       layout
       {
           area(content)
           {
               cuegroup(MasterRecords)
               {
                   Caption = 'Master Records';
                   field(CountCustomers; this.CustomerCount)
                   {
                       ApplicationArea = Basic, Suite;
                       Caption = 'Customers';
                       ToolTip = 'Specifies the total number of customer records.';
                       BlankZero = true;
                   }
               }
               cuegroup(Transactions)
               {
                   Caption = 'Transactional Counts';
                   field(CountCustomerLedgerEntries; this.CustomerLedgerEntryCount)
                   {
                       ApplicationArea = Basic, Suite;
                       Caption = 'Customer Ledger Entries';
                       ToolTip = 'Specifies the total number of customer ledger entries.';
                       BlankZero = true;
                   }
               }
           }
       }
   
       trigger OnAfterGetCurrRecord()
       begin
           this.CountLedgerEntries();
       end;
   
       var
           CustomerCount: Integer;
           CustomerLedgerEntryCount: Integer;
   
       local procedure CountLedgerEntries()
       var
           Parameters1,
           Parameters2 : Dictionary of [Text, Text];
           TaskId: Integer;
       begin
           Parameters1.Add('TableNo', Format(Database::Customer));
           CurrPage.EnqueueBackgroundTask(TaskId, Codeunit::"DVLPR Background Cues", Parameters1);
   
           Parameters2.Add('TableNo', Format(Database::"Cust. Ledger Entry"));
           CurrPage.EnqueueBackgroundTask(TaskId, Codeunit::"DVLPR Background Cues", Parameters2);
   
       end;
   
       trigger OnPageBackgroundTaskCompleted(TaskId: Integer; Results: Dictionary of [Text, Text])
       var
           TableNo: Integer;
       begin
           if not Evaluate(TableNo, Results.Get('TableNo')) then
               Error('TableNo result is missing or invalid');
   
           case TableNo of
               Database::Customer:
                   if Results.ContainsKey('Count') then
                       Evaluate(this.CustomerCount, Results.Get('Count'));
               Database::"Cust. Ledger Entry":
                   if Results.ContainsKey('Count') then
                       Evaluate(this.CustomerLedgerEntryCount, Results.Get('Count'));
           end;
       end;
   
       trigger OnPageBackgroundTaskError(TaskId: Integer; ErrorCode: Text; ErrorText: Text; ErrorCallStack: Text; var IsHandled: Boolean)
       begin
           // Handle errors here
       end;

4. On the Page, EnqueueBackground tasks to spawn children that will count the records in each table.
5. Specify code in the OnPageBackgroundTaskCompleted trigger to update the values as each child task returns them.
6. Specify error handling for the child tasks in the OnPageBackgroundTaskError trigger.

Note: The code and information discussed in this article are for informational and demonstration purposes only. This content was created referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online.

A full listing of the sample code may be found on GitHub here.