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:

Creating a new folder

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

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

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

Again Umbraco will make sure the necessary properties are updated.

A service for handling lawful data processing requirements.

What is a Consent

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

Register a new consent

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

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

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.

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.

Examples on using services

• Consent Service

• User Service

• Content Service

• Media Service

• Relation Service

• Content Type Service

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

You can read more about composing Umbraco here

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

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.

1. Start by defining an interface for our implementation:

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

1. Register the implementation in a Composer:

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

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:

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

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

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:

The service also have GetMany-methods to get a collection of content types by their GUIDs IDs or numeric IDs:

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:

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.

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

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:

or its numeric counterpart:

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:

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

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:

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

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

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: