Umbraco uses Notifications (similar to the Observer pattern) to allow you to hook into the workflow process for the backoffice. For example, notifications allow you to execute some code every time a page is published.

Notifications

All notifications reside in the Umbraco.Cms.Core.Notifications namespace and are postfixed with Notification.

Available notifications typically exist in pairs, with "before" and "after" notifications. For example, the ContentService class has the concept of publishing and published notifications. So, there is both a ContentPublishingNotification and a ContentPublishedNotification notification.

The notification to use depends on what you want to achieve. If you want to be able to cancel the action, you would use the CancelOperation method on the "before" notification. See the sample in ContentService Notifications. If you want to execute some code after the publishing has succeeded, then you would use the "after" notification.

Registering Notifications

Check the Notification Handler article to learn more about notification handlers lifetime, async notification handler and how to register the notification handlers.

List of Notifications

Below you can find a list of most used object notifications.

You can find a list of all supported notifications in the API Docs.

Content, Media, and Member notifications

Other notifications

Tree notifications

See Tree Notifications for a list of the tree notifications.

Editor Model Notifications

See EditorModel Notifications for a list of the EditorModel events.

Creating and publishing your own custom notifications

Umbraco uses notifications to allow people to hook into different workflow processes. This notification pattern is extensible, allowing you to create and publish custom notifications, and other people to observe and hook into your custom processes. This approach can be useful when creating Umbraco packages. For more information on how you create and publish your own notifications, see the creating and publishing notifications article.

Samples

Below you can find some articles with some examples using Notifications.

• CacheRefresher Notification

• ContentService Notifications

• Determining if an entity is new

• Hot vs. cold restarts

• MediaService Notifications

• MemberService Notifications

• Sending Allowed Children Notification

• Umbraco Application Lifetime Notifications

Creating And Publishing Custom Notifications

There may be many reasons why you would like to create your own custom notifications, in this article we'll use the CleanUpYourRoom recurring hosted service as an example, which empties the recycle bin every 5 minutes. You might want to publish a notification once the task has started, and maybe once the task has successfully cleared the recycle bin.

For a notification to be publishable there's only one requirement, it must implement the empty marker interface INotification, the rest is up to you. For instance, we might want to create a notification that just signals that the clean your room task has started and nothing else, in this case, we'll create an empty class implementing INotification

using Umbraco.Cms.Core.Notifications;

namespace Umbraco.Docs.Samples.Web.RecurringBackgroundJobs;

public class CleanYourRoomStartedNotification : INotification
{

}

This notification can now be published, and we can create a notification handler to receive it with, see MediaService-Notifications for an example of how to implement a notification handler. But this notification alone might not be super helpful, we might want to be able to send some additional information with the notification, however, since this is, in essence, just a normal class, we can include whatever information we want. Let's try and create a RoomCleanedNotification which contains the number of nodes removed from the recycle bin:

using Umbraco.Cms.Core.Notifications;

namespace Umbraco.Docs.Samples.Web.RecurringBackgroundJobs;

public class RoomCleanedNotification : INotification
{
    public int ItemsDeleted { get; }

    public RoomCleanedNotification(int itemsDeleted)
    {
        ItemsDeleted = itemsDeleted;
    }
}

Now you can create a handler that receives the amount of items deleted through the notification.

Sending notifications

Just creating the notification classes is not enough, we also want to be able to publish them. There's two ways of publishing notifications:

• IEventAggregator - Notifications published with IEventAggregator will always be published immediately.

• IScope.Notifications - Notifications published with a scope will only be published once the scope has been completed and disposed.

The method you use to publish notifications depends on what your needs are, the benefits of publishing notifications with a scope is that the notification will only be published if you complete the scope, and then only once the scope is disposed of. This can be useful if you access the database, or do some other operation that might fail causing you to do a rollback, disposing of the scope without completing it, in this case, you might not want to publish a notification that signals that the operation was a success, using scopes will handle this for you. On the other hand, you might want to publish the notification immediately no matter what, for instance with the CleanYourRoomStartedNotification, for this, the IEventAggregator is the right choice.

Example

using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Scoping;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Infrastructure.BackgroundJobs;

namespace Umbraco.Docs.Samples.Web.RecurringBackgroundJobs;

public class CleanUpYourRoom : IRecurringBackgroundJob
{
    public TimeSpan Period { get; } = TimeSpan.FromMinutes(5);
    public event EventHandler? PeriodChanged { add {} remove {} }

    private readonly IContentService _contentService;
    private readonly ICoreScopeProvider _coreScopeProvider;
    private readonly IEventAggregator _eventAggregator;

