In the blogpost series of Tridion Custom Tools Example Projects, this blog covers the Event Handler Extension. The Example Code Project could be found here on GIT. I've also shared the Visual Studio Extension here, If you want to install the project template in visual studio for event handler.
An Event Handler is a piece of functionality
that is triggered when a certain type of event happens to a certain Content
Manager item, for example when a Component being saved.
In Technical terms, It is a .NET assembly that uses the Event
System to hook into events occurring in the Content Manager.The Event System is part of the TOM.NET (.NET Tridion Object Model) API.
To create an Event Handler, create a class that extends Tridion.ContentManager.Extensibility.TcmExtension. You then need to compile your Event Handler into
an assembly (DLL) and register it.
Procedure (Copied From SDL Documentation)
- In Visual Studio,
create a class that extends Tridion.ContentManager.Extensibility.TcmExtension. This class must
have a unique class attribute, say,
[TcmExtension("MyUniqueEventHandlerExtension")].
- 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 classTridion.ContentManager.Extensibility.TcmEventArgs or any of its subclasses.
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. 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.
- 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) by 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.
- 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
- Compile your class
to a .NET assembly.
Note: If your
event code contains a bug that raises an exception, it can cause the event that
triggered it to hang. Especially if your event code is likely to be triggered
very often, this can easily cause the system to freeze. Always test your event
code before deploying it.
- Open the
configuration file called Tridion.ContentManager.config, located in the config/ subfolder of
%TRIDION_HOME% (defaults to C:\Program
Files (x86)\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>
- Save and close Tridion.ContentManager.config.
- Restart the services you stopped.
