1 of 8

Using Umbraco services

List of service references along with instructions on how to use them, as well as some examples for better understanding.

In this article you can learn how to use and work with some of the services provided with Umbraco CMS.

You can find a list of all supported services in the API Documentation.

Getting a Service

All services can be accessed with the following using statement:

using Umbraco.Cms.Core.Services;

In some cases, you can use Dependency Injection. For example, if you have registered your class in Umbraco's dependency injection, you can specify the service interface in your constructor.

To use the NotificationService you can use Dependency Injection via the INotificationService interface like this:

public class MyClass
{
    private INotificationService _notificationService;

 public MyClass(INotificationService notificationService)
 {
  _notificationService = notificationService;
 }
}

In Razor views, you can access the Notification Service through the @inject directive:

@inject INotificationService NotificationService

Use the above example for other services by replacing the interface and the name of the service.

Consent Service

A service for handling lawful data processing requirements.

A consent is fully identified by a source (whoever is consenting), a context (for example, an application), and an action (whatever is consented). A consent state registers the state of the consent (granted, revoked...).

Consent can be given or revoked or changed via the RegisterConsent method, which creates a new Consent entity to track the consent.

Get the current state

Getter methods of this service return the current state of a consent, that is the latest IConsent entity that was created.

Revoking a consent is performed by registering a revoked consent.

A consent cannot be deleted. It can only be revoked by registering a "revoked consent".

Examples

// store a new consent
var newConsent = _consentService.RegisterConsent("userId", "Our.Custom.Umbraco.Plugin", "AllowedToEmail", ConsentState.Granted, "some comments");

// lookup a consent
var consents = _consentService.LookupConsent("userId", "Our.Custom.Umbraco.Plugin", "AllowedToEmail", sourceStartsWith : true);
if (consents != null && consents.Any())
{
    var currentConsent = consents.First(c => c.Current == true);
    if(currentConsent.State  == ConsentState.Granted)
    {
        // Do what you need
    }
    else
    {
        // the state is None, Pending or Revoked
    }
}

Media Service

Examples on how to create a new folder and a new media item from a stream by using the MediaService.

In this article, you can find some examples on how to create a new media folder and a media item from a stream programmatically.

Samples in this document will require the following using statements:

using Umbraco.Cms.Core;
using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Strings;
using Umbraco.Extensions;

Creating a new folder

To create a new folder at the root of the media archive, your code could look like the following:

// Initialize a new media at the root of the media archive
IMedia folder = _mediaService.CreateMedia("Samples Media Item Folder", Constants.System.Root, Constants.Conventions.MediaTypes.Folder);

// Save the folder
var result = _mediaService.Save(folder);

Alternatively, you can replace the Constants in the above sample with hardcoded values.

// Initialize a new media at the root of the media archive
IMedia folder = _mediaService.CreateMedia("Samples Media Item Folder", -1, "Folder");

// Save the folder
var result = _mediaService.Save(folder);

For the CreateMedia method, the first parameter is the name of the folder to be created.

The second parameter is the ID of the parent media item. Constants.System.Root is a constant defined in Umbraco with the value of -1, which is used for indicating the root of the media archive. Instead of specifying the numeric ID of the parent, you may instead specify either a Guid ID or an IMedia instance representing the parent media.

The third parameter is the alias of the Media Type. As Umbraco comes with a Folder Type by default, we can use the Constants.Conventions.MediaTypes.Folder constant to specify that the alias of the Media Type is Folder.

Besides the three mandatory parameters, you can specify a user's numeric ID for media creation attribution. Unspecified cases default to the "Administrator" user with ID -1.

Creating a new media item from a stream

You can specify a Stream for the contents of the file that should be created.

As an example, if you have an image on disk named unicorn.jpg in the images folder of wwwroot. You can open a new stream for a file on the disk, and then create a new media item for that file in Umbraco:

Please be aware that you will need to inject the following services:

MediaFileManager _mediaFileManager
IShortStringHelper _shortStringHelper
IContentTypeBaseServiceProvider _contentTypeBaseServiceProvider
MediaUrlGeneratorCollection _mediaUrlGeneratorCollection
IMediaService _mediaService
IWebHostEnvironment _webHostEnvironment

string webRootPath = _webHostEnvironment.WebRootPath;
var path = Path.Combine(webRootPath, "images", "unicorn.jpg");

// Open a new stream to the file
using (Stream stream = System.IO.File.OpenRead(path))
{
    // Initialize a new image at the root of the media archive
    IMedia media = _mediaService.CreateMedia("Unicorn", Constants.System.Root, Constants.Conventions.MediaTypes.Image);
    // Set the property value (Umbraco will handle the underlying magic)
    media.SetValue(_mediaFileManager, _mediaUrlGeneratorCollection, _shortStringHelper, _contentTypeBaseServiceProvider, Constants.Conventions.Media.File, "unicorn.jpg", stream);

    // Save the media
    var result = _mediaService.Save(media);
}

Again Umbraco will make sure the necessary properties are updated.

Relation Service

The RelationService allows you to create relations between objects that would otherwise have no obvious connection.

Below you will find examples using RelationService.

Automatically relate to the root node

To perform the said task we need a Notification Handler:

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

namespace Doccers.Core.Components;

public class ContentPublishedNotificationHandler(IContentService contentService, IRelationService relationService) : INotificationHandler<ContentPublishedNotification>
{
    public void Handle(ContentPublishedNotification notification)
    {
        var home = contentService.GetRootContent().FirstOrDefault();
        if (home == null) return;

        // Get the relation type by alias
        var relationType = relationService.GetRelationTypeByAlias("homesick");

        if (relationType == null) return;

        foreach (var entity in notification.PublishedEntities
                     .Where(x => x.Id != home.Id))
        {
            // Check if they are already related
            if (!relationService.AreRelated(home.Id, entity.Id))
            {
                // If not then let us relate the currenty entity to home
                relationService.Relate(home.Id, entity.Id, relationType);
            }
        }
    }
}

To have Umbraco recognize our Notification Handler we need to register it in a composer:

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

namespace Doccers.Core.Composers;

public class RelationComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddNotificationHandler<ContentPublishedNotification, ContentPublishedNotificationHandler>();
    }
}

If I know Save and Publish my Products node I get the following result:

Now let us try and fetch the data from an API.

using Microsoft.AspNetCore.Mvc;
using System.Runtime.Serialization;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Web.Common;

namespace Doccers.Core.Controllers.Http;

[ApiController]
[Route("/umbraco/api/relations")]
public class RelationsController : Controller
{
    private readonly IRelationService _relationService;
    private readonly UmbracoHelper _umbracoHelper;

    public RelationsController(IRelationService relationService, UmbracoHelper umbracoHelper)
    {
        // Alternatively you could also access
        // the service via the service context:
        // _relationService = Services.RelationService;
        _relationService = relationService;
        _umbracoHelper = umbracoHelper;
    }

    [HttpGet("getbyrelationtypealias")]
    public IActionResult GetByRelationTypeAlias(string alias)
    {
        var relationType = _relationService.GetRelationTypeByAlias(alias);
        if (relationType == null)
            return BadRequest("Invalid relation type alias");

        var relations = _relationService.GetAllRelationsByRelationType(relationType.Id);
        var content = relations.Select(x => _umbracoHelper.Content(x.ChildId))
            .Select(x => new Relation()
            {
                Name = x.Name,
                UpdateDate = x.UpdateDate
            });

        return Ok(content);
    }
}

Notice the x => new Relation()? We need to make sure what we are returning can be serialized. Therefore the Relation class is:

[DataContract(Name = "relation")]
public class Relation
{
    [DataMember(Name = "name")]
    public string Name { get; set; }

    [DataMember(Name = "updateDate")]
    public DateTime UpdateDate { get; set; }
}

Browsing /umbraco/api/relations/getbyrelationtypealias?alias=homesick now returns the following:

If you want to do something similar it is recommended that you wrap a caching layer around it, as the RelationService queries the database directly.

Content Service

Example on how to create content programmatically using the ContentService.

Learn how to use the Content Service.

Creating content programmatically

In the example below, a new page is programmatically created using the content service. It is assumed that there are two document types, namely Catalogue and Product. In this case, a new Product is added underneath the Catalogue page. Add the below code in the Catalogue template.

