Services and Helpers

Umbraco has a range of 'Core' Services and Helpers that act as a 'gateway' to Umbraco data and functionality to use when extending or implementing an Umbraco site

Umbraco has a range of 'Core' Services and Helpers that act as a 'gateway' to Umbraco data and functionality to use when extending or implementing an Umbraco site.

The general rule of thumb is that management Services provide access to allow the modification of Umbraco data (and therefore aren't optimised for displaying data). Helpers on the other hand provide access to readonly data with performance of displaying data taken into consideration.

Although there is a management Service named the IContentService - only use this to modify content - do not use the IContentService in a View/Template to pull back data to display, this will make requests to the database and be slow - here instead inject the IPublishedContentQueryAccessor interface and get the IPublishedContentQuery that operate against a cache of published content items, and are significantly quicker.

The management Services and Helpers are all registered with Umbraco's underlying DI framework. This article aims to show examples of gaining access to utilise these resources in multiple different scenarios. There are subtle differences to be aware of depending on what part of Umbraco is being extended.

This article will also suggest how to follow a similar pattern to encapsulate custom 'site specific' implementation logic, in similar services and helpers, registered with the underlying DI contain. This would be to avoid repetition and promote consistency and readability within an Umbraco site solution.

Accessing Management Services and Helpers in a Template/View

Inside a view/template or partial view, access is also provided by the DI framework, by using the @inject keyword.

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.Root>
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
@using Umbraco.Cms.Core.Services;
@using Umbraco.Cms.Web.Common;

@* it is really 'unlikely' to need to use a management Service in a view: *@
@inject IRelationService RelationService
@inject UmbracoHelper Umbraco

@{
    Layout = null;

    // retrieve an item from Umbraco's published cache with id 123
    IPublishedContent publishedContentItem = Umbraco.Content(123);
}

Accessing Core Services and Helpers in a Controller

Inside a custom Controller access is provided to Services via the Services property (ServiceContext) and the UmbracoHelper via the Umbraco property (UmbracoHelper).

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ViewEngines;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Web.Common.Controllers;

namespace Umbraco9.Controllers
{
    public class BlogPostController : RenderController
    {
        private readonly ILogger<BlogPostController> _logger;
        private readonly IPublishedContentQuery _publishedContentQuery;
        private readonly IRelationService _relationService;

        public BlogPostController(
            ILogger<BlogPostController> logger,
            ICompositeViewEngine compositeViewEngine,
            IUmbracoContextAccessor umbracoContextAccessor,
            IPublishedContentQuery publishedContentQuery,
            IRelationService relationService)
            : base(logger, compositeViewEngine, umbracoContextAccessor)
        {
            _logger = logger;
            _publishedContentQuery = publishedContentQuery;
            _relationService = relationService;
        }

        public override IActionResult Index()
        {
            // write helpful messages to the Umbraco logs to aid with debugging
            _logger.LogInformation("Using core logger implementation");
            // retrieve an item from Umbraco's published cache with id 123
            IPublishedContent publishedContentItem = _publishedContentQuery.Content(123);
            // it is unlikely to use a management service when rendering content from a custom controller
            //(when using relationService like this you would want to provide a layer of caching)
            var allRelatedUmbracoItems = _relationService.GetByParentId(CurrentPage.Id);

            return base.Index();
        }
    }
}

Accessing core Services and Helpers when there is no 'UmbracoContext' eg in a Component or C# Class

Controllers and Views can access an IUmbracoContext by injecting the IUmbracoContextAccessor, however this is not always the case 'everywhere in Umbraco', for example common extension points: Components,ContentFinders or Custom C# Classes.

IUmbracoContext, UmbracoHelper, IPublishedContentQuery - are all based on an HttpRequest - their lifetime is controlled by an HttpRequest. So if you are not operating within an actual request, you cannot inject these parameters and if you try to ... Umbraco will report an error on startup.

Injecting Services into a Component

It's possible to inject management Services that do not rely on the UmbracoContext into the constructor of a component. This example shows injecting the IMediaService in a Notification Handler to create a corresponding Media Folder for every 'landing page' that is saved in the Content Section, by subscribing to the 'Content Saved' notification.

using System.Linq;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.Services;

namespace Umbraco9.Components
{
    public class SubscribeToContentSavedEventComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<ContentSavedNotification, SubscribeToContentSavedNotification>();
        }
    }
    public class SubscribeToContentSavedNotification: INotificationHandler<ContentSavedNotification>
    {
        private readonly IMediaService _mediaService;

        public SubscribeToContentSavedNotification(IMediaService mediaService)
        {
            _mediaService = mediaService;
        }

        public void Handle(ContentSavedNotification notification)
        {
            foreach (var contentItem in notification.SavedEntities)
            {
                // if this is a new landing page create a folder for associated media in the media section
                if (contentItem.ContentType.Alias == "landingPage")
                {
                    // we have injected in the mediaService in the constructor for the component see above.
                    bool hasExistingFolder = _mediaService.GetByLevel(1).Any(f => f.Name == contentItem.Name);
                    if (!hasExistingFolder)
                    {
                        // let's create one (-1 indicates the root of the media section)
                        IMedia newFolder = _mediaService.CreateMedia(contentItem.Name, -1, "Folder");
                        _mediaService.Save(newFolder);
                    }
                }
            }
        }
    }
}

See documentation on Composing for further examples and information on Components and Composition.

Accessing Published Content outside of a Http Request

