Backward-Compatible Event Handler

Represents a server-side code routine that is called when registered events occur within a SharePoint document library. Backward-compatible event handlers can be attached to and have the scope of a document library only.

Real World Example

A business process site based on Microsoft Office SharePoint Portal Server 2003 has a requirement that whenever a new document is added to a specific forms library, it should initiate the creation of a Web site inside the site collection. An event handler is registered to trigger on “new item created” events that call a routine that examines the added Microsoft Office InfoPath XML form for information that is used to create an SPWeb object in the current site collection. The event handler must still function after the site is upgraded to Microsoft Office SharePoint Server 2007.

Technical Details

In earlier versions of SharePoint Products and Technologies, event handlers were configured only for document libraries and had to be allowed at the Web application level first. In the current SharePoint Products and Technologies there are many other scopes for event handlers, and the method supported in earlier versions of SharePoint Products and Technologies is now known as a “backward-compatible” event handler.

Backward-compatible event handlers require installation on the server either in the global assembly cache or the Web applications \bin directory, and the Web application must be set to allow backward-compatible event handlers from the Web Application General Settings page (_admin/vsgeneralsettings.aspx) within the Central Administration Web site. This setting allows any document library within that Web application to now be bound to a backward-compatible event handler. Each document library must be bound individually to a backward-compatible event handler by setting the event handler assembly and calling parameters within the advanced settings of the specific document library.

Support Details

Because backward-compatible event handlers are available only to support legacy code, any new environment should avoid their use. Use the new form of event handler code instead, and convert legacy code to the new model when possible.

Backward-compatible event handlers introduce risks to an environment’s performance similar to those of the newer event handler model. This can be especially obvious if the event handler calls a moderately long-running operation that is triggered by such events as a document update when used in conjunction with a heavily updated document library.