Within this tutorial, you will learn how to hook into the Umbraco V9 event pipeline. Whenever a content editor logs into the Umbraco backend and performs certain actions, in the background events are triggered. As a developer, it is possible to hook into these events. By hooking into these events, you can trigger some custom code of your choice to run. This type of feature can be really handy when you need to introduce some new capability to Umbraco that is not provided out-of-the-box. In these situations, you will need to master event handling and this is the tutorial that will teach you exactly that 🔥🔥🔥
The first thing I should point out is that events have been rebranded in Umbraco V9. We are now meant to call event handling, notifications. I am not sure why events have been renamed. To me personally, it is conceptually easier to think about and discuss event handling as its a known software engineering technique. When it comes to notification handling within Umbraco, from my experience 90% of the time you will either want to hook into the content saving, published or publishing event.
As you would expect, Umbraco exposes these types of 'notifications'`, as well as many more. It may shock you that Umbraco exposes over 40 notifications for you to pick from 😱. You can see a full list of all the available notifications that ships with Umbraco over at Github. If you look at this list, you can see how it gets on.
Registering A Notification Handler
In order to hook into the notification pipeline, you will need to register a notification handler with Umbraco. This is done via a Umbraco composer. Composers first made an appearance in Umbraco V8, so they are not new. Any composer that is added within a Umbraco project, will be triggered whenever the application is started. To create one, all you need to do is create a class, implement the IComposer interface and implement the void Compose(IUmbracoBuilder builder) method like this:
Within a composer, you will get access to the builder parameter. Using this parameter, you can access the AddNotificationHandler<T, T> handler. To register a custom notification handler, you define the notification that you want to hook into as the first T and your custom notification handler as the second T.
A notification handler is very easy to create. Create a new C# class and implement it from INotificationHandler<T>. Use the notification you declared within the composer as T. Thie notification type needs to marry up between the composer and the notification handler, otherwise, you will encounter an error. The skeleton code to create a notification handler is shown below:
In order to get some of your own custom code to trigger whenever a related notification is triggered from the CMS, you will need to implement the void Handle(T notification) method. This method contains one argument. The argument type will be the type you used for T in the class declaration. From this argument, you can get access to the item(s) that triggered the event. You can get this data from within a property called something like SavedEntities. The exact property that you will need to access, will vary depending on which 'notification' you are hooking into. You are a smart cookie, I am confident you will find it obvious which property you need to target 🍪 Even though the item that triggered the notification might be a single page, the argument will expose the data via a collection. You need to iterate through this collection in order to access the content:
This will give you access to the related item as IContent item. Through this item, you can then perform do what you need to. You could update content, media and member data, using methods like GetValue() and SetValue().
You are now a Umbraco notification guru 🧘🧘🧘. You now have the power to customise the Umbraco backend to your little heart's desire ❤️. As you can see it is very easy to set up and hook into Umbraco events. Happy Coding 🤘