    public CleanUpYourRoom(
        IContentService contentService,
        ICoreScopeProvider coreScopeProvider,
        IEventAggregator eventAggregator,
        ILogger<CleanUpYourRoom> logger)
    {
        _contentService = contentService;
        _coreScopeProvider = coreScopeProvider;
        _eventAggregator = eventAggregator;
    }

    public Task RunJobAsync()
    {
        // This will be published immediately
        _eventAggregator.Publish(new CleanYourRoomStartedNotification());

        using ICoreScope scope = _coreScopeProvider.CreateCoreScope();
        int numberOfThingsInBin = _contentService.CountChildren(Constants.System.RecycleBinContent);

        if (_contentService.RecycleBinSmells())
        {
            _contentService.EmptyRecycleBin(userId: -1);
            // This will only be published when the scope is completed and disposed.
            scope.Notifications.Publish(new RoomCleanedNotification(numberOfThingsInBin));
        }

        // Remember to complete the scope when done.
        scope.Complete();
        return Task.CompletedTask;
    }
}

In this case, the CleanYourRoomStartedNotification will always be published immediately, however, RoomCleanedNotification will only be published once the operation is done, and if you remove the scope.Complete(); line it will never be published, the recycle bin won't be emptied either.

Before starting with cache refresher notifications it's a good idea to ensure you need to use them. If you want to react to changes in content, for instance, there's no real reason to use these notifications. This is due to the content service notifications being easier to work with. If you need to react to changes in the cache, then these are the notifications for you.

Cache refresher notifications are sent when the cache has refreshed. There are multiple different types of cache refresher notifications. These types are based on what type has been updated in the cache, for instance, content or media. All these notifications inherit from the same base notification: CacheRefresherNotification.

The base notification is implemented in the following way:

public abstract class CacheRefresherNotification : INotification
{
    public CacheRefresherNotification(object messageObject, MessageType messageType)
    {
        MessageObject = messageObject ?? throw new ArgumentNullException(nameof(messageObject));
        MessageType = messageType;
    }

    public object MessageObject { get; }

    public MessageType MessageType { get; }
}

As you can see this notification contains two properties, a MessageObject and a MessageType. The MessageType specifies what kind of cache operation was performed, for example RemoveById. The possible message types is as follows:

public enum MessageType
{
    RefreshAll,
    RefreshById,
    RefreshByJson,
    RemoveById,
    RefreshByInstance,
    RemoveByInstance,
    RefreshByPayload,
}

The other parameter MessageObject will depend on what type of cache refresher notification you're handling. If you for instance handle the ContentCacheNotification, the message object will be ContentCacheRefresher.JsonPayload[].

This object contains the Id and key of the item being updated, as well as an enum specifying how the tree is updated:

[Flags]
public enum TreeChangeTypes : byte
{
    None = 0,

    // all items have been refreshed
    RefreshAll = 1,

    // an item node has been refreshed
    // with only local impact
    RefreshNode = 2,

    // an item node has been refreshed
    // with branch impact
    RefreshBranch = 4,

    // an item node has been removed
    // never to return
    Remove = 8,
}

An example of working with the ContentCacheNotification can be seen here:

using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Services.Changes;

namespace Umbraco.Cms.Web.UI;

public class ContentCacheRefresherExample : INotificationHandler<ContentCacheRefresherNotification>
{
    private readonly IContentService _contentService;

    public ContentCacheRefresherExample(IContentService contentService)
    {
        _contentService = contentService;
    }

    public void Handle(ContentCacheRefresherNotification notification)
    {
        if (notification.MessageObject is not ContentCacheRefresher.JsonPayload[] payloads)
        {
            return;
        }

        foreach (ContentCacheRefresher.JsonPayload payload in payloads)
        {
            if (payload.ChangeTypes is not TreeChangeTypes.RefreshNode or TreeChangeTypes.RefreshBranch)
            {
                return;
            }

            // You can do stuff with the ID of the refreshed content, for instance getting it from the content service.
            var refeshedContent = _contentService.GetById(payload.Id);
        }
    }
}

The ContentService class is the most commonly used type when extending Umbraco using notifications. ContentService implements IContentService. It provides access to operations involving IContent.

Usage

Example usage of the ContentPublishingNotification:

Variants and Notifications

Umbraco V8 introduced the concept of Variants for Document Types, initially to allow different language variants of particular properties within a Document Type to be edited/translated based on the languages configured in your instance of Umbraco.

