Custom Handler Library compatibility


This article addresses differences between the old method of defining custom event handlers using Custom Event Handler Libraries, and the new method of using the App_Code class and the extent of the backward compatibility.

Since Kentico CMS v6, a new method of defining Custom Event Handlers has been introduced, a complete description can be found in the event handlers article.

The old method of using a Custom Event Handler Library project has since been rendered obsolete but basic backwards compatibility has been preserved. The most noticeable difference is that some events may not trigger the handlers they used to, as they are no longer associated with them. For example, saving a document will no longer trigger methods in CustomDataHandler, but only those in the CustomTreeNodeHandler. This is due to a different event association.

An old Custom Event Handler is now called when a related new event handler has been triggered. For example OnBeforeInsert in the CustomTreeNodeHandler will only trigger when DocumentEvents.Insert.Before event has been triggered. This table contains a complete list of all event associations:

Library Handler App_Code Handler
CustomTreeNodeHandler.OnBeforeInsert DocumentEvents.Insert.Before
CustomTreeNodeHandler.OnAfterInsert DocumentEvents.Insertfter 
CustomTreeNodeHandler.OnBeforeInsert DocumentEvents.InsertLink.Before
CustomTreeNodeHandler.OnAfterInsert DocumentEvents.InsertLink.After
CustomTreeNodeHandler.OnBeforeInsertNewCultureVersion DocumentEvents.InsertNewCulture.Before
CustomTreeNodeHandler.OnAfterInsertNewCultureVersion DocumentEvents.InsertNewCulture.After
CustomTreeNodeHandler.OnBeforeUpdate DocumentEvents.Update.Before
CustomTreeNodeHandler.OnAfterUpdate DocumentEvents.Update.After
CustomTreeNodeHandler.OnBeforeDelete DocumentEvents.Delete.Before
CustomTreeNodeHandler.OnAfterDelete DocumentEvents.Delete.After
CustomTreeNodeHandler.OnBeforeCopy DocumentEvents.Copy.Before
CustomTreeNodeHandler.OnAfterCopy DocumentEvents.Copy.After
CustomTreeNodeHandler.OnBeforeMove DocumentEvents.Move.Before
CustomTreeNodeHandler.OnAfterMove DocumentEvents.Move.After
CustomDataHandler.OnBeforeInsert ObjectEvents.Insert.Before
CustomDataHandler.OnAfterInsert ObjectEvents.Insert.After
CustomDataHandler.OnBeforeUpdate ObjectEvents.Update.Before
CustomDataHandler.OnAfterUpdate ObjectEvents.Update.After
CustomDataHandler.OnBeforeDelete ObjectEvents.Delete.Before
CustomDataHandler.OnBeforeDelete ObjectEvents.Delete.After
CustomDataHandler.OnAfterDelete ObjectEvents.GetContent.Execute
CustomDataHandler.OnGetContent DocumentEvents.GetContent.Execute
CustomSecurityHandler.OnAuthentication SecurityEvents.Authenticate.Execute
CustomSecurityHandler.OnClassNameAuthorization SecurityEvents.AuthorizeClass.Execute
CustomSecurityHandler.OnResourceAuthorization SecurityEvents.AuthorizeResource.Execute
CustomSecurityHandler.OnUIElementAuthorization SecurityEvents.AuthorizeUIElement.Execute
CustomSecurityHandler.OnFilterDataSetByPermissions DocumentEvents.FilterDataSetByPermissions.Execute
CustomSecurityHandler.OnTreeNodeAuthorization DocumentEvents.AuthorizeDocument.Execute
CustomExceptionHandler.OnException SystemEvents.Exception.Execute
CustomWorkflowHandler.OnBeforeApprove WorkflowEvents.Approve.Before
CustomWorkflowHandler.OnAfterApprove WorkflowEvents.Approve.After
CustomWorkflowHandler.OnBeforeCheckIn WorkflowEvents.CheckIn.Before
CustomWorkflowHandler.OnAfterCheckIn WorkflowEvents.CheckIn.After
CustomWorkflowHandler.OnBeforeCheckOut WorkflowEvents.CheckOut.Before
CustomWorkflowHandler.OnAfterCheckOut WorkflowEvents.CheckOut.After
CustomWorkflowHandler.OnBeforePublish WorkflowEvents.Publish.Before
CustomWorkflowHandler.OnAfterPublish WorkflowEvents.Publish.After
CustomWorkflowHandler.OnBeforeReject WorkflowEvents.Reject.Before
CustomWorkflowHandler.OnAfterReject WorkflowEvents.Reject.After

It is not recommended to use the old custom handler libraries and try to re-implement them as Custom Global Event Handlers in App_Code as soon as possible. The handler libraries are only supported for backwards compatibility and may be removed completely in future Kentico versions.

In general, you should encounter no problems moving your code from the Custom Handler Library to the App_Code handler class, however there are some differences which need to be addressed by your code.  The most significant change had been made to the event arguments passed to the handler. In the Event Handler Library, the arguments were anonymous objects which had to be typecast as IDataClass in order to be used. The new handlers receive strongly typed argument <Handler type>EventArgs e containing either TreeNode e.Node or BaseInfo e.Object with all data related to the object tied to the event. Even though the typecasting of these properties is no longer necessary to access contained information, it is possible to typecast both of them as IDataContainer, as an alternative to the IDataClass. However this is not a recommended practice and should be avoided when possible. You can find more detailed description of which handler class accepts which EventArgs class in the article linked above.




Share this article on   LinkedIn

Josef Dvorak

Hello, I am a Solution Architect with Kentico. My primary focus is the E-Commerce module, however it is not uncommon for me to help with other modules as well.