1 of 43

Management

Details of CRUD operations within Umbraco and how to interact with the data persisted in the database

The intended audience for these reference pages are .NET developers. It is assumed the reader already has knowledge of the basics of Umbraco and knows .NET & C#.

Since the release of Umbraco 10, we will no longer be updating the articles in this section.

You can find up-to-date code references for all Models in our API Documentation.

Models

Here you will find references for the models in the public API. The models include Content, ContentType, DataTypeDefinition, DictionaryItem, Language, Media, MediaType, Relation, RelationType, Task, TaskType, and Template classes.

Services

Here you will find references for the services which are available for performing Create, Read, Update and Delete (CRUD) operations for the models mentioned above.

Models Reference

Content

The Content class represents a single item in the content tree, its values are fetched directly from the database, not from the cache.

The Content class represents a single item in the content tree, its values are fetched directly from the database, not from the cache. Notice the Content class should strictly be used for CRUD operations, not complex queries, as it is not flexible nor fast enough for this.

All content is versioned, so on each individual change, a new version is stored. Past versions can only be retrieved from the Content api, not from the cache.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

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

Constructors

new Content(string name, IContent parent, IContentType contentType, string culture = null)

Constructor for creating a new Content object where the necessary parameters are the name of the Content, the parent of the Content as an IContent object and the ContentType as an IContentType object for the Content being created. In addition, there is an optional parameter for the culture.

new Content(string name, IContent parent, IContentType contentType, int userId, string culture = null)

Constructor for creating a new Content object where the necessary parameters are the name of the Content, the parent of the Content as an IContent object, the ContentType as an IContentType object for the Content being created and the id of the user as a int. In addition, there is an optional parameter for the culture.

new Content(string name, IContent parent, IContentType contentType, PropertyCollection properties, string culture = null)

Constructor for creating a new Content object where the necessary parameters are the name of the Content, the parent of the Content as an IContent object, the ContentType as an IContentType object and a PropertyCollection for the Content being created. In addition, there is an optional parameter for the culture.

new Content(string name, int parentId, IContentType contentType, string culture = null)

Constructor for creating a new Content object where the necessary parameters are the name of the Content, the id of the parent as int and the ContentType as an IContentType object for the Content being created. In addition, there is an optional parameter for the culture.

new Content(string name, int parentId, IContentType contentType, int userId, string culture = null)

Constructor for creating a new Content object where the necessary parameters are the name of the Content, the parent id of the Content as an int object, the ContentType as an IContentType object for the Content being created and the id of the user as a int. In addition, there is an optional parameter for the culture.

new Content(string name, int parentId, IContentType contentType, PropertyCollection properties, string culture = null)

Constructor for creating a new Content object where the necessary parameters are the name of the Content, the id of the parent as int, the ContentType as an IContentType object and a PropertyCollection for the Content being created.In addition, there is an optional parameter for the culture.

Properties

.CreateDate

Gets or Sets a DateTime object, indicating then the given Content was created.

// Given a `ContentService` object get Content by its Id and return CreateDate
var content = contentService.GetById(1234);
return content.CreateDate;

.CreatorId

Gets or Sets the Id of the User who created the Content.

// Given a `ContentService` object get Content by its Id and return the Id of the Creator
var content = contentService.GetById(1234);
return content.CreatorId;

.ContentType

Returns a ISimpleContentType object representing the DocumentType used by the given Content.

// Given a `ContentService` object get Content by its Id and return ContentType
var content = contentService.GetById(1234);
return content.ContentType;

.ContentTypeId

Returns the id as an int of the ContentType object representing the DocumentType used by the given Content.

// Given a `ContentService` object get Content by its Id and return the Id of the ContentType
var content = contentService.GetById(1234);
return content.ContentTypeId;

.Id

Returns the unique Content Id as a Int, this ID is based on a Database identity field, and is therefore not safe to reference in code which are moved between different instances, use Key instead.

.Key

Returns the Guid assigned to the Content during creation. This value is unique, and should never change, even if the content is moved between instances.

// Given a `ContentService` object get Content by its Id and return the Key
var content = contentService.GetById(1234);
return content.Key;

.PublishedCultures

Gets Languages of the Content as a IEnumerable<string>.

.Level

Gets or Sets the given Content level in the site hierarchy as an Int. Content placed at the root of the site, will return 1, content right underneath will return 2, and so on.

// Given a `ContentService` object get Content by its Id and return the Level
var content = contentService.GetById(1234);
return content.Level;

.Name

Gets or Sets the name of the content as a String.

// Given a `ContentService` object get Content by its Id and return its Name
var content = contentService.GetById(1234);
return content.Name;

.ParentId

Gets or Sets the parent Content Id as an Int.

// Given a `ContentService` object get Content by its Id and return the Id of the Parent Content
var content = contentService.GetById(1234);
return content.ParentId;

.Path

Gets or Sets the path of the content as a String. This string contains a comma separated list of the ancestor Ids including the current contents own id at the end of the string.

// Given a `ContentService` object get Content by its Id and return the Path
var content = contentService.GetById(1234);
return content.Path;

.Properties

Gets or Sets the IPropertyCollection object, which is a collection of IProperty objects. Each property corresponds to a PropertyType, which is defined on the ContentType.

// Given a `ContentService` object get Content by its Id and loop through all Properties
var content = contentService.GetById(1234);
foreach (var property in content.Properties)
{
    string alias = property.Alias;
    object value = property.GetValue();

}

.Published

Returns a Bool indicating whether the given Content is published and available on the website or not. Notice: the published flag does not check the current in-memory cache, so this flag is not a guarantee that the Content is/is not available in the cache and the frontend of the website.

// Given a `ContentService` object get Content by its Id and return Published
var content = contentService.GetById(1234);
return content.Published;

.PublishDate

If set, returns DateTime? indicating when the Content should be published and made available on the website and cache.

// Given a `ContentService` object get Content by its Id and set the release date to 4 days from now
var content = contentService.GetById(1234);
return content.PublishDate

.SortOrder

Returns the given Content index, compared to sibling content.

// Given a `ContentService` object get Content by its Id and return its SortOrder
var content = contentService.GetById(1234);
return content.SortOrder;

.PublishedState

Returns a IPublishedState enum with the status of the Content being either Unpublished, Published, Publishing, Unpublishing.

// Given a `ContentService` object get Content by its Id and return its Status
var content = contentService.GetById(1234);
return content.PublishedState;

.TemplateId

Gets or sets the template id used to render the content.

// Given a `ContentService` object get Content by its Id and return its Template
var content = contentService.GetById(1234);
return content.TemplateId;

.Trashed

Returns a Bool indicating whether the given Content is currently in the recycle bin.

// Given a `ContentService` object get Content by its Id and return Trashed
var content = contentService.GetById(1234);
return content.Trashed;

.UpdateDate

Gets or Sets a DateTime object, indicating when the given Content was last updated.

// Given a `ContentService` object get Content by its Id and return UpdateDate
var content = contentService.GetById(1234);
return content.UpdateDate;

.VersionId

Returns the current Version Id as a int, for each change made to a content item, its values are stored under a new Version. This version is identified by a int.

// Given a `ContentService` object get Content by its Id and return its Version
var content = contentService.GetById(1234);
return content.VersionId;

.WriterId

Gets or Sets the Id of the User who made the latest edit on the Content.

// Given a `ContentService` object get Content by its Id and return the Id of the Writer
var content = contentService.GetById(1234);
return content.WriterId;

Methods

.GetCreatorProfile(IUserService userService)

Gets the IProfile object for the Creator of this Content, which contains the Id and Name of the User who created this Content item.

// Given a `ContentService` object get Content by its Id and get the `IProfile` of the Creator
var content = contentService.GetById(1234);
var profile = content.GetCreatorProfile(userService);
var id = profile.Id;
string name = profile.Name;

.GetValue(string propertyTypeAlias)

Gets the value of a Property as an Object.

// Given a `ContentService` object get Content by its Id and get a value by alias
var content = contentService.GetById(1234);
object value = content.GetValue("bodyText");
string text = value as string;

.GetValue< TPassType >(string propertyTypeAlias)

Gets the value of a Property as the defined type 'TPassType'.

// Given a `ContentService` object get Content by its Id and get a value by alias while specifying the return type
var content = contentService.GetById(1234);
string value = content.GetValue<string>("bodyText");

.GetWriterProfile(IUserService userService)

Gets the IProfile object for the Writer of this Content, which contains the Id and Name of the User who last updated this Content item.

// Given a `ContentService` object get Content by its Id and get the `IProfile` of the Writer
var content = contentService.GetById(1234);
var profile = content.GetWriterProfile(userService);
var id = profile.Id;
string name = profile.Name;

.HasProperty(string propertyTypeAlias)

Returns a Bool indicating whether the Content object has a property with the supplied alias.

// Given a `ContentService` object get Content by its Id and check if certain properties exist
var content = contentService.GetById(1234);
bool tagsExists = content.HasProperty("myTagProperty");
bool bodyTextExists = content.HasProperty("bodyText");

.SetValue(string propertyTypeAlias, object value)

Sets the value of a property by its alias.

// Given a `ContentService` object get Content by its Id, set a few values
// and saves the Content through the `ContentService`
var content = contentService.GetById(1234);
content.SetValue("bodyText", "This text will be added to by RTE field");
content.SetValue("date", DateTime.Now);
contentService.Save(content);

.ToXml(IEntityXmlSerializer serializer)

Returns an XElement containing the Content data, based off the latest changes. Is used when the published content is sent to the in-memory xml cache.

// Given a `ContentService` object get Content by its Id and returns the xml
var content = contentService.GetById(1234);
XElement xml = content.ToXml(serializer);
return xml;

ContentType

A ContentType corresponds to the Document Type found in the backoffice.

A ContentType corresponds to the Document Type found in the backoffice. The ContentType is a model / data definition for your content nodes. Every content node on an Umbraco web site always maps to a backing Document Type.

A Document Type is composed by Properties, which are grouped by Tabs (or PropertyGroups in the API). It can also inherit properties and tabs from other Document Types.

It is possible to link one or more Templates to a Document Type. This determines how your model/data is rendered to the user.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

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

Constructors

ContentType(IShortStringHelper shortStringHelper, IContentType parent, string alias)

Constructor for creating a new ContentType object. The necessary parameters are a short string helper IShortStringHelper, the parent ContentType as an IContentType and the alias of the new ContentType as string.

new ContentType(IShortStringHelper shortStringHelper, int parentId)

Constructor for creating a new ContentType object where the necessary parameters are a short string helper IShortStringHelper and the Id of the parent ContentType as an Int.

Properties

.Alias

Gets or Sets the Alias as a String of the ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return Alias
var contentType = contentTypeService.Get(1234);
return contentType.Alias;

.AllowedAsRoot

Gets or Sets a Bool indicating whether this ContentType is allowed at the root. If one or more ContentTypes are set to 'AllowedAsRoot' only they are shown in the create dialog at the root level in the backoffice.

// Given a `ContentTypeService` object get ContentType by its Id and return AllowedAsRoot
var contentType = contentTypeService.Get(1234);
return contentType.AllowedAsRoot;

.AllowedContentTypes

Gets or Sets an Enumerable list of ContentTypeSort objects of the ContentTypes allowed under the current ContentType.

The ContentTypeSort is an object with a lazy Id, int SortOrder and string Alias used to sort the MediaTypes within the list of AllowedContentTypes.

// Given a `ContentTypeService` object get ContentType by its Id and return AllowedContentTypes
var contentType = contentTypeService.Get(1234);
return contentType.AllowedContentTypes;

.AllowedTemplates

Gets or Sets an Enumerable list of ITemplates which are allowed for the current ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return AllowedTemplates
var contentType = contentTypeService.Get(1234);
return contentType.AllowedTemplates;

.ContentTypeComposition

Gets a list of ContentTypes as IContentTypeComposition objects that make up a composition of PropertyGroups and PropertyTypes for the current ContentType.

The ContentTypeComposition provides a mixin-type functionality in that you can compose a ContentType of one or more other ContentTypes in a complex structure. But please be aware that the backoffice does not fully support these complex structures yet.

// Given a `ContentTypeService` object get ContentType by its Id and return ContentTypeComposition
var contentType = contentTypeService.Get(1234);
return contentType.ContentTypeComposition;

.CompositionPropertyGroups

Gets a list of all 'PropertyGroup` objects from the composition including PropertyGroups from the current ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return CompositionPropertyGroups
var contentType = contentTypeService.Get(1234);
return contentType.CompositionPropertyGroups;

.CompositionPropertyTypes

Gets a list of all PropertyType objects from the composition including PropertyTypes from the current ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return CompositionPropertyTypes
var contentType = contentTypeService.Get(1234);
return contentType.CompositionPropertyTypes;

.CreateDate

Gets or Sets a DateTime object, indicating then the given ContentType was created.

// Given a `ContentTypeService` object get ContentType by its Id and return CreateDate
var contentType = contentTypeService.Get(1234);
return contentType.CreateDate;

.CreatorId

Gets or Sets the Id of the User who created the ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return the Id of the Creator
var contentType = contentTypeService.Get(1234);
return contentType.CreatorId;

.Description

Gets or Sets the Description as a String for the ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return the Description
var contentType = contentTypeService.Get(1234);
return contentType.Description;

.DefaultTemplate

Gets the default Template set as an ITemplate object for this ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return the DefaultTemplate
var contentType = contentTypeService.Get(1234);
return contentType.DefaultTemplate;

.Icon

Gets or Sets the Icon as a String for the ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return the Icon
var contentType = contentTypeService.Get(1234);
return contentType.Icon;

.Id

Gets the unique ContentType Id as an Int. The ID, derived from a database identity field, isn't safe for code references as they are moved across instances. Therefore it's recommended to use Key instead.

.Key

Gets the Guid assigned to the ContentType during creation. This value is unique, and should never change, even if the content is moved between instances.

// Given a `ContentTypeService` object get ContentType by its Id and return the Key
var contentType = contentTypeService.Get(1234);
return contentType.Key;

.Level

Gets or Sets the given ContentType level in the site hierarchy as an Int. ContentTypes placed at the root of the tree, will return 1, content right underneath will return 2, and so on.

// Given a `ContentTypeService` object get ContentType by its Id and return the Level
var contentType = contentTypeService.Get(1234);
return contentType.Level;

.Name

Gets or Sets the name of the ContentType as a String.

// Given a `ContentTypeService` object get ContentType by its Id and return its Name
var contentType = contentTypeService.Get(1234);
return contentType.Name;

.ParentId

Gets or Sets the parent ContentType Id as an Int.

// Given a `ContentTypeService` object get ContentType by its Id and return the Id of the Parent ContentType
var contentType = contentTypeService.Get(1234);
return contentType.ParentId;

.Path

Gets or Sets the path of the ContentType as a String. This string contains a comma separated list of the ancestors Ids including the current ContentTypes own id at the end of the string.

// Given a `ContentTypeService` object get ContentType by its Id and return the Path
var contentType = contentTypeService.Get(1234);
return contentType.Path;

.PropertyGroups

Gets or Sets a PropertyGroupCollection containing a list of PropertyGroups for the current ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return PropertyGroups
var contentType = contentTypeService.Get(1234);
return contentType.PropertyGroups;

.PropertyTypes

Gets an Enumerable list of PropertyTypes aggregated for all groups within the current ContentType, as well as PropertyTypes not within a group.

// Given a `ContentTypeService` object get ContentType by its Id and return PropertyTypes
var contentType = contentTypeService.Get(1234);
return contentType.PropertyTypes;

.SortOrder

Gets the given ContentType index, compared to sibling content.

// Given a `ContentTypeService` object get ContentType by its Id and return its SortOrder
var contentType = contentTypeService.Get(1234);
return contentType.SortOrder;

.Thumbnail

Gets or Sets the Thumbnail as a String for the ContentType.

// Given a `ContentTypeService` object get ContentType by its Id and return the Thumbnail
var contentType = contentTypeService.Get(1234);
return contentType.Thumbnail;

Methods

.AddContentType(IContentTypeComposition contentType)

Adds a new ContentType to the list of composite ContentTypes.

// Given a `ContentTypeService` object get a few ContentTypes by their alias
// and add the 'Meta' and 'SEO' ContentTypes to the composition of the 'Textpage' ContentType.
var metaContentType = contentTypeService.Get("meta");
var seoContentType = contentTypeService.Get("seo");
var textpageContentType = contentTypeService.Get("textPage");
textpageContentType.AddContentType(metaContentType);
textpageContentType.AddContentType(seoContentType);
contentTypeService.Save(textpageContentType);

.CompositionAliases()

Returns an Enumerable list of ContentType aliases as String from the current composition.

// Given a `ContentTypeService` object get a ContentType by its alias and loop through CompositionAliases
var contentType = contentTypeService.Get("textPage");
var aliases = contentType.CompositionAliases();

.CompositionIds()

Returns an Enumerable list of ContentType Ids as Int from the current composition.

// Given a `ContentTypeService` object get a ContentType by its alias and loop through CompositionIds
var contentType = contentTypeService.Get("textPage");
var ids = contentType.CompositionIds();

.ContentTypeCompositionExists(string alias)

Checks if a ContentType with the supplied alias exists in the list of composite ContentTypes.

// Given a `ContentTypeService` object get a ContentType by its alias
// and check if a given ContentType exists in the composition of the 'Text Page' ContentType.
var contentType = contentTypeService.Get("textPage");
bool result = contentType.ContentTypeCompositionExists("meta");

.SetDefaultTemplate(ITemplate template)

Sets the default Template for the current ContentType.

// Given a `ContentTypeService` object get a ContentType by its alias
// and change the default template with another one from the list of allowed templates.
var contentType = contentTypeService.Get("textPage");
ITemplate template = contentType.AllowedTemplates.First(x => x.Alias == "anotherTemplate");
contentType.SetDefaultTemplate(template);
contentTypeService.Save(contentType);

.RemoveContentType(string alias)

Removes a ContentType with the supplied alias from the list of composite ContentTypes.

// Given a `ContentTypeService` object get a ContentType by its alias and
// remove the 'Meta' ContentType from its composition.
var contentType = contentTypeService.Get("textPage");
bool success = contentType.RemoveContentType("meta");
if(success)
    contentTypeService.Save(contentType);

.RemovePropertyType(string propertyTypeAlias)

Removes a PropertyType from the current ContentType.

// Given a `ContentTypeService` object get a ContentType by its alias
// and remove a PropertyType from the list of PropertyTypes.
var contentType = contentTypeService.Get("textPage");
contentType.RemovePropertyType("author");
contentTypeService.Save(contentType);

.RemoveTemplate(ITemplate template)

Removes a Template from the list of allowed templates.

// Given a `ContentTypeService` object get a ContentType by its alias
// and remove one of the templates from the list of allowed templates.
var contentType = contentTypeService.Get("textPage");
ITemplate template = contentType.AllowedTemplates.First(x => x.Alias == "RemoveThisTemplate");
contentType.RemoveTemplate(template);
contentTypeService.Save(contentType);

DataType

A DataType is what you see in the backoffice in the Settings / DataTypes tree. The listed nodes are definitions of the DataTypes that are available to use on your PropertyTypes.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statement:

using Umbraco.Cms.Core.Models;

Constructors

new DataType(IDataEditor editor, IConfigurationEditorJsonSerializer serializer, int parentId = -1)

Constructor for creating a new DataType object where the necessary parameters are a IDataEditor and a IConfigurationEditorJsonSerializer. Optionally, the parentId can be added, if not provided the default value is -1, which means it will be created at root level.

Properties

.CreateDate

Gets or Sets a DateTime object, indicating then the given DataType was created.

.CreatorId

Gets or Sets the Id of the User who created the DataType.

.DatabaseType

Gets or Sets the DatabaseType as a ValueStorageType enum for which the DataType's value is saved as.

.Id

Returns the unique DataType ID as an Int. The ID, derived from a database identity field, isn't safe for code references as they are moved across instances. Therefore it's recommended to use Key instead.

.Key

Returns the Guid assigned to the DataType during creation. This value is unique, and should never change, even if the DataType is moved between instances.

.Level

Gets or Sets the given DataType level in the site hierarchy as an Int. DataType placed at the root of the site, will return 1, DataType right underneath will return 2, and so on.

.Name

