MediaService Notifications

    If you are using Umbraco 8 or any lower version, please refer to the MediaService Events article instead.

    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);
                    }
                }
            }
        }
    }
    

    Events

    Notification Members Description
    MediaSavingNotification
    • IEnumerable<IMedia> SavedEntities
    • EventMessages Messages
    • IDictionary<string,object> State
    • bool Cancel
    Published when MediaService.Save is called in the API.
    NOTE: It can be skipped completely if the parameter "raiseEvents" is set to false during the Save method call (true by default).
    SavedEntities: Gets the collection of IMedia objects being saved.
    MediaSavedNotification
    • IEnumerable<IMedia> SavedEntities
    • EventMessages Messages
    • IDictionary<string,object> State
    Published when MediaService.Save is called in the API and after the data has been persisted.
    NOTE: It can be skipped completely if the parameter "raiseEvents" is set to false during the Save method call (true by default).
    SavedEntities: Gets the saved collection of IMedia objects.
    MediaMovingNotification
    • IEnumerable<MoveEventInfo<IMedia>> MoveInfoCollection
    • EventMessages Messages
    • IDictionary<string,object> State
    • bool Cancel
    Published when MediaService.Move is called in the API.
    NOTE: If the target parent is the Recycle bin, this notification is never published. Try the MediaMovingToRecycleBinNotification instead.
    MoveInfoCollection will for each moving entity provide:
    1. Entity: Gets the IMedia object being moved
    2. OriginalPath: The original path the entity is moved from
    3. NewParentId: Gets the Id of the parent the entity will have after it has been moved
    MediaMovedNotification
    • IEnumerable<MoveEventInfo<IMedia>> MoveInfoCollection
    • EventMessages Messages
    • IDictionary<string,object> State
    Published when MediaService.Move is called in the API. The event is fired after the media object has been moved.
    NOTE: If the target parent is the Recycle bin, this notification is never published. Try the MediaMovedToRecycleBinNotification instead.
    MoveInfoCollection will for each moving entity provide:
    1. Entity: Gets the IMedia object being moved
    2. OriginalPath: The original path the entity is moved from
    3. NewParentId: Gets the Id of the parent the entity will have after it has been moved
    MediaMovingToRecycleBinNotification
    • IEnumerable<MoveEventInfo<IMedia>> MoveInfoCollection
    • EventMessages Messages
    • IDictionary<string,object> State
    • bool Cancel
    Published when MediaService.MoveToRecycleBin is called in the API.
    MoveInfoCollection will for each moving entity provide:
    1. Entity: Gets the IMedia object being moved
    2. OriginalPath: The original path the entity is moved from
    3. NewParentId: Gets the Id of the RecycleBin
    MediaMovedToRecycleBinNotification
    • IEnumerable<MoveEventInfo<IMedia>> MoveInfoCollection
    • EventMessages Messages
    • IDictionary<string,object> State
    Published when MediaService.MoveToRecycleBin is called in the API, after the media object has been moved to the RecycleBin.
    MoveInfoCollection will for each moving entity provide:
    1. Entity: Gets the IMedia object being moved
    2. OriginalPath: The original path the entity is moved from
    3. NewParentId: Gets the Id of the RecycleBin
    MediaDeletingNotification
    • IEnumerable<IMedia> DeletedEntities
    • EventMessages Messages
    • IDictionary<string,object> State
    • bool Cancel
    Published when MediaService.DeleteMediaOfType, MediaService.Delete, MediaService.EmptyRecycleBin are called in the API.
    DeletedEntities: Gets the collection of IMedia objects being deleted.
    MediaDeletedNotification
    • IEnumerable<IMedia> DeletedEntities
    • EventMessages Messages
    • IDictionary<string,object> State
    Published when MediaService.Delete, MediaService.EmptyRecycleBin are called in the API, after the media has been deleted.
    DeletedEntities: Gets the collection of deleted IMedia objects.
    MediaDeletingVersionsNotification
    • EventMessages Messages
    • IDictionary<string,object> State
    • bool Cancel
    • int Id
    • int SpecificVersion
    • DateTime DateToRetain
    • bool DeletePriorVersions
    Published when MediaService.DeleteVersion, MediaService.DeleteVersions are called in the API.
    1. Id: Gets the id of the IMedia object being deleted.
    2. DateToRetain: Gets the latest version date.
    3. SpecificVersion: Gets the id of the IMedia object version being deleted.
    4. DeletePriorVersions: False by default
    MediaDeletedVersionsNotification
    • EventMessages Messages
    • IDictionary<string,object> State
    • int Id
    • int SpecificVersion
    • DateTime DateToRetain
    • bool DeletePriorVersions
    Published when MediaService.DeleteVersion, MediaService.DeleteVersions are called in the API, after the media version has been deleted
    1. Id: Gets the id of the deleted IMedia object.
    2. DateToRetain: Gets the latest version date.
    3. SpecificVersion: Gets the id of the deleted IMedia object version.
    4. DeletePriorVersions: False by default

    What happened to Creating and Created events?

    Both the MediaService.Creating and MediaService.Created events have been obsoleted. Because of this, these were not moved over to notifications, and no longer exist. Why? Because these events were not guaranteed to trigger and therefore should not have been used. This is because these events only triggered when the MediaService.CreateMedia method was used which is an entirely optional way to create media entities. It is also possible to construct a new media item - which is generally the preferred and consistent way - and therefore the Creating/Created events would not execute when constructing media that way.

    Furthermore, there was no reason to listen for the Creating/Created events because they were misleading. They didn't trigger before and after the entity had been persisted. Instead they triggered inside the CreateMedia method which never persists the entity. It constructs a new media object.

    What do we use instead?

    The MediaSavingNotification and MediaSavedNotification will always be published before and after an entity has been persisted. You can determine if an entity is brand new with either of those notifications. With the Saving notification - before the entity is persisted - you can check the entity's HasIdentity property which will be 'false' if it is brand new. In the Saved event you can check to see if the entity 'remembers being dirty'