Edit

Share via

EventSubscriberInstance Property

  • Article

Version: Available or changed with runtime version 1.0.

Specifies how event subscriber functions in a codeunit are bound to the codeunit instance and the events that they subscribe to.

Applies to

  • Codeunit

Property value

Value Available or changed with Description
StaticAutomatic runtime version 1.0 Subscribers are automatically bound to the events that they subscribe to.
Manual runtime version 1.0 Subscribers are bound to an event only if the BINDSUBSCRIPTION method is called from the code that raises the event.

Syntax

EventSubscriberInstance = StaticAutomatic|Manual;

Remarks

StaticAutomatic is the default value for this property. The bindings are always considered static on the event publisher side. For example, if you bind instance A of a given subscriber codeunit, all instances of publisher application objects will start calling the event subscribers. You can't design it so that a specific instance of publisher table X calls only a specific instance of subscriber codeunit A. You can, however, achieve the same by using/storing some global state on the subscriber.

StaticAutomatic binding

If the subscriber codeunit is defined as single instance (as specified by the SingleInstance Property), the first call to an event subscriber creates in instance of the codeunit. This instance is kept for the lifespan of the session.

If the codeunit isn't declared as single instance, each event subscriber will be run in its own codeunit instance. When an event gets raised, a codeunit instance is created for each event subscriber method that subscribes to the event. The individual codeunit instances are immediately disposed after its event subscriber is run.

Note

With this setting, you can't call the BindSubscription method or UnBindSubscription method for any events in this codeunit; otherwise, an error occurs.

Manual binding

This setting enables you to control which event subscriber instances are called when an event is raised. With this setting, you can essentially activate event subscribers on demand. If the BindSubscription method isn't called, then nothing will happen when the event is raised.

The binding of event subscribers to events is manual. To establish the binding, you must call the BindSubscription method to pass an instance of an event subscriber codeunit. Only then will the event subscribers be called.

You stop the event subscriber calls by either calling the UnBindSubscription method or by letting the previously bound instance go out of scope. For example, you declare a local variable, call BindSubscription, and then eventually exit the method that declares the local variable. All bindings on the instance are automatically unbound.

By controlling the instance of the subscriber codeunit, you control the lifespan. If you store the instance on a single instance codeunit global variable, you're effectively creating a binding that lasts the whole session. However, it's still only bound for the current session. Other sessions must also call BindSubscription to establish the direct binding to the instance of the subscriber codeunit.

Important

When you develop on a production solution, you can experience a runtime error if the event subscriber codeunit has been updated by a development operation. For example, you recompiled the codeunit. This situation causes the event subscription codeunit's metadata to become stale and prevents the event subscriber from being called. A message similar to the following message appears in the event log:

A manually bound event subscriber is stale and will no longer be called. This can be caused by the subscriber object being updated by an operation in the development environment.

Example

This code example uses the EventSubscriberInstance property to manually bind an event subscriber to an event. The example uses events to display a message to the user if they use a '+' sign in the Address field on the Customer Card page.

The following code creates codeunit that publishes the OnAddressLineChanged event.

codeunit 50100 MyPublishers
{
    [IntegrationEvent(false, false)]
    procedure OnAddressLineChanged(line: Text[100])
    begin
    end;
}

The following code declares the CheckAddressLine event subscriber in the event subscriber codeunit 50101 MySubscribers. The event subscriber displays a message in the client when '+' is used in the Address field.

codeunit 50101 MySubscribers
{
    //Set the event subscribers to manual binding;
    EventSubscriberInstance = Manual;

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"MyPublishers", 'OnAddressLineChanged', '', true, true)]
    procedure CheckAddressLine(line: Text[100])
    begin
        if (STRPOS(line, '+') > 0) then begin
            MESSAGE('Can''t use a plus sign (+) in the address [' + line + ']');
        end;
    end;
}

The following code extends the Customer Card page to raise the OnAddressLineChanged event when the Address field is changed:

pageextension 50100 MyCustomerExt extends "Customer Card"
{
    layout
    {
        modify(Address)
        {
            trigger OnBeforeValidate();
            var
                Publisher: Codeunit MyPublishers;
                Subscriber: Codeunit MySubscribers;
            begin
                // Bind the event to the MySubscribers codeunit
                BindSubscription(Subscriber);

                // Raise the event
                Publisher.OnAddressLineChanged(Address);
            end;
        }
    }
}

On the event publisher side, the bindings are always considered static. For example, if you bind instance A of a given subscriber codeunit, all instances of publisher application objects will start calling the event subscribers. You can't design it so that a specific instance of publisher table X calls only a specific instance of subscriber codeunit A. However, you can achieve the same by using/storing some global state on the subscriber.

BindSubscription Method
UnBindSubscription Method
Publishing Events
Raising Events
Subscribing to Events