These variants can be saved, published, and unpublished independently of each other. (Unpublishing a 'mandatory language' variant of a content item - will trigger all culture variants to be unpublished).

This poses a problem when handling notifications from the ContentService - for example which culture got published? Do I want to run my 'custom' code that fires on save if it's only the Spanish version that's been published? Also, if only the Spanish variant is 'unpublished' - that feels like a different situation than if 'all the variants' have been 'unpublished'. Depending on which event you are handling there are helper methods you can call to find out.

Saving

When handling the ContentSavingNotification which will be published whenever a variant is saved. You can tell 'which' variant has triggered the save using an extension method on the ContentSavingNotification called 'IsSavingCulture'

As an example, you could check which cultures are being saved (it could be multiple if multiple checkboxes are checked)

Saved

With the Saved notification you can similarly use the 'HasSavedCulture' method of the 'ContentSavedNotification' to detect which culture caused the Save.

Unpublishing

When handling the Unpublishing notification, it might not work how you would expect. If 'all the variants' are being unpublished at the same time (or the mandatory language is being unpublished, which forces this to occur) then the Unpublishing notification will be published as expected.

However, if only one variant is being unpublished, the Unpublishing event will not be triggered. This is because the content item itself is not fully 'unpublished' by the action. Instead, what occurs is a 'publish' action 'without' the unpublished variant.

You can therefore detect the Unpublishing of a variant in the publishing notification - using the IsUnpublishingCulture extension method of the ContentPublishingNotification

Unpublished

Again, the Unpublished notification does not get published when a single variant is Unpublished, instead, the Published notification can be used, and the 'HasUnpublishedCulture' extension method of the ContentPublishedNotification can determine which variant being unpublished triggered the publish.

Publishing

When handling the ContentPublishingNotification which will be triggered whenever a variant is published (or unpublished - see note in the Unpublishing section above).

You can tell 'which' variant has triggered the publish using a helper method on the ContentPublishingNotification called IsPublishingCulture.

For example, you could check which cultures are being published and act accordingly (it could be multiple if multiple checkboxes are checked).

Published

In the Published notification you can similarly use the HasPublishedCulture and HasUnpublishedCulture methods of the 'ContentPublishedEventArgs' to detect which culture caused the Publish or the UnPublish if it was only a single non-mandatory variant that was unpublished.

IContent Helpers

In each of these notifications, the entities being Saved, Published, and Unpublished are IContent entities. There are some useful helper methods on IContent to discover the status of the content item's variant cultures:

Umbraco application lifetime notifications are published for the starting, started, stopping, and stopped events of the Umbraco runtime. These events implement the IUmbracoApplicationLifetimeNotification interface that contains a single IsRestarting property.

An Umbraco application is restarted after an install or upgrade has been completed. You can use this property to prevent running code twice: on initial boot and restart. To prevent running code when the application is in the install or upgrade state, inject an IRuntimeState instance in your notification and inspect the Level property instead.

Usage

Example usage of the UmbracoApplicationLifetime notifications:

It's important to know that the handlers you create and register to receive notifications will be transient. This means that they will be initialized every time they receive a notification. You can therefore not rely on them having a specific state based on previous notifications.

As an example, you cannot do the following:

1. Create a list in a handler.

2. Add something when a notification is received.

3. Check if that list contains what you added in an earlier notification.

When following the steps above, the list will always be empty because the object has only been initialized.

If you need persistence between notifications, we recommend you move that functionality into a service or similar. You can then register it with the DI container, and inject it into your handler.

As previously mentioned, many notifications exist in pairs, with a "before" and "after" notification. There may be cases where you want to add some information to the "before" notification, which will then be available to your "after" notification handler. In order to support this, the notification "pairs" are stateful. This means the notifications contain a dictionary that is shared between the "before" and "after" notifications. You can add values to the dictionary, and later retrieve them like this:

Registering notification handlers

Once you have made your notification handlers, you need to register them with the AddNotificationHandler extension method on the IUmbracoBuilder. This enables them to run whenever a notification they subscribe to is published. There are two ways to do this:

1. In the Program class, if you're making handlers for your site

2. In a composer, if you're a package developer subscribing to notifications

Registering notification handlers in the program class

In the Program.cs file, register your notification in the CreateUmbracoBuilder() builder chain:

The extension method takes two generic type parameters. The first, ContentPublishingNotification, is the notification you wish to subscribe to. The second, DontShout, is the class that handles the notification. This class must implement INotificationHandler<> with the type of notification it handles as the generic type parameter. In this case, the DontShout class definition looks like this:

Registering notification handlers in a composer

