InstanceDestruction

Metreos.ApplicationControl.InstanceDestruction

Summary

The InstanceDestruction event is fired whenever the Application Runtime Environment destroys an instance of a script.

Usage

The InstanceDestruction event is provided for developers to execute logic which is needed immediately before an instance is unloaded. Because scripts can end in any number of locations due to EndScript usage, Forward usage, application unloading, and by unexpected errors causing script crashes, the InstanceDestruction script is an ideal way to ensure that any resources that need to be cleaned deterministically occur. A good analogy to help understand InstanceDestruction is the try/catch/finally pattern, where scripts are the code in the try block, application crashes occur in the catch block, and the finally block corresponds to the code in the InstanceDestruction-triggered script.

The InstanceDestruction event provides the ErrorCode and ErrorText event parameters to indicate under what circumstances did the script instance unload.

Implementing the InstanceDestruction event is completely optional.

Remarks

InstanceDestruction occurs whenever a script is ended with EndScript, Forward, abnormal exit due to unhandled exception or script error, or if the application server is unloading the application. Refer to ErrorCode regarding more information on specific reasons for script instance termination.

The InstanceDestruction event handler has up to 30 seconds to finish, by default. This amount is configurable on an application server-wide basis.

If an application is being unloaded due to the application server service stopping or if the application is being uninstalled, the script has excecution stopped immediately and then the InstanceDestruction event handler is executed.

Event Parameters
Parameter Name.NET TypeDescription
ErrorCodeSystem.Int32
0

Is caused by use of EndScript. Corresponds to Normal.

1

Is caused by use of Forward. Corresponds to Forwarded

2

Is caused by the application being unloaded, which can be due to uninstallation of the application or if the application server is being shutdown. Corresponds to Shutdown.

3

Is caused by the application terminating due to an unexpected error in a native action, type, custom code, or other Application Runtime Environment error. Corresponds to Exception.

4

Is caused by the application terminating due to a script error, such as an branch condition being returned by an action which was not defined in the script at design time. Corresponds to ScriptError.

ErrorTextSystem.StringAn error message describing the specific reason that the application ended.