Gets or Sets the name of the DataType as a String.

.ParentId

Gets or Sets the parent DataType Id as an Int.

.Path

Gets or Sets the path of the DataType as a String. This string contains a comma separated list of the ancestor Ids including the current contents own id at the end of the string.

.SortOrder

Returns the given DataType index, compared to sibling DataType.

.Trashed

Returns a Bool indicating whether the given DataType is currently in the recycle bin.

DictionaryItem

Represents a Dictionary Item. A Dictionary Item is what you see in the Translation / Dictionary tree.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statement:

using Umbraco.Cms.Core.Models;

Constructors

new DictionaryItem(string itemKey)

Constructor for creating a new DictionaryItem object where the necessary parameter is the key of the DictionaryItem as a string.

new DictionaryItem(Guid? parentId, string itemKey)

Constructor for creating a new DictionaryItem object where the necessary parameters are the parentKey as Guid and the key of the DictionaryItem as a string. Use this one if you want to create a DictionaryItem underneath another one.

Properties

.ItemKey

Gets or sets the Key for the Dictionary Item.

// Create a DictionaryItem and return the key
var dictionaryItem = new DictionaryItem("your_key");
return dictionaryItem.ItemKey;

.ParentId

Gets or Sets a Guid? of the Dictionary Item ParentId.

// Create a DictionaryItem and return the parentId
DictionaryItem dictionaryItem = new DictionaryItem("your_key");
Guid? parentId = dictionaryItem.ParentId;
return parentId;

.Translations

Gets or sets a IEnumerable<IDictionaryTranslation> of translations for the Dictionary Item.

// Create a DictionaryItem and return the translations
var dictionaryItem = new DictionaryItem("your_key");
return dictionaryItem.Translations;

Language

Represents a Language. Installed languages can be found in the settings section.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statement:

Constructors

new Language(GlobalSettings globalSettings, string isoCode)

Constructor for creating a new Language object where the necessary parameter are the global settings as GlobalSettings and the isoCode as a string.

To create a new Language the global setting parameter is necessary. You can find more info about how to use configuration in code in the .

Properties

.CultureInfo

Gets the CultureInfo object for the language.

.CultureName

Gets or sets the culture name of the language.

.FallbackLanguageId

Gets or sets the identifier of a fallback language. The fallback language can be used in multi-lingual scenarios, to help define fallback strategies when a value does not exist for a requested language.

.IsDefault

Gets or sets a value indicating whether the language is the default language.

.IsMandatory

Gets or sets a value indicating whether the language is mandatory. When a language is mandatory, a multi-lingual document cannot be published without that language being published, and unpublishing that language unpublishes the entire document.

.IsoCode

Gets or sets the ISO code of the language.

Media

The Media class represents a single item in the media tree.

The Media class represents a single item in the media tree, its values are fetched directly from the database, not from the cache. Notice the Media class should strictly be used for CRUD operations. Media is already stored in cache, so for querying Media you'd want to use the IUmbracoContext.IPublishedMediaCache to get the media. Then one would use .

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Constructors

new Media(string name, IMedia parent, IMediaType mediaType)

Constructor for creating a new Media object where the necessary parameters are the name of the Media, the parent of the Media as an IMedia object and the MediaType as an IMediaType object for the Media being created.

new Media(string name, IMedia parent, IMediaType mediaType, IPropertyCollection properties)

Constructor for creating a new Media object where the necessary parameters are the name of the Media, the parent of the Media as an IMedia object, the MediaType as an IMediaType object and a IPropertyCollection for the Media being created.

new Media(string name, int parentId, IMediaType mediaType)

Constructor for creating a new Media object where the necessary parameters are the name of the Media, the id of the parent as int and the MediaType as an IMediaType object for the Media being created.

new Media(string name, int parentId, IMediaType mediaType, IPropertyCollection properties)

Constructor for creating a new Media object where the necessary parameters are the name of the Media, the id of the parent as int, the MediaType as an IMediaType object and a IPropertyCollection for the Media being created.

Properties

.CreateDate

Gets or Sets a DateTime object, indicating then the given Media was created.

.CreatorId

Gets or Sets the Id of the User as an int who created the Media.

.ContentType

Returns a ISimpleContentType object representing the ContentType used by the given Media.

.ContentTypeId

Returns the id as an int of the MediaType object representing the ContentType used by the given Media.

.Id

Returns the unique Media Id as a Int, this ID is based on a Database identity field, and is therefore not safe to reference in code which are moved between different instances, use Key instead.

.Key

Returns the Guid assigned to the Media during creation. This value is unique, and should never change, even if the Media is moved between instances.

.Level

Gets or Sets the given Media level in the site hierarchy as an Int. Media placed at the root of the tree, will return 1, Media right underneath will return 2, and so on.

.Name

Gets or Sets the name of the Media as a String.

.ParentId

Gets or Sets the parent Media Id as an Int.

.Path

Gets or Sets the path of the Media as a String. This string contains a comma separated list of the ancestors Ids including the current medias own id at the end of the string.

.Properties

Gets or Sets the PropertyCollection object, which is a collection of Property objects. Each property corresponds to a PropertyType, which is defined on the MediaType.

.SortOrder

Returns the given Media index, compared to sibling media.

.Trashed

Returns a Bool indicating whether the given Media is currently in the recycle bin.

.UpdateDate

Gets or Sets a DateTime object, indicating when the given Media was last updated.

.Version

Returns the current Version Id as a Guid, For each change made to a Media item, its values are stored under a new Version. This version is identified by a Guid.

Methods

.ChangeContentType(IMediaType mediaType)

Changes the IMediaType for the current Media object and removes PropertyTypes and Properties, which are not part of the new MediaType. Please use with caution as this remove differences between the new and old MediaType.

.GetCreatorProfile()

Gets the IProfile object for the Creator of this Media, which contains the Id and Name of the User who created this Media item.

.GetValue(string propertyTypeAlias)

Gets the value of a Property as an Object.

.GetValue< TPassType >(string propertyTypeAlias)

Gets the value of a Property as the defined type 'TPassType'.

.HasProperty(string propertyTypeAlias)

Returns a Bool indicating whether the Media object has a property with the supplied alias.

.SetValue(string propertyTypeAlias, object value)

Sets the value of a property by its alias.

It is worth noting that it is also possible to pass a HttpPostedFile, HttpPostedFileBase or HttpPostedFileWrapper to the SetValue method, so it can be used for uploads.

.ToXml()

Returns an XElement containing the Media data, based off the latest changes. When the Media item is saved the xml is stored in the database.

MediaType

A MediaType is almost the same as a ContentType. I.e. a model / data definition for your media nodes.

A MediaType is almost the same as a , that is, a model / data definition for your media nodes

You can set icon, thumbnail and description. It is also possible to add groups and properties.

A Media Type differs from a Document Type in that it has no templates.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Constructors

new MediaType(IShortStringHelper shortStringHelper, int parentId)

