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:

public void Handle(TemplateSavingNotification notification)
{
 notification.State["SomeKey"] = "Some Value Relevant to the \"after\" notification handler";
}


public void Handle(TemplateSavedNotification notification)
{
  var valueFromSaving = notification.State["SomeKey"];
}

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:

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    // Add your extension methods here, before Build().
    .AddNotificationHandler<ContentPublishingNotification, DontShout>()
    .Build();

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:

public class DontShout : INotificationHandler<ContentPublishingNotification>

For the full handler implementation, see ContentService Notifications.

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.

public class DontShoutComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddNotificationHandler<ContentPublishingNotification, DontShout>();
    }
}

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:

public class ContentDeletedHandler : INotificationAsyncHandler<ContentDeletedNotification>
{
    public async Task HandleAsync(ContentDeletedNotification notification, CancellationToken cancellationToken)
    {
        // await anything
        await Task.Delay(1000);
    }
}

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.

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddNotificationAsyncHandler<ContentDeletedNotification, ContentDeletedHandler>()
    .Build();

public class NotificationHandlersComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddNotificationAsyncHandler<ContentDeletedNotification, ContentDeletedHandler>();
    }
}

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

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:

var dirty = (IRememberBeingDirty)entity;
var isNew = dirty.WasPropertyDirty("Id");

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

var isNew = entity.HasIdentity is false;

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 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:

using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace Umbraco.Docs.Samples.Web.Notifications;

public class DontShout : INotificationHandler<ContentPublishingNotification>
{
    public void Handle(ContentPublishingNotification notification)
    {
        foreach (var node in notification.PublishedEntities)
        {
            if (node.ContentType.Alias.Equals("announcement"))
            {
                var newsArticleTitle = node.GetValue<string>("title");
                if (!string.IsNullOrWhiteSpace(newsArticleTitle) && newsArticleTitle.Equals(newsArticleTitle.ToUpper()))
                {
                    notification.CancelOperation(new EventMessage("Corporate style guideline infringement",
                        "Don't put the announcement title in upper case, no need to shout!",
                        EventMessageType.Error));
                }
            }
        }
    }
}

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'

public bool IsSavingCulture(IContent content, string culture);

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

public void Handle(ContentSavingNotification notification)
{
    foreach (var entity in notification.SavedEntities)
    {
        // Cultures being saved
        var savingCultures = entity.AvailableCultures
            .Where(culture => notification.IsSavingCulture(entity, culture)).ToList();
        // or
        if (notification.IsSavingCulture(entity, "en-GB"))
        {
            // Do things differently if the UK version of the page is being saved.
        }
    }
}

Saved

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

public bool HasSavedCulture(IContent content, string culture);

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.

public void Handle(ContentUnpublishingNotification  notification)
{
 foreach (var unPublishedEntity  in notification.UnpublishedEntities)
 {
  // complete unpublishing of entity, all cultures
 }
}

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

public void Handle(ContentPublishingNotification notification)
{
    foreach (var node in notification.PublishedEntities)
    {
        if (notification.IsUnpublishingCulture(node, "da-DK"))
        {
            // Bye bye DK!
        }
    }
}

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.

public bool HasUnpublishedCulture(IContent content, string culture);

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.

public bool IsPublishingCulture(IContent content, string culture);

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

public void Handle(ContentPublishingNotification notification)
{
    foreach (var node in notification.PublishedEntities)
    {
        var publishingCultures = node.AvailableCultures
            .Where(culture => notification.IsPublishingCulture(node, culture)).ToList();
        
        var unPublishingCultures = node.AvailableCultures
            .Where(culture => notification.IsUnpublishingCulture(node, culture)).ToList();
        // or
        if (notification.IsPublishingCulture(node, "da-DK"))
        {
            // Welcome back DK!
        }
    }
}

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.

public bool HasPublishedCulture(IContent content, string culture);
public bool HasUnpublishedCulture(ICotnent content, string culture);

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:

bool IsCultureAvailable(string culture);
bool IsCultureEdited(string culture);
bool IsCulturePublished(string culture);

using (IScope scope = ScopeProvider.CreateScope(autoComplete: true))
using (IDisposable _ = scope.Notifications.Suppress())
{
    // TODO: Calls to service methods here will not have notifications
}

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

Usage

Example usage of the MediaService notifications:

using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace MySite;

public class MediaNotificationHandler : INotificationHandler<MediaSavedNotification>
{
    private readonly ILogger<MediaNotificationHandler> _logger;

    public MediaNotificationHandler(ILogger<MediaNotificationHandler> logger)
    {
        _logger = logger;
    }
    
    public void Handle(MediaSavedNotification notification)
    {
        foreach (var mediaItem in notification.SavedEntities)
        {
            if (mediaItem.ContentType.Alias.Equals("Image"))
            {
                // Do something with the image, maybe send to Azure for AI analysis of image contents or something.
                _logger.LogDebug($"Sending {mediaItem.Name} to analysis");
                SendToAzure(mediaItem);
            }
        }
    }
}

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.

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace MyProject
{
 public class CustomComposer : IComposer
 {
  public void Compose(IUmbracoBuilder builder)
  {
   builder.AddNotificationHandler<MediaSavedNotification, MediaNotificationTest>();
  }
 }

 public class MediaNotificationTest : INotificationHandler<MediaSavedNotification>
 {  
  public void Handle(MediaSavedNotification notification)
  {
   notification.Messages.Add(new EventMessage(
    "Notification",
    "You can return a message to the user, using the messages property on the notification.",
    EventMessageType.Info));
  }
 }
}

using (IScope scope = ScopeProvider.CreateScope(autoComplete: true))
using (IDisposable _ = scope.Notifications.Supress())
{
    // TODO: Calls to service methods here will not have notifications
}

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 the search indexes need to be rebuilt.

• Cold restart: When the search indexes need to rebuild.

• Hot start: When the search indexes do 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 search indexes need 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:

• The search indexes need 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

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.

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 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

This notification can now be published, and we can create a notification handler to receive it with, see 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:

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

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.

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:

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:

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

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:

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 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:

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:

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:

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

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:

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

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

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 MemberService implements IMemberService and provides access to operations involving IMember.

Usage