// Get access to ContentService - Add this at the top of your razor view
@inject IContentService ContentService
@using Umbraco.Cms.Core.Services

// Add this anywhere in your Catalogue template
@{
    // Create a variable for the GUID of the parent page - Catalogue, where you want to add a child item.
    var parentId = Guid.Parse("b6fbbb31-a77f-4f9c-85f7-2dc4835c7f31");

    // Create a new child item of type 'Product'
    var demoproduct = ContentService.Create("Microphone", parentId, "product"); 

    // Set the value of the property with alias 'category'
    demoproduct.SetValue("category" , "audio");

    // Set the value of the property with alias 'price'
    demoproduct.SetValue("price", "1500");

    // Save and publish the child item
    ContentService.SaveAndPublish(demoproduct);
    
}

In a multilanguage setup, it is necessary to set the name of the content item for a specified culture:

demoproduct.SetCultureName("Microphone", "en-us"); // this will set the english name
demoproduct.SetCultureName("Mikrofon", "da"); // this will set the danish name

For information on how to retrieve multilingual languages, see the Retrieving languages article.

Content Type Service

Examples on how to retrieve content types and content type containers using the ContentTypeService.

Learn how to work with Content Types through the Content Type Service.

Getting a single content type

A given content type has a few different unique identifier that we can use to look it up via the content type service. For instance, if we know the GUID of the content type, we can look it up like this:

// Declare the GUID ID
Guid guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");

// Get a reference to the content type by its GUID ID
IContentType contentType = _contentTypeService.Get(guid);

Although the use of a GUID is preferable, you can also use it's numeric ID:

// Get a reference to the content type by its numeric ID
IContentType contentType = _contentTypeService.Get(1234);

Finally, you can also look up a content type by its alias:

// Get a reference to the content type by its alias
IContentType contentType = _contentTypeService.Get("home");

Getting a list of content types

As content types are stored in a hierarchical list with folders (containers), there is also multiple ways to can get content types. If you are looking for a flat list of all content types, you can use the GetAll method:

// Get a collection of all content types
IEnumerable<IContentType> contentTypes = _contentTypeService.GetAll();

In the example above, the method was called without any parameters. The method also has two overloads, which lets you look up a collection fo content types by either specifying their GUID or numeric IDs:

// Get a collection of two specific content types by their GUIDs IDs
IEnumerable<IContentType> contentTypes = _contentTypeService.GetAll(new[] {
    new Guid("2b54088e-d355-4b9e-aa4b-5aec4b3f87eb"),
    new Guid("859c5916-19d8-4a72-9bd0-5641ad503aa9")
});

// Get a collection of two specific content types by their numeric IDs
IEnumerable<IContentType> contentTypes = _contentTypeService.GetAll(1234, 1235);

To get a list of all Content Types of another content type, you can use the GetChildren method. This can be done by specifying the numeric ID or the GUID:

// Get a collection of content types of a specific content type
IEnumerable<IContentType> contentTypes = _contentTypeService.GetChildren(1232);

IEnumerable<IContentType> contentTypes = _contentTypeService.GetChildren(Guid.Parse("4f89dd28-d038-4209-aaa1-06109b7946a7"));

Check whether a content type has children

In some cases it can be useful to check if a content type has children. The HasChildren method can be used to check whether a content type has children.

// Check if there are children
bool hasChildren = _contentTypeService.HasChildren(Guid.Parse("2b54088e-d355-4b9e-aa4b-5aec4b3f87eb"));

Although the use of a GUID is preferable, you can also use it's numeric ID:

// Check if there are children
bool hasChildren = _contentTypeService.HasChildren(1234);

Retrieving content type container

Getting a single content type container

You can add content types in three different ways. At the root level, under another content type, or under a container (which is a folder). To obtain a single container, the process is similar to obtaining a single content type. This means that you can search for a container either by its GUID:

// Declare the GUID ID
Guid guid = new Guid("d3b9cc9a-d471-4465-a89a-112c6bc1e5b4");

// Get a container by its GUID ID
EntityContainer container = _contentTypeService.GetContainer(guid);

or its numeric counterpart:

