Custom Handler Library 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.