Content Service
Learn how to get, create, and publish content using the Content Service.
The IContentService reads and manages content items (IContent) in the database. It works with both draft and published versions. Use it for management tasks such as imports, migrations, and background jobs.
Render or read published content
IPublishedContentCache or IPublishedContentQuery. See Querying.
Create, update, or publish content as a specific user, identified by key
IContentEditingService and IContentPublishingService
Manage content directly, without validation
IContentService
The examples on this page use two Document Types: Catalogue and Product. Product is allowed as a child of Catalogue. Product has a category property (Textstring) and a price property (Numeric).
Replace the aliases and keys with values from your own project.
Getting Content
The following example retrieves content by key. GetCategory() reads a property value from a single content item. GetChildren() returns a page of the item's children.
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Services;
namespace MyProject.Services;
public class GetContentDemo
{
private readonly IContentService _contentService;
public GetContentDemo(IContentService contentService) => _contentService = contentService;
public string? GetCategory(Guid key)
{
IContent? content = _contentService.GetById(key);
// Reads the draft value. Pass published: true to read the published value.
return content?.GetValue<string>("category");
}
public IEnumerable<IContent> GetChildren(Guid parentKey, int pageIndex, int pageSize)
{
IContent? parent = _contentService.GetById(parentKey);
if (parent is null)
{
return [];
}
return _contentService.GetPagedChildren(
parent.Id,
pageIndex,
pageSize,
out long totalRecords,
propertyAliases: null,
filter: null,
ordering: null);
}
}Pass null for propertyAliases to load all properties. Pass an empty array to load no custom properties.
Other retrieval methods include GetByIds(), GetRootContent(), GetPagedDescendants(), and GetPagedOfType().
Creating and Publishing Content
The following example creates a Product under a Catalogue page. It sets the property values, saves the content, and then publishes it.
IContentService saves content even when a mandatory value is missing, but Publish() returns FailedPublishContentInvalid.
Saving and Publishing in one Call
SaveAndPublish() saves and publishes in one call. The following example creates a Product and saves and publishes it with a single method call. For invariant content, pass an empty array.
Multilingual Content
For a Document Type that varies by culture, set a name for each culture. Save the content, and then pass the cultures to publish:
A successful culture publish returns the status SuccessPublishCulture. To publish all cultures, pass ["*"] to Publish(). To publish specific cultures with SaveAndPublish(), pass them explicitly, for example ["en-US", "da"].
For information on retrieving a site's languages, see Creating a Multilingual Site.
Publishing a Branch
The following example publishes a page and all its descendants, including descendants that have never been published.
The PublishBranchFilter option can include one or more of the following flags:
Default- publishes only published content with pending changes.IncludeUnpublished- publishes unpublished content and published content with pending changes.ForceRepublish- republishes all published content, even if unchanged.All- combinesIncludeUnpublishedandForceRepublish.
The root of the branch is published even if it has never been published, whichever filter you use. For multilingual content, replace "*" with the cultures to publish, for example ["en-US", "da"].
Identifying the User performing an Action
IContentService methods take an optional int userId. If you omit it, the action is recorded against the super user.
IContentService does not accept a user key. To record an action against a user identified by key, use one of the following approaches.
Using the Editing and Publishing Services
IContentEditingService and IContentPublishingService take a Guid userKey. Pass Constants.Security.SuperUserKey, or the key of a specific user.
The following example creates a Product with IContentEditingService, and then publishes it with IContentPublishingService. Both calls record the action against the user identified by userKey.
Unlike IContentService, IContentEditingService validates the Document Type, the parent, and the property values. If property validation fails, the content is still created. The status is PropertyValidationError, and Success is true. Check the status, not only Success.
From Umbraco 18.1, use IContentEditingService.CreateAndPublishAsync() to create and publish content in one call. Pass the cultures to publish as an ISet<string>. For invariant content, pass an empty set. The returned ContentEditingAndPublishingStatus reports the save and the publish outcomes separately. A publish blocked by a business rule still leaves the save in effect.
Resolving a User Key to an ID
To keep using IContentService, resolve the user key to an ID with IUserIdKeyResolver. The following example publishes existing content and records the action against the resolved user:
Reading Values from Date Property Editors
The Date Only, Date Time (Unspecified), Date Time (with time zone), and Time Only property editors store values as JSON:
IContentService returns this JSON as a string. The following example reads a Date Only property, deserializes it into a DateTimeDto, and returns a DateOnly:
The legacy Date Picker (Umbraco.DateTime) returns a DateTime, not JSON.
Last updated
Was this helpful?