Trying to inject types that are based on an Http Request such as UmbracoHelper or IPublishedContentQuery into classes that are not based on an Http Request will trigger an error. However, there is a technique that allows the querying of the Umbraco Published Content, using the UmbracoContextFactory and calling EnsureUmbracoContext().

In this example, when a page is unpublished, instead of a 404 occurring for the content when the url is requested in the future, we might want to serve a 410 'page gone' status code instead. We handle the Unpublishing notification of the ContentService, access the Published Content Cache, determine it's 'published url' and then store for later use in any 'serving the 410' mechanism.

An IContentFinder could be placed in the ContentFinder ordered collection, right before a 404 is served. This could be done to lookup the incoming request against the stored location of 410 urls, and serve the 410 status request code if a match is found for the previously published item.

using System;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.PublishedCache;
using Umbraco.Cms.Core.Web;
using Umbraco.Extensions;

namespace Umbraco9.Components
{
    public class HandleUnPublishingEventComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<ContentUnpublishedNotification, HandleUnPublishingHandler>();
        }
    }

    public class HandleUnPublishingHandler : INotificationHandler<ContentUnpublishedNotification>
    {
        private readonly IUmbracoContextFactory _umbracoContextFactory;

        public HandleUnPublishingHandler(IUmbracoContextFactory umbracoContextFactory)
        {
            _umbracoContextFactory = umbracoContextFactory;
        }

        public void Handle(ContentUnpublishedNotification notification)
        {
            // for each unpublished item, we want to find the url that it was previously 'published under' and store in a database table or similar
            using (UmbracoContextReference umbracoContextReference = _umbracoContextFactory.EnsureUmbracoContext())
            {
                // the UmbracoContextReference provides access to the ContentCache
                IPublishedContentCache contentCache = umbracoContextReference.UmbracoContext.Content;

                foreach (var item in notification.UnpublishedEntities)
                {
                    if (item.ContentType.Alias == "blogpost")
                    {
                        // item being unpublished will still be in the cache, as unpublishing event fires before the cache is updated.
                        IPublishedContent soonToBeUnPublishedItem = contentCache.GetById(item.Id);

                        if (soonToBeUnPublishedItem != null)
                        {
                            string previouslyPublishedUrl = soonToBeUnPublishedItem.Url();

                            if (!string.IsNullOrEmpty(previouslyPublishedUrl) && previouslyPublishedUrl != "#")
                            {
                                _customFourTenService.InsertFourTenUrl(previouslyPublishedUrl, DateTime.UtcNow);
                            }
                        }
                    }
                }
            }
        }
    }
}

Accessing the Published Content Cache from a Content Finder / UrlProvider

Inside a ContentFinder access to the content cache is possible by injecting IUmbracoContextAccessor into the constructor and provided via the PublishedRequest object:

public Task<bool> TryFindContent(IPublishedRequestBuilder request)
{
    if (!UmbracoContextAccessor.TryGetUmbracoContext(out var umbracoContext))
    {
        return false;
    }
    var someContent = umbracoContext.Content.GetById(1234);

    // ...
}

And inside an IPublishedUrlProvider injection of IUmbracoContextAccessor into the constructor is also possible.

private readonly IUmbracoContextAccessor _umbracoContextAccessor;

public MyCustomUrlProvider(IUmbracoContextAccessor umbracoContextAccessor)
{
    _umbracoContextAccessor = umbracoContextAccessor ?? throw new ArgumentNullException(nameof(umbracoContextAccessor));
}

public override UrlInfo GetUrl(IPublishedContent content, UrlMode mode = UrlMode.Default, string culture = null, Uri current = null)
{

    var umbracoContext = _umbracoContextAccessor.GetRequiredUmbracoContext();
    var someContent = umbracoContext.Content.GetById(1234);

    // ...
}

It is still possible to inject services into IContentFinder's. IContentFinders are singletons, but the example is showing you do not 'need to' in order to access the Published Content Cache.

Customizing Services and Helpers

When implementing an Umbraco site, it is likely to have to execute similar code that accesses or operates on Umbraco data, in multiple places, perhaps using the core management Services or Umbraco Helpers.

For example; Getting a list of the latest News Articles, or building a link to the site's News Section or Contact Us page. Repeating this kind of logic in multiple places, Views, Partial Views / Controllers etc, is possible, but it's generally considered good practice to consolidate this logic into a single place.

Extension methods

One option is to add 'Extension Methods' to the UmbracoHelper class or IPublishedContentQuery interface.

using System.Linq;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Extensions;

namespace Umbraco9.Components
{
    public static class PublishedContentQueryExtensions
    {
        public static IPublishedContent GetNewsSection(this IPublishedContentQuery publishedContentQuery)
        {
            // assuming a single site with a single News Section at the top level
            IPublishedContent siteRoot = publishedContentQuery.ContentAtRoot().FirstOrDefault();
            // make sure siteRoot isn't null, then locate first child content item with alias 'newsSection'
            return siteRoot?.FirstChild(f => f.ContentType.Alias == "newsSection") ?? null;
        }
    }

Circular Dependencies

Circular Dependencies

Services and Helpers

Accessing Management Services and Helpers in a Template/View

Accessing Core Services and Helpers in a Controller

Accessing core Services and Helpers when there is no 'UmbracoContext' eg in a Component or C# Class

Injecting Services into a Component

Accessing Published Content outside of a Http Request

Accessing the Published Content Cache from a Content Finder / UrlProvider

Customizing Services and Helpers

Extension methods