// Get a container by its numeric ID
EntityContainer container = _contentTypeService.GetContainer(1090);

Getting a list of content type containers

In the same way as you can get the content types of a container, you can get the child containers of another container. This is done by calling the GetContainers method with an array of numeric IDs:

// Declare the array of IDs to lookup
int[] ids = new[] {1090};

// Get the child containers via the content type service
IEnumerable<EntityContainer> containers = _contentTypeService.GetContainers(ids);

Also, if the array is empty, all containers will be returned:

// Declare the array of IDs to lookup
int[] ids = new int[0];

// Get all content type containers
IEnumerable<EntityContainer> containers = _contentTypeService.GetContainers(ids);

Localization Service

Example on how to retrieve languages using the LocalizationService.

Learn how to use the Localization service to retrieve languages.

Getting a single language

The localization service contains a number of methods for looking up languages. If you already know the ID of a specific language (eg. the default language has ID 1), you can use the GetLanguageById method to get the reference to that language:

// Get a reference to the language by its ID
ILanguage language1 = _localizationService.GetLanguageById(1);

As an alternative, you can look up a language by its ISO code via the GetLanguageByIsoCode method:

// Get a reference to the language by its ISO code
ILanguage language2 = _localizationService.GetLanguageByIsoCode("en-US");

The ISO code is a combination of the two-letter ISO 639-1 language code (lowercase) and two-letter ISO-3166 country code (uppercase). Eg. en-US for English in the United States, en-GB for English in the United Kingdom and da-DK for Danish in Denmark.

Both methods will return an instance of the ILanguage interface, which has traditional properties like Id and Key, but also properties specific to the language like CultureName, CultureInfo and IsoCode. You can see the API reference for further information on the properties of the interface.

Getting all languages

If you need instead need a list of all installed languages, you can use the GetAllLanguages method. It takes no parameters, and as such a returns a collection of all languages (with no pagination like some of the other services):

// Get a collection of all languages
IEnumerable<ILanguage> languages = _localizationService.GetAllLanguages();

// Iterate over the collection
foreach (ILanguage language in languages)
{
    // Get the .NET culture info
    CultureInfo cultureInfo = language.CultureInfo;

    <pre>ID: @language.Id</pre>
    <pre>Key: @language.Key</pre>
    <pre>Name: @language.CultureName</pre>
    <pre>ISO: @language.IsoCode</pre>
    <pre>Culture info: @cultureInfo</pre>
    <hr />
}

As shown in the example above, you can get the System.Globalization.CultureInfo instance of each language. The CultureInfo determines how numbers, dates and similar should be either parsed or formatted in .NET.

Full example

Below you can see a full example of the examples shown above - including the necessary imports:

@using System.Globalization
@using Umbraco.Cms.Core.Models
@using Umbraco.Cms.Core.Services
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@inject ILocalizationService LocalizationService

@{
    // Get a collection of all languages
    IEnumerable<ILanguage> languages = LocalizationService.GetAllLanguages();

    // Iterate over the collection
    foreach (ILanguage language in languages)
    {

        // Get the .NET culture info
        CultureInfo cultureInfo = language.CultureInfo;

        <pre>ID: @language.Id</pre>
        <pre>Key: @language.Key</pre>
        <pre>Name: @language.CultureName</pre>
        <pre>ISO: @language.IsoCode</pre>
        <pre>Culture info: @cultureInfo</pre>
        <hr />

    }

    // Get a reference to the language by its ID
    ILanguage language1 = LocalizationService.GetLanguageById(1);

    // Get a reference to the language by its ISO code
    ILanguage language2 = LocalizationService.GetLanguageByIsoCode("en-US");

    <pre>@language1</pre>
    <pre>@language2</pre>
}

The above example is using ILocalizationService which is currently obselete and will be removed in v15. Use ILanguageService or IDictionaryItemService (for dictionary item operations) instead.

User Service

This will show you how to perform various User management using the Umbraco service layer.

Learn how to use the User Service to manage the users on your Umbraco project.

Assigning a User to a User Group

To assign a User to a User Group, we need both the IUserService and IUserGroupService. As with all Umbraco services, these are obtained using dependency injection.

Start by defining an interface for our implementation:

Next we implement the interface. This implementation holds the dependency to the Umbraco services:

Lastly, we need to put our implementation to use. This could be done in a Management API controller:

Content Type Service

Examples on how to retrieve content types and content type containers using the ContentTypeService.

Learn how to work with Content Types through the Content Type Service.

Getting a single content type

// Declare the GUID ID
Guid guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");

// Get a reference to the content type by its GUID ID
IContentType contentType = _contentTypeService.Get(guid);

Although the use of a GUID is preferable, you can also use it's numeric ID:

// Get a reference to the content type by its numeric ID
IContentType contentType = _contentTypeService.Get(1234);

Finally, you can also look up a content type by its alias:

// Get a reference to the content type by its alias
IContentType contentType = _contentTypeService.Get("home");

Getting a list of content types

// Get a collection of all content types
IEnumerable<IContentType> contentTypes = _contentTypeService.GetAll();

// Get a collection of two specific content types by their GUIDs IDs
IEnumerable<IContentType> contentTypes = _contentTypeService.GetAll(new[] {
    new Guid("2b54088e-d355-4b9e-aa4b-5aec4b3f87eb"),
    new Guid("859c5916-19d8-4a72-9bd0-5641ad503aa9")
});

// Get a collection of two specific content types by their numeric IDs
IEnumerable<IContentType> contentTypes = _contentTypeService.GetAll(1234, 1235);

To get a list of all Content Types of another content type, you can use the GetChildren method. This can be done by specifying the numeric ID or the GUID:

// Get a collection of content types of a specific content type
IEnumerable<IContentType> contentTypes = _contentTypeService.GetChildren(1232);

IEnumerable<IContentType> contentTypes = _contentTypeService.GetChildren(Guid.Parse("4f89dd28-d038-4209-aaa1-06109b7946a7"));

Check whether a content type has children

In some cases it can be useful to check if a content type has children. The HasChildren method can be used to check whether a content type has children.

// Check if there are children
bool hasChildren = _contentTypeService.HasChildren(Guid.Parse("2b54088e-d355-4b9e-aa4b-5aec4b3f87eb"));

Although the use of a GUID is preferable, you can also use it's numeric ID:

// Check if there are children
bool hasChildren = _contentTypeService.HasChildren(1234);

Retrieving content type container

Getting a single content type container

// Declare the GUID ID
Guid guid = new Guid("d3b9cc9a-d471-4465-a89a-112c6bc1e5b4");

// Get a container by its GUID ID
EntityContainer container = _contentTypeService.GetContainer(guid);

or its numeric counterpart:

// Get a container by its numeric ID
EntityContainer container = _contentTypeService.GetContainer(1090);

Getting a list of content type containers

// Declare the array of IDs to lookup
int[] ids = new[] {1090};

// Get the child containers via the content type service
IEnumerable<EntityContainer> containers = _contentTypeService.GetContainers(ids);

Also, if the array is empty, all containers will be returned:

// Declare the array of IDs to lookup
int[] ids = new int[0];

// Get all content type containers
IEnumerable<EntityContainer> containers = _contentTypeService.GetContainers(ids);

Using Umbraco services

Getting a Service

Examples on using services

Consent Service

What is a Consent

Register a new consent

Get the current state

Revoking a consent

Examples

Media Service

Creating a new folder

Creating a new media item from a stream

Relation Service

Automatically relate to the root node

Content Service

Creating content programmatically

Content Type Service

Getting a single content type

Getting a list of content types

Check whether a content type has children

Retrieving content type container

Getting a single content type container

Getting a list of content type containers

Localization Service

Getting a single language

Getting all languages

Full example

User Service

Assigning a User to a User Group

Consent Service

What is a Consent

Register a new consent

Get the current state

Revoking a consent

Examples

Using Umbraco services

Getting a Service

Examples on using services

Media Service

Creating a new folder

Creating a new media item from a stream

Content Type Service

Getting a single content type

Getting a list of content types

Check whether a content type has children

Retrieving content type container

Getting a single content type container

Getting a list of content type containers

Localization Service

Getting a single language

Getting all languages

Full example

Content Service

Creating content programmatically

Relation Service

Automatically relate to the root node

User Service

Assigning a User to a User Group