Constructor for creating a new MediaType object where the necessary parameters are a short string helper IShortStringHelper and the Id of the parent MediaType as an Int.

new MediaType(IShortStringHelper shortStringHelper,IMediaType parent)

Constructor for creating a new MediaType object where the necessary parameter are a short string helper IShortStringHelper and the parent MediaType as an IMediaType object.

new MediaType(IShortStringHelper shortStringHelper, IMediaType parent, string alias)

This constructor creates a new MediaType object and requires the following parameters: a short string helper IShortStringHelper and the parent MediaType as an IMediaType object. Additionally, the alias of the MediaType should be provided as a string.

Properties

.Alias

Gets or Sets the Alias as a String of the MediaType.

.AllowedContentTypes

Gets or Sets an Enumerable list of ContentTypeSort objects of the MediaTypes allowed under the current MediaType.

The ContentTypeSort is an object with a lazy Id, int SortOrder and string Alias used to sort the MediaTypes within the list of AllowedContentTypes.

.ContentTypeComposition

Gets a list of MediaTypes as IContentTypeComposition objects that make up a composition of PropertyGroups and PropertyTypes for the current MediaType.

The ContentTypeComposition provides a mixin-type functionality in that you can compose a MediaType of one or more other MediaTypes in a complex structure. But please keep in mind that the backoffice does not fully support these complex structures yet

.CompositionPropertyGroups

Gets a list of all PropertyGroup objects from the composition including PropertyGroups from the current MediaType.

.CompositionPropertyTypes

Gets a list of all PropertyType objects from the composition including PropertyTypes from the current MediaType.

.CreateDate

Gets or Sets a DateTime object, indicating then the given MediaType was created.

.CreatorId

Gets or Sets the Id of the User who created the MediaType.

.Description

Gets or Sets the Description as a String for the MediaType.

.Icon

Gets or Sets the Icon as a String for the MediaType.

.Id

Retrieves the unique MediaType ID as an Int. This ID is based on a Database identity field and is therefore not safe to reference in code when moved between different instances.

.Key

Gets the Guid assigned to the MediaType during creation. This value is unique, and should never change, even if the content is moved between instances.

.Level

Gets or Sets the given MediaType level in the site hierarchy as an Int. MediaTypes placed at the root of the tree, will return 1, content right underneath will return 2, and so on.

.Name

Gets or Sets the name of the MediaType as a String.

.ParentId

Gets or Sets the parent MediaType Id as an Int.

.Path

Gets or Sets the path of the MediaType as a String. This string contains a comma separated list of the ancestor Ids including the current MediaTypes own id at the end of the string.

.PropertyGroups

Gets or Sets a PropertyGroupCollection containing a list of PropertyGroups for the current MediaType.

.PropertyTypes

Gets an Enumerable list of PropertyTypes aggregated for all groups within the current MediaType, as well as PropertyTypes not within a group.

.SortOrder

Gets the given MediaType index, compared to sibling content.

.Thumbnail

Gets or Sets the Thumbnail as a String for the MediaType.

Methods

.AddContentType(IContentTypeComposition mediaType)

Adds a new MediaType to the list of composite MediaTypes.

.CompositionAliases()

Returns an Enumerable list of MediaType aliases as String from the current composition.

.CompositionIds()

Returns an Enumerable list of MediaType Ids as Int from the current composition.

.ContentTypeCompositionExists(string alias)

Checks if a MediaType with the supplied alias exists in the list of composite MediaTypes.

.RemoveContentType(string alias)

Removes a MediaType with the supplied alias from the list of composite MediaTypes.

.RemovePropertyType(string propertyTypeAlias)

Removes a PropertyType from the current MediaType.

Relation

Represents a Relation between two items.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statement:

Constructors

new Relation(int parentId, int childId, IRelationType relationType)

Constructor for creating a new Relation object. The necessary parameters are the Id of the parent item as an int, the Id of the child as an int and the relationType as IRelationType.

new Relation(int parentId, int childId, Guid parentObjectType, Guid childObjectType, IRelationType relationType)

A second constructor exists but it should not be used because it is used to reconstruct a relation from the data source.

Properties

.ChildId

Gets or sets the Child Id of the Relation (Destination)

.Comment

Gets or sets a comment for the Relation

.ParentId

Gets or sets the Parent Id of the Relation (Source)

.RelationType

Gets or sets the RelationType for the Relation

.RelationTypeId

Gets the Id of the RelationType that this Relation is based on.

RelationType

The `RelationType` class represents a relation definition between two node types (content or media).

The RelationType class represents a relation definition between two node types (content or media). For example keeping track of node usage across the site, in order to avoid deleting content that is used else where. When querying a relation, it is typically done using the parent node key. However, if the RelationType is bidirectional, querying with the child node key is also possible.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statement:

Constructors

new RelationType(string name, string alias, bool isBidrectional, Guid? parentObjectType, Guid? childObjectType)

Create a new RelationType object with this constructor. It requires a string alias, the relation type's name, and a bool for bidirectionality. Additionally, specify the Guid? keys for both child and parent object types involved in the relation.

Properties

.Name

Gets or sets the Name of the RelationType as a String.

.Alias

Gets or sets the Alias of the RelationType as String.

.IsBidirectional

Gets or sets a boolean indicating whether the RelationType is Bidirectional (true) or Parent to Child (false)

.ParentObjectType

Gets or sets the Parents object type key as Guid?

.ChildObjectType

Gets or sets the Childs object type key as Guid?

ServerRegistration

Represents a registered server in a multiple-servers environment.

The ServerRegistration class represents a registered server in a multiple-servers environment.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statement:

using Umbraco.Cms.Core.Models;

Constructors

new ServerRegistration(string serverAddress, string serverIdentity, DateTime registered)

Constructor for creating a new ServerRegistration object. The necessary parameters are the serverAddress as a string, the serverIdentity as a string and the date and time of registration as a DateTime

new ServerRegistration(int id, string serverAddress, string serverIdentity, DateTime registered, DateTime accessed, bool isActive, bool isSchedulingPublisher)

A second constructor exists but it should not be used because it is used to reconstruct a ServerRegistration from the data source.

Properties

.Accessed

Gets the date and time the registration was last accessed.

// Given a `IServerRegistrationService` object get the first ServerRegistration and return Accessed
var serverRegistration = serverRegistrationService.GetActiveServers().FirstOrDefault();
return serverRegistration.Accessed;

.IsActive

Gets or sets a value indicating whether the server is active.

// Given a `IServerRegistrationService` object get the first ServerRegistration and return IsActive
var serverRegistration = serverRegistrationService.GetActiveServers().FirstOrDefault();
return serverRegistration.IsActive;

.IsSchedulingPublisher

Gets or sets a value indicating whether the server has the SchedulingPublisher role

