Creating an Event Handler

About this task

This topic explains how to create an Event Handler, that is, a piece of functionality triggered when a certain type of event happens to a certain type of Content Manager item. It also explains what to do with your Event Handler once you have compiled it to an assembly (DLL).

You can implement very narrowly defined Event Handlers: for example, if the trigger is the creation of a Component, you can associate the Component with a specific Component Template, put the resulting Component Presentation on a Page you create for this purpose, and publish the Page. But you can also implement very broadly defined Event Handlers: for example, you can log any action performed on the Content Manager to a back office as part of preserving an audit trail.

Procedure

  1. In Visual Studio, create a class that extends Tridion.ContentManager.Extensibility.TcmExtension. You can find an example of such a class in Event Handler example.
  2. In the constructor of this class, execute code that subscribes to one or more events using the following methods:
    SubscribeAsync
    Subscribe asynchronously to an event. Select this method if your Event Handler code does not affect the data being handled in the Content Manager. For example, if your Event Handler saves data to a backup system or a log file, you can select this method.
    Subscribe
    Subscribe synchronously to an event. Select this method if your Event Handler code changes the data being handled. For example, if your Event Handler analyzes a Component and then adds metadata to it, ensure that you select this method.

    Both methods have the following signatures:

    Subscribe<TSubject, TEvent>(TcmEventHandler<TSubject, TEvent> eventHandler, EventPhases phases, EventSubscriptionOrder order)
    SubscribeAsync<TSubject, TEvent>(TcmEventHandler<TSubject, TEvent> eventHandler, EventPhases phases, EventSubscriptionOrder order)

    where the parameters mean the following:

    TSubject (type parameter)
    This is the type(s) of the object you are checking events for. This can be any item of class Tridion.ContentManager.IdentifiableObject or any of its subclasses, which includes any kind of content item (such as Component, Schema or Target Group), organizational item (such as Folder or Structure Group) or system-wide object (such as User or Group).
    TEvent (type parameter)

    This indicates the type(s) of event that trigger this code if applied to an item of the object type specified in TSubject. This can be any event of class Tridion.ContentManager.Extensibility.TcmEventArgs or any of its subclasses. You can find an overview of the hierarchy in Event hierarchy.

    TcmEventHandler<TSubject, TEvent> eventHandler
    The name of the method that contains the code you want to be triggered when the event occurs. This method should be contained in the same class and should have parameters that are the same as the type parameters of this Subscribe or SubscribeAsync method.
    EventPhases phases

    The exact moment during the event at which the event code should be triggered. These moments are listed in Event phases. Note that this parameter is an enum with FlagsAttribute, meaning that you can select multiple moments, which in turn means that a single event could trigger the same code multiple times.

    EventSubscriptionOrder order
    This optional parameter specifies when the event code should be executed if the same event triggers multiple Event Handlers. This is explained in Event subscription order.
  3. Now, in the same class, implement your event code in a method with the name specified in the eventHandler parameter of the Subscribe or SubscribeAsync method. In this method, you can perform any action you wish, including any type of querying, modification or other manipulation of items in the Content Manager. Include any namespace you need to access these items.

    When you write this code, note the following:

    • You can make changes to the members of the TEvent parameter (the members are different depending on the event type). This is explained in Exchanging information between Event Handlers.
    • When executed, the code you write may result in other event code being triggered.
    • From your event handling method, you can identify the specific user who triggered the event through the Session property of your first parameter of type <TSubject>. For example, if your method has a signature HandlerForSave(Component subject, SaveEventArgs args, EventPhases phase), get the name of the user by checking subject.Session.User.Title.
  4. Once you are satisfied with your code, shut down the following services on your Content Manager server:
    • IIS
    • Any Tridion-related COM+ services
    • If your code is related to publishing, the Publisher service of SDL Tridion
  5. Compile your class to a .NET assembly.
  6. Open the configuration file called Tridion.ContentManager.config, located in the config/ subfolder of the Content Manager root location (typically C:\Program Files\Tridion\), in a plain-text or XML editor. Find the extensions element in this file. If the element is empty (that is, if it reads <extensions/>), replace it with <extensions></extensions>. Then add a line of the following format:
    <add assemblyFileName="C:\Projects\Events\MyCustomEventHandlerExample\bin\Debug\MyCustomEventHandler.dll" />

    where MyCustomEventHandler.dll is the full path and name of your compiled class. If the element was empty, the fragment should now read:

    <extensions>
     <add assemblyFileName="C:\Projects\Events\MyCustomEventHandlerExample\bin\Debug\MyCustomEventHandler.dll" />
    </extensions>
  7. Save and close Tridion.ContentManager.config.
  8. Restart the services you stopped.

Results

Your Event Handler is now running and responds to the types of events you specified as triggers.