If you are writing a package for Umbraco you will not have access to the Program class. You can instead use a composer, which gives you access to the IUmbracoBuilder.

Async Notification Handler

If you need to do anything asynchronously when handling a notification, you can achieve this using the INotificationAsyncHandler.

Notification handler

Create an asynchronous handler by implementing the INotificationAsyncHandler:

Notification registration

When using the INotificationAsyncHandler, register it using the IUmbracoBuilder and the AddNotificationAsyncHandler extension method. This can be done in the Program class or with a composer.

The MediaService class implements IMediaService. It provides access to operations involving IMedia.

Usage

Example usage of the MediaService notifications:

Returning messages to the user

You can return a custom message to the user. Use this to show information, a warning or maybe an error. This is achieved using the Messages property of the notification and a composer.

Example

This example returns an informational message to the user when a Media item is saved.

Many of the Umbraco services publishes a 'Saved' notification (or similar). In some cases, it is beneficial to know if this entity is a brand new entity that has been persisted in the database. This is how you can determine this.

Checking if it's new

We know that if an entity is new and hasn't been persisted that it will not have an ID. Therefore we know if an entity has been newly persisted to the database by checking if its ID was changed before being persisted.

Here's the snippet of code that does that:

To check if an entity is new in the ContentSavingNotification use the following:

Since the IContent has not been saved yet, it's not necessary to cast it to IRememberBeingDirty. It won't have an identity if it's new, since it hasn't been committed yet.

How it works

This is all possible because of the IRememberBeingDirty interface. Indeed the name of this interface is hilarious but it describes exactly what it does. All entities implement this interface which is really handy. It tracks not only the property data that has changed because it inherits from yet another hilarious interface called ICanBeDirty. It also tracks the property data that was changed before it was committed.

The MemberService implements IMemberService and provides access to operations involving IMember.

Usage

The SendingAllowedChildrenNotification enables you to manipulate the Document Types that will be shown in the create menu when adding new content in the backoffice.

Usage

With the example below we can ensure that a Document Type cannot be selected if the type already exists in the Content tree.

You also need to register this notification handler. You can achieve this by updating the Program class like:

The load time of your site is dependent on a few different things. When talking about hot vs. cold restarts of your Umbraco CMS website it comes down to whether NuCache needs to be rebuilt.

• Cold restart: When NuCache needs to rebuild.

• Hot start: When NuCache does not need to rebuild.

Hot start

When no cache needs to be rebuild, the restart of your site is generally faster. This is why it is referred to as a hot restart.

Cold start

The cold restart expression is generally used for when the NuCache needs to rebuild. This will resolve in a slower startup time, depending on the amount of content on the site. Generally speaking, the more content you have the longer a cold boot will take.

Troubleshooting slow startup

Different things could be in play when your site is slow to startup after a reboot/restart.

Below is a list of some of the more common reasons:

• NuCache needs to rebuild (cold restart).

• Examine indexes need to rebuild - for large sites, this can take some time.

• The custom code on the website is not optimized and does not live up to .NET standards.

In Memory Auto

Another factor that can slow down time to first page load is the In Memory Auto models builder setting. Having this setting enabled will result in the first page load being slower. The reason for this is that when the first page is requested, the strongly typed models needs to be compiled and loaded in.

This is, however, less noticeable on consecutive restarts, a bit like hot and cold restarts. Since the compiled models will be cached on disk, they don't need to be recompiled until the models change again.

Legacy Umbraco

In earlier versions of Umbraco, the difference between hot and cold restarts was more distinct as more components were involved with this process.

Learn more about the different restart processes in the legacy documentation.

The process for troubleshooting slow startup times is also slightly different for earlier version of Umbraco.

EditorModel notifications enable you to manipulate the model used by the backoffice before it is loaded into an editor. For example the SendingContentNotification is published right before a content item is loaded into the backoffice for editing. It is therefore the perfect notification to use to set a default value for a particular property, or perhaps to hide a property/tab/Content App from a certain editor.

Usage

Example usage of the SendingContentNotification - e.g. set the default PublishDate for a new NewsArticle to be today's Date:

using System;
using System.Linq;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Models.ContentEditing;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Extensions;

namespace Umbraco.Docs.Samples.Web.Notifications;