// Given a `IServerRegistrationService` object get the first ServerRegistration and return IsSchedulingPublisher
var serverRegistration = serverRegistrationService.GetActiveServers().FirstOrDefault();
return serverRegistration.IsSchedulingPublisher;

.Registered

Gets the date and time the registration was created.

// Given a `IServerRegistrationService` object get the first ServerRegistration and return Registered
var serverRegistration = serverRegistrationService.GetActiveServers().FirstOrDefault();
return serverRegistration.Registered;

.ServerAddress

Gets or sets the server URL.

// Given a `IServerRegistrationService` object get the first ServerRegistration and return ServerAddress
var serverRegistration = serverRegistrationService.GetActiveServers().FirstOrDefault();
return serverRegistration.ServerAddress;

.ServerIdentity

Gets or sets the server unique identity.

// Given a `IServerRegistrationService` object get the first ServerRegistration and return ServerIdentity
var serverRegistration = serverRegistrationService.GetActiveServers().FirstOrDefault();
return serverRegistration.ServerIdentity;

Template

Represents a Template file.

Namespace: Umbraco.Cms.Core.Models
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Constructors

new Template(IShortStringHelper shortStringHelper, string name, string alias)

Constructor for creating a new Template object. The necessary parameters include a short String Helper as an IShortStringHelper. The name and alias of the Template must be provided as string values.

Properties

.Alias

Gets the Alias of the File, which is the name without the extension.

.IsMasterTemplate

Returns true if the template is used as a layout for other templates (that is, it has 'children')

.MasterTemplateAlias

Returns the alias of the master template if one is set.

.MasterTemplateId

Returns the id of the master template if one is set.

.Name

Gets the Name of the File including extension.

Methods

.SetMasterTemplate(ITemplate masterTemplate)

Sets the master template of the template.

Services Reference

AuditService

The AuditService acts as a "gateway" to Umbraco data for operations which are related to the audit trail.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

For Razor views:

Getting the service

Dependency Injection

If you wish to use the audit service in a class, you need to use Dependency Injection (DI). For instance if you have registered your own class in Umbraco's DI container, you can specify the IAuditService interface in your constructor:

In Razor views, you can access the audit service through the @inject directive:

ConsentService

Browse the API documentation for ConsentService.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

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

In Razor views, you can access the consent service through the @inject directive:

@inject IConsentService ConsentService

DataTypeService

The DataTypeService acts as a "gateway" to Umbraco data for operations which are related to DataTypes and DataTypeDefinitions.

Browse the API documentation for IDataTypeService.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

using Umbraco.Cms.Core.Services;

For Razor views:

@using Umbraco.Cms.Core.Services

Getting the service

Dependency Injection

If you wish to use the Data Type service in a class, you need to specify the IDataTypeService interface in your constructor:

public class MyClass
{
    private IDataTypeService _dataTypeService;

    public MyClass(IDataTypeService dataTypeService)
    {
        _dataTypeService = dataTypeService;
    }
}

In Razor views, you can access the Data Type service through the @inject directive:

@inject IDataTypeService DataTypeService

DomainService

The DomainService acts as a "gateway" to Umbraco data for operations which are related to domains.

Browse the API documentation for IDomainService.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

using Umbraco.Cms.Core.Services;

For Razor views:

@using Umbraco.Cms.Core.Services

Getting the service

Dependency Injection

If you wish to use the domain service in a class, you need to specify the IDomainService interface in your constructor:

public class MyClass
{
    private IDomainService _domainService;

    public MyClass(IDomainService domainService)
    {
        _domainService = domainService;
    }
}

In Razor views, you can access the domain service through the @inject directive:

@inject IDomainService DomainService

EntityService

The EntityService acts as a "gateway" to Umbraco data for operations which are related to entities.

Browse the API documentation for IEntityService interface.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

using Umbraco.Cms.Core.Services;

For Razor views:

@using Umbraco.Cms.Core.Services

Getting the service

Dependency Injection

If you wish to use the entity service in a class, you need to specify the IEntityService interface in your constructor:

public class MyClass
{
 private IEntityService _entityService;

 public MyClass(IEntityService entityService)
 {
  _entityService = entityService;
 }
}

In Razor views, you can access the entity service through the @inject directive:

@inject IEntityService EntityService

ExternalLoginService

The ExternalLoginService is used to store the external login info and can be replaced with your own implementation.

Browse the API documentation for IEntityService interface.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

using Umbraco.Cms.Core.Services;

Getting the service

Dependency Injection

If you wish to use the entity service in a class, you need to specify the IExternalLoginService interface in your constructor:

public class MyClass
{
 private IExternalLoginService _externalLoginService;

 public MyClass(IExternalLoginService externalLoginService)
 {
  _externalLoginService = externalLoginService;
 }
}

In Razor views, you can access the entity service through the @inject directive:

@inject IExternalLoginService ExternalLoginService

FileService

The FileService acts as a "gateway" to Umbraco data for operations which are related to Scripts, Stylesheets and Templates.

Browse the API documentation for IFileService.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

using Umbraco.Cms.Core.Services;

For Razor views:

@using Umbraco.Cms.Core.Services

Getting the service

Dependency Injection

If you wish to use the file service in a class, you need to specify the IFileService interface in your constructor:

public class MyClass
{
    private IFileService _fileService;

    public MyClass(IFileService fileService)
    {
        _fileService = fileService;
    }
}

In Razor views, you can access the file service through the @inject directive:

@inject IFileService FileService

MacroService

MacrosService will be removed in the next version.

Defines the MacroService, which is an access to operations involving IMacro.

Browse the API documentation for IMacroService interface.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

using Umbraco.Cms.Core.Services;

For Razor views:

@using Umbraco.Cms.Core.Services

Getting the service

Dependency Injection

If you wish to use the macro service in a class, you need to specify the IMacroService interface in your constructor:

public class MyClass
{
    private IMacroService _macroService;

    public MyClass(IMacroService macroService)
    {
        _macroService = macroService;
    }
}

In Razor views, you can access the macro service through the @inject directive:

@inject IMacroService MacroService

MediaService

The MediaService acts as a "gateway" to Umbraco data for operations which are related to media.

Browse the API documentation for IMediaService interface.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require reference to the following packages:

Umbraco.Cms.Core

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;

Getting the service

Dependency Injection

If you wish to use the media service in a class, you need to specify the IMediaService interface in your constructor:

public class MyClass
{
    private IMediaService _mediaService;

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

In Razor views, you can access the media service through the @inject directive:

@inject IMediaService MediaService

Samples

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.

MemberGroupService

The MemberGroupService acts as a "gateway" to Umbraco data for operations which are related to Member groups, which are also known as Member Roles.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

For Razor views:

Getting the service

Dependency Injection

If you wish to use the member group service in a class, you need to specify the IMemberGroupService interface in your constructor:

In Razor views, you can access the member group service through the @inject directive:

MemberService

The MemberService acts as a "gateway" to Umbraco data for operations which are related to Members.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

For Razor views:

Getting the service

Dependency Injection

If you wish to use the member service in a class, you need to specify the IMemberService interface in your constructor:

In Razor views, you can access the member service through the @inject directive:

MemberTypeService

The MemberTypeService acts as a "gateway" to Umbraco data for operations which are related to MemberTypes.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

For Razor views:

Getting the service

Dependency Injection

If you wish to use the member type service in a class, you need to specify the IMemberTypeService interface in your constructor:

In Razor views, you can access the member type service through the @inject directive:

NotificationService

The NotificationServices is used to perform operations related to backoffice notifications.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Getting the service

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the INotificationService interface in your constructor:

In Razor views, you can access the member type service through the @inject directive:

PackagingService

The PackagingService provides import/export functionality for the Core models of the API.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Getting the service

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the IPackagingService interface in your constructor:

In Razor views, you can access the member service through the @inject directive:

PublicAccessService

Service to handle public access.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Getting the service

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the IPublicAccessService interface in your constructor:

In Razor views, you can access the member service through the @inject directive:

RedirectUrlService

The RedirectUrlService is used for Create, Read, Update and Delete (CRUD) operations related to Redirects.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Getting the service

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the IRedirectUrlService interface in your constructor:

In Razor views, you can access the member service through the @inject directive:

RelationService

The RelationService is pretty awesome as it allows you to create relations between objects that would otherwise have no obvious connection.

Browse the API documentation for IRelationService interface.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

Getting the service

using System.Web.Mvc;
using Umbraco.Web.Models;
using Umbraco.Web.Mvc;

using Umbraco.Cms.Core.Services;

```csharp
public class MyClass
{
    private IRelationService _relationService_;

 public MyClass(IRelationService relationService)
 {
  _relationService_ = relationService;
 }

Methods

AreRelated(int parentId, int childId, string relationTypeAlias)

Checks if two items are related.

Returns bool.

AreRelated(IUmbracoEntity parent, IUmbracoEntity child, string relationTypeAlias)

Checks if two items are related.

Returns bool.

AreRelated(int parentId, int childId)

Checks if two items are related.

Returns bool.

Delete(IRelation relation)

Deletes a relation.

Returns void.

Delete(IRelationType relationType)

Deletes a relation type.

Returns void.

DeleteRelationsOfType(IRelationType relationType)

Deletes relation of the specified relation type.

Returns void.

GetAllRelations(params int[] ids)

Gets a collection of Umbraco.Core.Models.Relation objects. Optional array of integer ids to return relations for.

Returns IEnumerable<IRelation>.

GetAllRelationsByRelationType(RelationType relationType)

Gets a collection of Umbraco.Core.Models.Relation objects by their relation type.

Returns IEnumerable<IRelation>.

GetAllRelationsByRelationType(int relationTypeId)

Gets a collection of Umbraco.Core.Models.Relation objects by their relation type id.

Returns IEnumerable<IRelation>.

GetAllRelationTypes(params int[] ids)

Gets a collection of Umbraco.Core.Models.Relation objects. Optional array of integer ids to return relationtypes for.

Returns IEnumerable<IRelationType>.

GetByChild(IUmbracoEntity child)

Gets a collection of Umbraco.Core.Models.Relation objects by their child entity.

Returns IEnumerable<IRelation>.

GetByChild(IUmbracoEntity child, string relationTypeAlias)

Gets a collection of Umbraco.Core.Models.Relation objects their child entity and relation type alias.

Returns IEnumerable<IRelation>.

GetByChildId(int id)

Gets a collection of Umbraco.Core.Models.Relation objects by their child id.

Returns IEnumerable<IRelation>.

GetById(int id)

Gets a Umbraco.Core.Models.Relation object by its id.

Returns IRelation.

GetByParent(IUmbracoEntity parent, string relationTypeAlias)

Gets a collection of Umbraco.Core.Models.Relation objects by their parent entity and relation type alias.

Returns IEnumerable<IRelation>.

GetByParent(IUmbracoEntity parent)

Gets a collection of Umbraco.Core.Models.Relation objects by their parent entity.

Returns IEnumerable<IRelation>.

GetByParentId(int id)

Gets a collection of Umbraco.Core.Models.Relation objects by their parent id.

Returns IEnumerable<IRelation>.

GetByParentOrChildId(int id, string relationTypeAlias)

Gets a collection of Umbraco.Core.Models.Relation objects by their parent or child id and relation type alias.

Returns IEnumerable<IRelation>.

Using this method will get you all relations regards of it being a child or parent relation.

GetByParentOrChildId(int id)

Gets a collection of Umbraco.Core.Models.Relation objects by their parent or child id.

Returns IEnumerable<IRelation>.

Using this method will get you all relations regards of it being a child or parent relation.

GetByRelationTypeAlias(string relationTypeAlias)

Gets a collection of Umbraco.Core.Models.Relation objects by their relation type alias.

Returns IEnumerable<IRelation>.

GetByRelationTypeId(int relationTypeId)

Gets a collection of Umbraco.Core.Models.Relation objects by the id of their relation type.

Returns IEnumerable<IRelation>.

GetByRelationTypeName(string relationTypeName)

Gets a collection of Umbraco.Core.Models.Relation objects by the name of their relation type.

Returns IEnumerable<IRelation>.

GetChildEntitiesFromRelations(IEnumerable relations)

Gets the child objects from a collection of IRelation as a collection of Umbraco.Core.Models.Entities.IUmbracoEntity.

Returns IEnumerable<IUmbracoEntity>.

GetChildEntityFromRelation(IRelation relation)

Gets the child object from a relation as an Umbraco.Core.Models.Entities.IUmbracoEntity object.

Returns IUmbracoEntity.

GetEntitiesFromRelation(IRelation relation)

Gets the parent and child objects from a relation as a System.Tuple with Umbraco.Core.Models.Entities.IUmbracoEntity.

Returns Tuple<IUmbracoEntity, IUmbracoEntity>.

GetEntitiesFromRelations(IEnumerable relations)

Gets the parent and child objects from a collection of relations as a list of Umbraco.Core.Models.Entities.IUmbracoEntity objects.

Returns IEnumerable<Tuple<IUmbracoEntity, IUmbracoEntity>>.

GetParentEntitiesFromRelations(IEnumerable relations)

Gets the parent objects from a collection of relations as a collection of Umbraco.Core.Models.Entities.IUmbracoEntity.

Returns IEnumerable<IUmbracoEntity>.

GetParentEntityFromRelation(IRelation relation)

Gets the parent object from a relation as an Umbraco.Core.Models.Entities.IUmbracoEntity object.

GetRelationTypeByAlias(string alias)

Gets an relation by its alias.

Returns IRelationType.

GetRelationTypeById(Guid id)

Gets a relation type by its Id

Returns IRelationType.

GetRelationTypeById(int id)

Gets a relation type by its id.

Returns IRelationType.

HasRelations(IRelationType relationType)

Checks if any relations exist for the specified relation type.

Returns bool.

IsRelated(int id)

Checks if any relations exist for the specified id.

Returns void.

Relate(int parentId, int childId, IRelationType relationType)

Relates two objects by their ids using the specified relation type.

Returns IRelation.

Relate(IUmbracoEntity parent, IUmbracoEntity child, IRelationType relationType)

Relates two IUmbracoEntity objects using the specified relation type.

Returns IRelation.

Relate(IUmbracoEntity parent, IUmbracoEntity child, string relationTypeAlias)

Relates two IUmbracoEntity objects using the specified relation type alias.

Returns IRelation.

Relate(int parentId, int childId, string relationTypeAlias)

Relates two IUmbracoEntity objects using the specified relation type alias.

Returns IRelation.

Save(IRelation relation)

Saves a relation.

Returns Void.

Save(IRelationType relationType)

Saves a relation type.

Returns Void.

Examples

Below you will examples using the RelationService.

Automatically relate to root node

Odd example, I know.. but why not?

To perform the said task we need a component in which we can register to the ContentService.Published event:

using System.Linq;
using Umbraco.Core.Composing;
using Umbraco.Core.Events;
using Umbraco.Core.Services;
using Umbraco.Core.Services.Implement;

namespace Doccers.Core.Components;

public class RelationComponent : IComponent
{
    private readonly IRelationService _relationService;

    public RelationComponent(IRelationService relationService)
    {
        _relationService = relationService;
    }

    public void Initialize()
    {
        ContentService.Published += ContentService_Published;
    }

    private void ContentService_Published(IContentService sender,
        ContentPublishedEventArgs e)
    {
        // Should never be null, to be honest.
        var home = sender.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 e.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);
            }
        }
    }

    public void Terminate() {
        //unsubscribe during shutdown
        ContentService.Published -= ContentService_Published;
    }
}

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

using Doccers.Core.Components;
using Umbraco.Core;
using Umbraco.Core.Composing;

namespace Doccers.Core.Composers;

[RuntimeLevel(MinLevel = RuntimeLevel.Run)]
public class RelationComposer : IUserComposer
{
    public void Compose(Composition composition)
    {
        composition.Components().Append<RelationComponent>();
    }
}

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

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

using System;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using Umbraco.Core.Services;
using Umbraco.Web.WebApi;

namespace Doccers.Core.Controllers.Http;

public class RelationsController : UmbracoApiController
{
    private readonly IRelationService _relationService;

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

    [HttpGet]
    public HttpResponseMessage GetByRelationTypeAlias(string alias)
    {
        var relationType = _relationService.GetRelationTypeByAlias(alias);
        if (relationType == null)
            return Request.CreateResponse(HttpStatusCode.BadRequest,
                "Invalid relation type alias");

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

        return Request.CreateResponse(HttpStatusCode.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 to this it is recommended that you wrap a caching layer around it, as the RelationService queries the database directly.

ServerRegistrationService

The ServerRegistrationService manages server registrations in the database.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

The Umbraco.Core.dll allows you to reference the Constants classes used in the below examples.

All samples in this document will require the following using statements:

For Razor views:

Getting the service

Dependency Injection

If you wish to use the server registration service in a class, you need to specify the IServerRegistrationService interface in your constructor:

In Razor views, you can access the server registration service through the @inject directive:

TagService

Tag service to query for tags in the tags db table.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Getting the service

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the ITagService interface in your constructor:

In Razor views, you can access the member service through the @inject directive:

TextService

The TextService is the entry point to localize any key in the text storage source for a given culture.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Getting the service

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the ILocalizedTextService interface in your constructor:

In Razor views, you can access the member service through the @inject directive:

ContentService

The ContentService acts as a "gateway" to Umbraco data for operations which are related to Content.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

For Razor views:

Getting the service

If you wish to use the content service in a class, you need to use Dependency Injection (DI) in your constructor:

In Razor views, you can access the content service through the @inject directive:

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

```csharp
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.

ContentTypeService

The content type service acts as a "gateway" to Umbraco data for operations which are related to both content types and media types.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

For Razor views:

Getting the service

Dependency Injection

If you wish to use the content type service in a class, you need to specify the IContentTypeService interface in your constructor:

In Razor views, you can access the content type service through the @inject directive:

Samples

Retrieving content types

Getting a single content type container

Content types can be added either at the root level, under another content type or under a content type container (or folders as they're called in the Umbraco backoffice). The approach for getting a single container is similar to getting a single content type, meaning that you can look up 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:

Retrieving content types

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:

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:

To get a list of all content types of another content type, you can instead use the GetChildren method - either 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:

LocalizationService

The LocalizationService acts as a "gateway" to Umbraco data for operations which are related to Dictionary items and Languages.

Browse the API documentation for ILocalizationService.

Namespace: Umbraco.Cms.Core.Services
Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

using Umbraco.Cms.Core.Services;

For Razor views:

@using Umbraco.Cms.Core.Services

Getting the service

Dependency Injection

If you wish to use the localization service in a class, you need to specify the ILocalizationService interface in your constructor:

public class MyClass
{
    private ILocalizationService _localizationService;

    public MyClass(ILocalizationService localizationService)
    {
        _localizationService = localizationService;
    }
}

In Razor views, you can access the localization service through the @inject directive:

@inject ILocalizationService LocalizationService

Samples

Retrieving languages See examples on how to retrieve languages via the localization service - either individually or as a collection.

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

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, which 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:

UserService

The UserService acts as a "gateway" to Umbraco data for operations which are related to Users.

Namespace: Umbraco.Core.Services
Assembly: Umbraco.Core.dll

All samples listed in this document will require references to the following dll:

Umbraco.Core.dll

All samples in this document will require the following using statements:

Getting the service

Services property

UmbracoAuthorizedApiController has been removed from Umbraco 14. Use ManagementApiControllerBase class instead.
UmbracoApiController is obsolete in Umbraco 14 and will be removed in Umbraco 15.

If you wish to use the UserService in a class that inherits from one of the Umbraco base classes (eg. SurfaceController, UmbracoApiController or UmbracoAuthorizedApiController), you can access the service through a local Services property:

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the IUserService interface in your constructor:

Static accessor

If neither a Services property or Dependency Injection is available, you can also reference the static Current class directly:

Samples

Creating a user

This will show you how to create a new user using the UserService in Umbraco.

If you want to create a new user, you'd use ASP.NET identity APIs like it is used in core.

Assigning the user to a user group

Permissions aren't administered for the specific user, but rather for the user group(s) that the user is a part of. So to add our new user to a user group, we first need to get a reference to the user via the GetUserGroupByAlias method, and then use the AddGroup method for adding the group to our user:

To make sure that these changed are saved to the database, we must also make sure to call the Save method. The GetUserGroupByAlias method takes the alias of a user group - eg. admin for the default Administrators user group.