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.

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.

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:

ISampleUserHandler.cs

namespace UmbracoDocs.Samples;

public interface ISampleUserHandler
{
    Task<bool> AssignUserToAdminGroup(string email, Guid performingUserKey);
}

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

SampleUserHandler.cs

using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Models.Membership;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Services.OperationStatus;

namespace UmbracoDocs.Samples;

public class SampleUserHandler : ISampleUserHandler
{
    private readonly IUserService _userService;
    private readonly IUserGroupService _userGroupService;

    public SampleUserHandler(IUserService userService, IUserGroupService userGroupService)
    {
        _userService = userService;
        _userGroupService = userGroupService;
    }

    public async Task<bool> AssignUserToAdminGroup(string email, Guid performingUserKey)
    {
        IUser? user = _userService.GetByEmail(email);
        if (user is null)
        {
            return false;
        }

        Attempt<UserGroupOperationStatus> result = await _userGroupService.AddUsersToUserGroupAsync(
            new UsersToUserGroupManipulationModel(Constants.Security.AdminGroupKey, [user.Key]),
            performingUserKey
        );

        return result.Success;
    }
}

SampleUserHandlerComposer.cs

using Umbraco.Cms.Core.Composing;

namespace UmbracoDocs.Samples;

public class SampleUserHandlerComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.AddSingleton<ISampleUserHandler, SampleUserHandler>();
}

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

SampleUserController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Management.Controllers;
using Umbraco.Cms.Api.Management.Routing;
using Umbraco.Cms.Core.Security;

namespace UmbracoDocs.Samples;

[ApiExplorerSettings(GroupName = "Sample user handler")]
[VersionedApiBackOfficeRoute("sample/user-handler")]
public class SampleUserController : ManagementApiControllerBase
{
    private readonly ISampleUserHandler _sampleUserHandler;
    private readonly IBackOfficeSecurityAccessor _backOfficeSecurityAccessor;

    public SampleUserController(
        ISampleUserHandler sampleUserHandler,
        IBackOfficeSecurityAccessor backOfficeSecurityAccessor)
    {
        _sampleUserHandler = sampleUserHandler;
        _backOfficeSecurityAccessor = backOfficeSecurityAccessor;
    }

    [HttpPut]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> AssignUserToAdminGroup(string email)
        => await _sampleUserHandler.AssignUserToAdminGroup(email, CurrentUserKey(_backOfficeSecurityAccessor))
            ? Ok()
            : BadRequest();
}

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.

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.

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.

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:

ISampleUserHandler.cs

namespace UmbracoDocs.Samples;

public interface ISampleUserHandler
{
    Task<bool> AssignUserToAdminGroup(string email, Guid performingUserKey);
}

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

SampleUserHandler.cs

using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Models.Membership;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Services.OperationStatus;

namespace UmbracoDocs.Samples;

public class SampleUserHandler : ISampleUserHandler
{
    private readonly IUserService _userService;
    private readonly IUserGroupService _userGroupService;

    public SampleUserHandler(IUserService userService, IUserGroupService userGroupService)
    {
        _userService = userService;
        _userGroupService = userGroupService;
    }

    public async Task<bool> AssignUserToAdminGroup(string email, Guid performingUserKey)
    {
        IUser? user = _userService.GetByEmail(email);
        if (user is null)
        {
            return false;
        }

        Attempt<UserGroupOperationStatus> result = await _userGroupService.AddUsersToUserGroupAsync(
            new UsersToUserGroupManipulationModel(Constants.Security.AdminGroupKey, [user.Key]),
            performingUserKey
        );

        return result.Success;
    }
}

SampleUserHandlerComposer.cs

using Umbraco.Cms.Core.Composing;

namespace UmbracoDocs.Samples;

public class SampleUserHandlerComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.AddSingleton<ISampleUserHandler, SampleUserHandler>();
}

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

SampleUserController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Management.Controllers;
using Umbraco.Cms.Api.Management.Routing;
using Umbraco.Cms.Core.Security;

namespace UmbracoDocs.Samples;

[ApiExplorerSettings(GroupName = "Sample user handler")]
[VersionedApiBackOfficeRoute("sample/user-handler")]
public class SampleUserController : ManagementApiControllerBase
{
    private readonly ISampleUserHandler _sampleUserHandler;
    private readonly IBackOfficeSecurityAccessor _backOfficeSecurityAccessor;

    public SampleUserController(
        ISampleUserHandler sampleUserHandler,
        IBackOfficeSecurityAccessor backOfficeSecurityAccessor)
    {
        _sampleUserHandler = sampleUserHandler;
        _backOfficeSecurityAccessor = backOfficeSecurityAccessor;
    }

    [HttpPut]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> AssignUserToAdminGroup(string email)
        => await _sampleUserHandler.AssignUserToAdminGroup(email, CurrentUserKey(_backOfficeSecurityAccessor))
            ? Ok()
            : BadRequest();
}

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>

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

Content Service

Creating content programmatically

User Service

Assigning a User to a User Group

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

Content Service

Creating content programmatically

User Service

Assigning a User to a User Group

Localization Service

Getting a single language

Getting all languages

Full example