public class EditorSendingContentNotificationHandler : INotificationHandler<SendingContentNotification>
{
    public void Handle(SendingContentNotification notification)
    {
        if (notification.Content.ContentTypeAlias.Equals("blogpost"))
        {
            // Access the property you want to pre-populate
            // each content item can have 'variations' - each variation is represented by the `ContentVariantDisplay` class.
            // if your site uses variants, then you need to decide whether to set the default value for all variants or a specific variant
            // eg. set by variant name:
            // var variant = notification.Content.Variants.FirstOrDefault(f => f.Name == "specificVariantName");
            // OR loop through all the variants:
            foreach (var variant in notification.Content.Variants)
            {
                // Check if variant is a 'new variant'
                // we only want to set the default value when the content item is first created
                if (variant.State == ContentSavedState.NotCreated)
                {
                    // each variant has an IEnumerable of 'Tabs' (property groupings)
                    // and each of these contain an IEnumerable of `ContentPropertyDisplay` properties
                    // find the first property with alias 'publishDate'
                    var pubDateProperty = variant.Tabs.SelectMany(f => f.Properties)
                        .FirstOrDefault(f => f.Alias.InvariantEquals("publishDate"));
                    if (pubDateProperty is not null)
                    {
                        // set default value of the publish date property if it exists
                        pubDateProperty.Value = DateTime.UtcNow;
                    }
                }
            }
        }
    }
}

Another example could be to set the default Member Group for a specific Member Type using SendingMemberNotification:

using System.Collections.Generic;
using System.Linq;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.Services;

namespace Umbraco.Docs.Samples.Web.Notifications;

public class EditorSendingMemberNotificationHandler : INotificationHandler<SendingMemberNotification>
{
    private readonly IMemberGroupService _memberGroupService;

    public EditorSendingMemberNotificationHandler(IMemberGroupService memberGroupService)
    {
        _memberGroupService = memberGroupService;
    }
    
    public void Handle(SendingMemberNotification notification)
    {
        var isNew = !int.TryParse(notification.Member.Id?.ToString(), out int id) || id == 0;
        
        // We only want to set the default member group when the member is initially created, eg doesn't have an Id yet
        if (isNew is false)
        {
            return;
        }

        // Set a default value member group for the member type `Member`
        if (notification.Member.ContentTypeAlias.Equals("Member"))
        {
            var memberGroup = _memberGroupService.GetByName("Customer");
            if (memberGroup is null)
            {
                return;
            }

            // Find member group property on member model
            var property = notification.Member.MembershipProperties.FirstOrDefault(x =>
                x.Alias.Equals($"{Constants.PropertyEditors.InternalGenericPropertiesPrefix}membergroup"));

            if (property is not null)
            {
                // Assign a default value for member group property
                property.Value = new Dictionary<string, object>
                {
                    {memberGroup.Name, true}
                };
            }
        }
    }
}

Notifications

Display models

ContentItemDisplay

A model representing a content item to be displayed in the backoffice

• TemplateAlias

• Urls

• AllowPreview - Determines whether previewing is allowed for this node, By default this is true but by using notifications developers can toggle this off for certain documents if there is nothing to preview

• AllowedActions - The allowed 'actions' based on the user's permissions - Create, Update, Publish, Send to publish

• IsBlueprint

• Tabs - Defines the tabs containing display properties

• Properties - properties based on the properties in the tabs collection

• And more...

MediaItemDisplay

A model representing a media item to be displayed in the backoffice

• Alias

• Tabs - Defines the tabs containing display properties

• Properties - properties based on the properties in the tabs collection

• And more...

MemberDisplay

A model representing a member to be displayed in the backoffice

• Username

• Email

• Tabs - Defines the tabs containing display properties

• Properties - properties based on the properties in the tabs collection

• And more...

Samples

The EditorModel notifications gives you a lot of options to customize the backoffice experience. You can find inspiration from the various samples provided below:

• Customizing the "Links" box

For a content item, Umbraco will show a Links box within the Info content app. By default, this box will show one or more links to content item.

With the SendingContentNotification event, we can manipulate the links in the Urls property. This could be by replacing it with custom links although a URL provider would be more suitable:

public void Handle(SendingContentNotification notification)
{
    notification.Content.Urls = new[]
    {
        new UrlInfo($"/products/?id={notification.Content.Id}", true, null)
    };
}

If the content item has multiple cultures, we can specify the link culture like this:

public void Handle(SendingContentNotification notification)
{
    notification.Content.Urls = new[]
    {
        new UrlInfo($"https://mysite.com/products/?id={notification.Content.Id}", true, "en-US"),
        new UrlInfo($"https://mysite.dk/produkter/?id={notification.Content.Id}", true, "da-DK")
    };
}

or remove the box entirely by providing an empty list of links:

public void Handle(SendingContentNotification notification)
{
    notification.Content.Urls = null;
}