EventSubscriberInstance Property

Articolo
06/05/2016

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

Applies to

Codeunits.

Property Value

Value Description

Static-Automatic Subscribers are statically bound to events and the codeunit instances are controlled by the system. This is the default value.

Binding – Scope

All bindings are for the current tenant group. When NAV extensions are not used, tenant group 0 is used, which is the same as a static binding cross all current and future sessions in the system.

If the event subscription is part of a NAV extension, it will be a static binding cross all current and future sessions within the tenant group(s) that has the NAV extension installed and enabled. Note: With this setting, you cannot call the BINDSUBSCRIPTION Function or UNBINDSUBSCRIPTION Function for any events in this codeunit; otherwise, an error occurs.

Instances

All codeunit instances are controlled by the system. If the subscriber codeunit is defined as single instance (as specified by the SingleInstance Property), the first call to a subscriber function will create the instance and it will be kept for the lifespan of the session.

If the codeunit is not declared as single instance, a new instance will automatically be created just before the call to the subscriber function, and immediately disposed afterwards – each subscriber function call will be run on its own instance.

Manual Subscribers are bound to an event by calling the BINDSUBSCRIPTION function. This enables you to control which event subscriber instances are called when an event is raised. If the BINDSUBSCRIPTION function is not called, then nothing will happen when the event is raised.

Bindings – Scope

The binding of event subscribers to events is completely manual. To establish the binding, you must call the BINDSUBSCRIPTION function to pass an instance of a subscriber codeunit. Only then will the event subscriber functions be called.

You can stop (or unbind) the subscriber function calls by either calling the UNBINDSUBSCRIPTION function 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 function that declares the local variable. All bindings on the instance are automatically unbound.

Instances

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 are effectively creating a binding that lasts the whole session. However, it is still only bound for your session. Other sessions must also call BINDSUBSCRIPTION to establish the direct binding to the instance of the subscriber codeunit.

Important: If you are working in the Microsoft Dynamics NAV Development Environment on a production solution, be aware that with a manually bound subscriber function, you can experience a runtime error if the event subscriber object has been updated by an operation done in the development environment, such as recompiling the object. This causes the event subscription object's metadata to become stale and prevents the event subscriber function from being called. A message similar to the following 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.

Value	Description
Static-Automatic	Subscribers are statically bound to events and the codeunit instances are controlled by the system. This is the default value. Binding – Scope All bindings are for the current tenant group. When NAV extensions are not used, tenant group 0 is used, which is the same as a static binding cross all current and future sessions in the system. If the event subscription is part of a NAV extension, it will be a static binding cross all current and future sessions within the tenant group(s) that has the NAV extension installed and enabled. Note: With this setting, you cannot call the BINDSUBSCRIPTION Function or UNBINDSUBSCRIPTION Function for any events in this codeunit; otherwise, an error occurs. Instances All codeunit instances are controlled by the system. If the subscriber codeunit is defined as single instance (as specified by the SingleInstance Property), the first call to a subscriber function will create the instance and it will be kept for the lifespan of the session. If the codeunit is not declared as single instance, a new instance will automatically be created just before the call to the subscriber function, and immediately disposed afterwards – each subscriber function call will be run on its own instance.
Manual	Subscribers are bound to an event by calling the BINDSUBSCRIPTION function. This enables you to control which event subscriber instances are called when an event is raised. If the BINDSUBSCRIPTION function is not called, then nothing will happen when the event is raised. Bindings – Scope The binding of event subscribers to events is completely manual. To establish the binding, you must call the BINDSUBSCRIPTION function to pass an instance of a subscriber codeunit. Only then will the event subscriber functions be called. You can stop (or unbind) the subscriber function calls by either calling the UNBINDSUBSCRIPTION function 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 function that declares the local variable. All bindings on the instance are automatically unbound. Instances 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 are effectively creating a binding that lasts the whole session. However, it is still only bound for your session. Other sessions must also call BINDSUBSCRIPTION to establish the direct binding to the instance of the subscriber codeunit. Important: If you are working in the Microsoft Dynamics NAV Development Environment on a production solution, be aware that with a manually bound subscriber function, you can experience a runtime error if the event subscriber object has been updated by an operation done in the development environment, such as recompiling the object. This causes the event subscription object's metadata to become stale and prevents the event subscriber function from being called. A message similar to the following 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.`

Remarks

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 cannot 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.

For more information about events, see Events in Microsoft Dynamics NAV.

Condividi tramite

EventSubscriberInstance Property

Applies to

Property Value

Remarks

See Also

Risorse aggiuntive