1 of 11

Querying & Models

Overview of multiple ways of querying, filtering, and searching published content for use on your website.

Umbraco stores identifiers in UDI format for most Umbraco object types. This identifier stores all of the metadata required to retrieve an Umbraco object and is parse-able within text. Example: umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2. UDI's can be used in many of the querying APIs.

IPublishedContent is strongly typed model for content, media and members that is used to render content in your views for your website.

UmbracoHelper is the unified way to work with published content/media on your website. Whether you are using MVC or WebForms you will be able to use UmbracoHelper to query/traverse Umbraco published data.

IMemberManager is an user manager interface for accessing member data in the form of MemberIdentityUser and converting it to IPublishedContent.

The IPublishedContentQuery interface contains query methods for accessing strongly typed content in services etc.

The ITagQuery interface allows to work with tags in Umbraco.

The UmbracoContext is a simplified way to work with the current request on your website.

IMemberManager

Using the IMemberManager1

IMemberManager is an user manager interface for accessing member data in the form of MemberIdentityUser and converting it to IPublishedContent. IMemberManager has a variety of methods that are useful in views and controllers. For the list of methods, see the .

How to reference IMemberManager

There are different ways to reference MembershipHelper:

Views

While working with templates, the methods are available when you inject @IMemberManager to access member data:

Dependency Injection

If you wish to use the IMemberManager in a class that inherits from one of the Umbraco base classes (eg. SurfaceController, UmbracoApiController, or UmbracoAuthorizedApiController), you can use Dependency Injection. For instance, if you have registered your own class in Umbraco's dependency injection, you can specify the IMemberManager interface in your constructor:

Examples

Finding members

IMemberManager has multiple ways to find members.

FindByIdAsync(string)

Finds a member by their ID

If we want to find a member by Udi or Guid we need to to inject IIdKeyMap service:

Find member by Udi

Find member by Guid

FindByEmailAsync(string)

Finds a member by their email.

FindByNameAsync(string)

Finds a member by their login name.

AsPublishedMember(MemberIdentityUser)

By default IMemberManager returns members as MemberIdentityUser. This method allows you to convert a MemberIndentityUser into IPublishedContent:

GetCurrentMemberAsync()

Returns the currently logged in member if there is one, else returns null value.

GetUserIdAsync()

Returns the user id of a user

IsLoggedIn()

Checks if a member is logged in.

IsMemberAuthorizedAsync(IEnumerable memberTypes, IEnumerable memberGroups, IEnumerable memberIds)

Checks if the current member is authorized for content protected by types, groups or specific members. For instance, you can use this method to check if the current logged in member is authorized. This is particularly useful for pages only available to the VIP member group, like so:

IsProtectedAsync()

MemberHasAccessAsync(string)

MemberManager can also be used to manage users.

ValidateCredentialsAsync(string username, string password)

Validates that a user's credentials are correct without logging them in.

IPublishedContentQuery

Querying in views with IPublishedContentQuery in Umbraco

The IPublishedContentQuery interface contains different query methods for accessing strongly typed content in services etc.

How to inject IPublishedContentQuery

In order to inject the IPublishedContentQuery into your services, you must add a using statement for Umbraco.Cms.Core and inject the service using the constructor.

using Umbraco.Cms.Core;

namespace Umbraco.Docs.Samples.Web.Services
{
    public class SearchService
    {
        private readonly IPublishedContentQuery _publishedContentQuery;

        public SearchService(IPublishedContentQuery publishedContentQuery)
        {
            _publishedContentQuery = publishedContentQuery;
        }
    }
}

Now you can access the IPublishedContentQuery through _publishedContentQuery

Examples

.Search(string term)

By default, IPublishedContentQuery will search on Umbraco's 'External' search index for any published content matching the provided search term.

public IEnumerable<PublishedSearchResult> Search(string searchTerm)
{
    foreach (var result in _publishedContentQuery.Search(searchTerm))
    {
        yield return result;
    }
}

.Search(string term, int skip, int take, out long totalRecords)

Specifying the number of records 'to skip' and the number of records 'to take' improves performance with many matching search results. This approach is beneficial when there is a requirement to implement paging.

public IEnumerable<PublishedSearchResult> Search(string searchTerm, int skip = 5, int take = 10)
{
    foreach (var result in _publishedContentQuery.Search(searchTerm, skip, take, out long totalRecords))
    {
        yield return result;
    }
}

.Search(IQueryExecutor queryExecutor)

For more complex searching you can construct an Examine QueryExecutor. In the example the search will execute against content of type "blogPost" only. Further information on using Examine

using System;
using System.Collections.Generic;
using Examine;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Infrastructure.Examine;
using Umbraco.Extensions;

namespace Umbraco.Docs.Samples.Web.Services
{
    public class SearchService
    {
        private readonly IPublishedContentQuery _publishedContentQuery;
        private readonly IExamineManager _examineManager;

        public SearchService(IPublishedContentQuery publishedContentQuery, IExamineManager examineManager)
        {
            _publishedContentQuery = publishedContentQuery;
            _examineManager = examineManager;
        }

        public IEnumerable<PublishedSearchResult> Search(string searchTerm)
        {
            if (!_examineManager.TryGetIndex(Constants.UmbracoIndexes.ExternalIndexName, out IIndex index))
            {
                throw new InvalidOperationException($"No index found by name{Constants.UmbracoIndexes.ExternalIndexName}");
            }

            var query = index.Searcher.CreateQuery(IndexTypes.Content);
            var queryExecutor = query.NodeTypeAlias("blogPost").And().ManagedQuery(searchTerm);

            foreach (var result in _publishedContentQuery.Search(queryExecutor))
            {
                yield return result;
            }
        }
    }
}

ITagQuery

Working with tags in Umbraco

The ITagQuery interface is your primary way to work with tags in Umbraco. This interface allows you to get different tags, such as content tags and media tags. It also lets you retrieve content by tag, for instance, getting all content nodes with the "Umbraco" tag.

How to reference ITagQuery

If you're using it in Views or Partial views you can inject ITagQuery using the @inject keyword, for example

@inject ITagQuery _tagQuery;

After this you can use _tagQuery to access the ITagQuery.

If you're using it in controllers, you can inject it into the constructor like so:

using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Core.PublishedCache;
using Umbraco.Cms.Web.Common.Controllers;

namespace UmbracoHelperDocs.Controllers
{
    [Route("tags/[action]")]
    public class TagApiController : UmbracoApiController
    {
        private readonly ITagQuery _tagQuery;

        public TagApiController(ITagQuery tagQuery)
        {
            _tagQuery = tagQuery;
        }

        public ActionResult<IEnumerable<string>> GetMediaTags()
        {
            return _tagQuery.GetAllMediaTags().Select(tag => tag.Text).ToList();
        }
    }
}

ITagQuery is a scoped service, meaning that it should only be injected into scoped or transient services. For more information see the official Microsoft Documentation

Examples

All examples are from a view using the injection shown above, but working with tags in controllers will be the same.

Get a collection of tags used by content items on the site. Optionally, you can pass in a group name to only list tags belonging to a specific tag group

@{
	var allContentTags = _tagQuery.GetAllContentTags();
	var newsContentTags = _tagQuery.GetAllContentTags("news");
}

Get a collection of tags used by media items on the site. Optionally, you can pass in a group name to only list tags belonging to a specific tag group

@{
	var allMediaTags = _tagQuery.GetAllMediaTags();
	var newsMediaTags = _tagQuery.GetAllMediaTags("news");
}

Get a collection of tags used by members on the site. Optionally, you can pass in a group name to only list tags belonging to a specific tag group

@{
	var allMemberTags = _tagQuery.GetAllMemberTags();
	var newsMemberTags = _tagQuery.GetAllMemberTags("news");
}

Get a collection of tags used on the site. Optionally, you can pass in a group name to only list tags belonging to a specific tag group

@{
	var allTags = _tagQuery.GetAllTags();
	var allNewsTags = _tagQuery.GetAllTags("news");
}

Get a collection of IPublishedContent by tag, and you can optionally filter by tag group as well

@{
	var taggedContent = _tagQuery.GetContentByTag("News");
}

Get a collection of IPublishedContent by tag group

@{
	var taggedContent = _tagQuery.GetContentByTagGroup("BlogTags");
}

Get a collection of Media by tag, and you can optionally filter by tag group as well

@{
	var taggedMedia = _tagQuery.GetMediaByTag("BlogTag");
}

Get a collection of Media by tag group

@{
	var mediaByTagGroup = _tagQuery.GetMediaByTagGroup("BlogTags");
}

Get a collection of tags by entity id (queries content, media and members), and you can optionally filter by tag group as well

@{
	var tagsForEntity = _tagQuery.GetTagsForEntity(1234);
}

Get a collection of tags assigned to a property of an entity (queries content, media and members). Optionally, you can filter by tag group as well

@{
	var propertyTags = _tagQuery.GetTagsForProperty(1234, "propertyTypeAlias");
}

UDI Identifiers

Introduction

UDI is currently not an acronym for something. There is no official definition of what it's short for. Therefore it's called UDI

Format

An Umbraco UDI consists of three parts: the scheme, the type and a GUID Identifier. For example: umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2.

Breaking it down:

The scheme is umb:// - this is always the same and makes it identifiable as an Umbraco UDI
The type is document - so in this is an Umbraco node, but it could also be media, member, etc.
The GUID Id is 4fed18d8c5e34d5e88cfff3a5b457bf2 - this is a GUID (dashes removed) which is randomly generated when the item is being created

Usage

You can use UDIs in some of the Querying and Management/Service APIs.

There are 2 types of UDIs:

GUID UDI

String UDI

UmbracoContext helper

The UmbracoContext is a helpful service provided on each request to the website

The UmbracoContext is the simplified way to work with the current request on your website.

You can use UmbracoContext to access the content and media cache. Other useful properties are the original and cleaned URLs of the current request. You can also check if the current request is running in "preview" mode.

How to reference UmbracoContext

If you are using Views or Partial View Macros you can reference the UmbracoContext with the syntax: @UmbracoContext

If you need an UmbracoContext in your own controllers, you need to inject an IUmbracoContextAccessor.

The following is an example of how to get access to the UmbracoContext in a controller:

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Web.Common.Controllers;
using Umbraco.Cms.Web.Common.PublishedModels;
using Umbraco.Extensions;

namespace Umbraco.Docs.Samples.Web.Controllers.Api;

public class PeopleController : UmbracoApiController
{
    private readonly IUmbracoContextAccessor _umbracoContextAccessor;

    public PeopleController(IUmbracoContextAccessor umbracoContextAccessor)
    {
        _umbracoContextAccessor = umbracoContextAccessor;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> GetAll()
    {
        if (_umbracoContextAccessor.TryGetUmbracoContext(out IUmbracoContext? context) == false)
        {
            return this.Problem("unable to get content");
        }

        if (context.Content == null)
        {
            return this.Problem("Content Cache is null");
        }

        var personContentType = context.Content.GetContentType(Person.ModelTypeAlias);
        Debug.Assert(context.Content.HasContent());
        var personNodes = (context.Content.GetAtRoot()
                .First()
                .FirstChild<People>()
                .Children<Person>() ?? Array.Empty<Person>())
            .Select(p => p.Name);
        return personContentType == null
            ? this.Problem("Person Content Type is null")
            : Ok(personNodes);
    }
}

UmbracoContext is registered with a scoped lifetime. See the Microsoft documentation for more information. A service scope is created for each request, which means you can resolve an instance directly in a controller.

UmbracoHelper

Using the Umbraco Helper

UmbracoHelper is the unified way to work with published content/media on your website. You can use the UmbracoHelper to query/traverse Umbraco published data.

UmbracoHelper also has a variety of helper methods that are useful when working in your views and controllers.

How to reference UmbracoHelper

If you are using Views or Partial View Macros you can reference UmbracoHelper with the syntax: @Umbraco

If you need an UmbracoHelper in your own controllers, you need to inject an instance.

Example of getting UmbracoHelper in a controller:

If you need to use an UmbracoHelper in a service with a singleton lifetime you would instead need to make use of the IUmbracoHelperAccessor interface to obtain a temporary reference to an instance.

IPublishedContent

UmbracoHelper will expose all content in the form of IPublishedContent. To get a reference to the currently executing content item from the UmbracoHelper, use UmbracoHelper.AssignedContentItem.

The samples below demonstrate using UmbracoHelper in Razor. Working with the UmbracoHelper will be the same in controllers, except for the fact that you must resolve it with IUmbracoHelperAccessor like shown above.

Working with Content

.Content(Guid id)

Given a node ID, returns a IPublishedContent

.ContentAtRoot()

Returns a collection of IPublishedContent objects from the Content tree.

.ContentAtXPath(string xpath)

Queries the cache for content matching a given XPath query and returns a collection of IPublishedContent objects.

.ContentSingleAtXPath(string xpath)

Queries the cache for content matching a given XPath query and returns the first match as an IPublishedContent object.

Working with Media

.Media(Guid id)

Given a node ID, returns an IPublishedContent Media entity

.MediaAtRoot()

Returns a collection of IPublishedContent objects from the Media tree.

Working with Tags

Working with Members

Searching

Fetching Dictionary Values

.GetDictionaryValue(string key)

Returns a dictionary value(string) for the key specified.

Alternatively, you can also specify an altText which will be returned if the dictionary value is empty.

Templating Helpers

.RenderMacro(string alias, object parameters)

Renders a macro in the current page content, given the macro's alias, and parameters required by the macro.

.RenderTemplateAsync(int contentId, int? altTemplateId)

Renders a template asynchronously, as if a page with the given contentId was requested, optionally with an alternative template ID passed in.

IPublishedContent

IPublishedContent is a strongly typed model for content, media and members and is used to render content in your views for your website.

Get started

To access the current page in your templates, copy-paste the below Razor code.

Listing and explanation of IPublishedContent properties and standard helpers for Content and Media.

Methods for IPublishedContent collections and filtering.

A library of extension methods to simplify working with IPublishedContent in collections to modify your HTML output. Examples of using IsHelpers could be injecting CSS classes for alternating rows or to modify margins.

IPublishedContent Collections

All collections of IPublishedContent are IEnumerable<IPublishedContent>. This means that all C# LINQ statements can be used to filter and query the collections.

Collections

.Children

Returns a collection of child items available in the current culture, below the current content item.

.ChildrenForAllCultures

Returns a collection of child items for all cultures, below the current content item, regardless of whether they are available for the current culture.

.Children(string culture = null)

Returns a collection of child items available in the specified culture with a default of the current one, below the current content item.

.Ancestors()

Returns all ancestors of the current page (parent page, grandparent and so on)

.Ancestor()

Returns the first ancestor of the current page

.AncestorsOrSelf()

Returns a collection of all ancestors of the current page (parent page, grandparent and so on), and the current page itself

.Descendants()

Returns all descendants of the current page (children, grandchildren etc)

.DescendantsOrSelf()

Returns all descendants of the current page (children, grandchildren etc), and the current page itself

.OfTypes

Filters a collection of content by content type alias

Filtering, Ordering & Extensions

Filtering and Ordering are done with LINQ.

Some examples:

.Where

.OrderBy

.GroupBy

Groups collection by content type alias

.Take(int)

Return only the number of items for a collection specified by the integer value.

.Skip(int)

Return items from the collection after skipping the specified number of items.

You can combine Skip and Take when using for paging operations

.Count()

Returns the number of items in the collection

.Any()

Returns a boolean True/False value determined by whether there are any items in the collection

Filtering Conventions

.IsVisible()

If you create a checkbox property on a document type with an alias umbracoNaviHide then the value of this property is used by the IsVisible() extension method when filtering.

Use case: When displaying a navigation menu for a section of the site, following this convention gives editors the option to 'hide' certain pages from appearing in the section navigation. (hence the unusual umbracoNaviHide property alias!)

IPublishedContent IsHelpers

The IsHelper methods are a set of extension methods for IPublishedContent to help perform quick conditional queries against IPublishedContent nodes in a collection.

IsHelper methods are ternary operators, however they work a little nicer since they can be embedded in properties. They are also quicker to write because fewer brackets are needed for Razor to understand them.

How to use

An IsHelper can be invoked as a method of an IPublishedContent.

IsHelper Methods

IsComposedOf(string alias)

Test whether the content is of a content type composed of the given alias.

IsAllowedTemplate(int templateId)

Test whether the specified templateId is an allowed template for the current node.

IsAllowedTemplate(string templateAlias)

Test whether the specified templateAlias is an allowed template for the current node.

By default the above template methods are disabled. To enable them, make sure to modify your appsettings.json to include the following JSON config keys inside Umbraco.CMS section:

.IsEqual(IPublishedContent otherNode[,string valueIfTrue][,string valueIfFalse])

Test if the current node is equal (by Id) to another node.

.IsNotEqual(IPublishedContent otherNode[,string valueIfTrue][,string valueIfFalse])

Test if the current node is not equal (by Id) to another node.

.IsDescendant(IPublishedContent otherNode[,string valueIfTrue][,string valueIfFalse])

Test if the current node is a descendant of another node.

.IsDescendantOrSelf(IPublishedContent otherNode[,string valueIfTrue][,string valueIfFalse])

Test if the current node is the same as or a descendant of another node.

.IsAncestor(IPublishedContent otherNode[,string valueIfTrue][,string valueIfFalse])

Test if the current node is an ancestor of another node.

.IsAncestorOrSelf(IPublishedContent otherNode[,string valueIfTrue][,string valueIfFalse])

Test if the current node is the same as or an ancestor of another node.

IPublishedContent Property Access & Extension Methods

Umbraco Properties

Built-in properties, which exists on all content objects by default

Common Examples

.Id

Returns the unique Id for the current content item

.Name

Returns the Name of the current content item in the current culture

.Name(IVariationContextAccessor, string culture = null)

Returns the Name of the current content item in the specified culture, null falls back to the current culture

.ContentType

Returns a strongly typed 'PublishedContentType' object representing the content type the IPublishedContent item is based on, that gives access to the alias

.GetCultureFromDomains(IUmbracoContextAccessor, ISiteDomainHelper, Uri current = null)

Returns a culture from a configured domain in the content tree.

.Parent

Returns the parent content item

.Path

Returns a comma delimited string of Node Ids that represent the path of content items back to root.

.Level

Returns the Level (depth) this content item is in its tree path

.TemplateId

Returns the id of the default Template object used with this content item.

There are extension methods to retrieve template alias (Model.GetTemplateAlias())

.SortOrder

Returns the index the page is on, compared to its siblings

.Url(PublishedUrlProvider, culture = null, UrlMode mode = UrlMode.Default) - (Extension method)

Returns the Url to the page.

Example: Getting a Danish Url for a site where a Danish language has been set up.

Example: Getting an Absolute Danish Url for a site where a Danish language has been set up.

.UrlSegment

Returns the Url encoded name of the page (slug) of the current culture

.UrlSegment(IVariationContextAccessor, string culture = null)

Returns the Url encoded name of the page (slug) of the specified culture

.WriterId

Returns the id of the Umbraco backoffice user that performed the last update operation on the content item.

.WriterName(IUserService)

Returns the name of the Umbraco backoffice user that initially created the content item.

.CreatorId

Returns the id of the Umbraco backoffice user that initially created the content item

.CreatorName(IUserService)

Returns the name of the Umbraco backoffice user that initially created the content item.

.CreateDate

Returns the DateTime the page was created

.UpdateDate

Returns the DateTime the page was modified

Custom properties

All content and media items contain a reference to all the data defined by their Document Type. Custom property access is achieved using variations of the method: Value

Model.Value(IPublishedValueFallback, string)

Returns the property value for the specified property alias

The type returned of this property value is object. This is fine in most cases since when using the above syntax, Razor will automatically execute a ToString() on the result value.

See Model.Value<T>(string) for how to return a strongly typed object for the property

Model.Value<T>(string)

Returns the property value for the specified property alias converted to 'T' - the requested output type of the property value.

For example, to return the string result of "siteName":

Fallbacks

If the current content item doesn't have the requested value, use an alternative 'fallback' value in its place.

Each of the examples below make use of an injected PublishedValueFallback. This is achieved by adding the following at the top of your Razor file:

This parameter is optional, but can make unit testing easier.

Fallback to Default Value

If a content page has a 'title' property, to fallback to use the 'Name' of the content item if the 'title' is not populated. Set the Fallback type to be Fallback.ToDefaultValue, and set the DefaultValue accordingly:

or to a specific value

Fallback to Ancestors

Look for a property value on the current page. If it doesn't exist look for the property value on the parent page. Then the parent's parent page and so on. This approach allows specifying 'global property values' all the way up the content tree. These values can be overridden in different sections or individual pages.

Fallback to Language

If working with variants - fallback to a different language value - if perhaps the value hasn't been populated yet for the current language:

Combining the Fallback options

Use Fallback.To() to 'combine' Fallback options.

The following would first look for a 'title' property on all ancestors, before defaulting to the current page's name:

Property Methods

There are a few helpful methods to help check if a property exists, has a value or is null.

.HasProperty(string propertyAlias)

Returns a boolean value representing if the IPublishedContent has a property with the specified alias.

.HasValue(string propertyAlias)

Returns a boolean value representing if the IPublishedContent property has had a value set.

It's possible to use 'Fallbacks' with HasValue:

IMemberManager

Using the IMemberManager1

How to reference IMemberManager

There are different ways to reference MembershipHelper:

Views

While working with templates, the methods are available when you inject @IMemberManager to access member data:

Dependency Injection

Examples

Finding members

IMemberManager has multiple ways to find members.

FindByIdAsync(string)

Finds a member by their ID

@{
    var memberById = await _memberManager.FindByIdAsync("1234");
    // Do stuff with the member, for instance checking if email is confirmed
    var emailConfirmed = memberById.EmailConfirmed;
}

If we want to find a member by Udi or Guid we need to to inject IIdKeyMap service:

Find member by Udi

var memberUdiAttempt = _idKeyMap.GetIdForUdi(nodeUdi);
if (memberUdiAttempt.Success)
{
   var memberId = memberUdiAttempt.Result;
   var member = await _memberManager.FindByIdAsync(memberId.ToString());
}

Find member by Guid

var memberKeyAttempt = _idKeyMap.GetIdForKey(nodeKey);
if (memberKeyAttempt.Success)
{
   var memberId = memberKeyAttempt.Result;
   var member = await _memberManager.FindByIdAsync(memberId.ToString());
}

FindByEmailAsync(string)

Finds a member by their email.

@{
    var memberById = await _memberManager.FindByEmailAsync("test@member.com");
    // Do stuff with the member, for instance checking if email is confirmed
    var emailConfirmed = memberById.EmailConfirmed;
}

FindByNameAsync(string)

Finds a member by their login name.

@{
    var memberById = await _memberManager.FindByNameAsync("TestLoginName");
    // Do stuff with the member, for instance checking if email is confirmed
    var emailConfirmed = memberById.EmailConfirmed;
}

AsPublishedMember(MemberIdentityUser)

By default IMemberManager returns members as MemberIdentityUser. This method allows you to convert a MemberIndentityUser into IPublishedContent:

@{
    MemberIdentityUser memberById = await _memberManager.FindByEmailAsync("test@member.com");
    IPublishedContent memberAsContent = _memberManager.AsPublishedMember(memberById);
}

GetCurrentMemberAsync()

Returns the currently logged in member if there is one, else returns null value.

@{
    var currentMember = await _memberManager.GetCurrentMemberAsync();
}

@if (currentMember is not null)
{
    <p>A member is logged in, member username: @currentMember.UserName</p>
}
else
{
    <p>No member is logged in.</p>
}

GetUserIdAsync()

Returns the user id of a user

@{
	var userId = await _memberManager.GetUserIdAsync(user);
}

IsLoggedIn()

Checks if a member is logged in.

@if (_memberManager.IsLoggedIn())
{
    <p>A member is logged in</p>
}
else
{
    <p>No member is logged in.</p>
}

IsMemberAuthorizedAsync(IEnumerable memberTypes, IEnumerable memberGroups, IEnumerable memberIds)

@{
    var memberIsAuthorized = await _memberManager.IsMemberAuthorizedAsync(allowGroups: new []{"VIP"});
}

IsProtectedAsync()

Returns a Task<bool> specifying if the page with a given has public access restrictions set.

<ul>
    @foreach (var child in Model.Children)
    {
        @if (await _memberManager.IsProtectedAsync(child.Path))
        {
            <li>@child.Name - Members only!</li>
        }
        else
        {
            <li>@child.Name - Access to everyone!</li>
        }
    }
</ul>

MemberHasAccessAsync(string)

Returns a Task<bool> specifying if the currently logged in member has access to the page given its .

<ul>
    @foreach (var child in Model.Children)
    {
        // Only display the page if the current member has access to it.
        @if (await _memberManager.MemberHasAccessAsync(child.Path))
        {
            <li>@child.Name</li>
        }
    }
</ul>

MemberManager can also be used to manage users.

ValidateCredentialsAsync(string username, string password)

Validates that a user's credentials are correct without logging them in.

@{
	var isValidCredentials = await _memberManager.ValidateCredentialsAsync(userName, password);
}

IPublishedContent Property Access & Extension Methods

Umbraco Properties

Built-in properties, which exists on all content objects by default

Common Examples

.Id

Returns the unique Id for the current content item

.Name

Returns the Name of the current content item in the current culture

@Model.Name

.Name(IVariationContextAccessor, string culture = null)

Returns the Name of the current content item in the specified culture, null falls back to the current culture

@Model.Name(VariationContextAccessor, "dk-dk")

.ContentType

Returns a strongly typed 'PublishedContentType' object representing the content type the IPublishedContent item is based on, that gives access to the alias

@Model.ContentType
@Model.ContentType.Alias

.GetCultureFromDomains(IUmbracoContextAccessor, ISiteDomainHelper, Uri current = null)

Returns a culture from a configured domain in the content tree.

@Model.GetCultureFromDomains(ContextAccessor, DomainHelper)

.Parent

Returns the parent content item

@Model.Parent
@Model.Parent.Name

.Path

Returns a comma delimited string of Node Ids that represent the path of content items back to root.

@Model.Path

.Level

Returns the Level (depth) this content item is in its tree path

@Model.Level

.TemplateId

Returns the id of the default Template object used with this content item.

@Model.TemplateId

There are extension methods to retrieve template alias (Model.GetTemplateAlias())

.SortOrder

Returns the index the page is on, compared to its siblings

@Model.SortOrder

.Url(PublishedUrlProvider, culture = null, UrlMode mode = UrlMode.Default) - (Extension method)

Returns the Url to the page.

@Model.Url(PublishedUrlProvider)

Example: Getting a Danish Url for a site where a Danish language has been set up.

@Model.Url(PublishedUrlProvider, "dk")

Example: Getting an Absolute Danish Url for a site where a Danish language has been set up.

@Model.Url(PublishedUrlProvider, "dk", UrlMode.Absolute)

.UrlSegment

Returns the Url encoded name of the page (slug) of the current culture

@Model.UrlSegment

.UrlSegment(IVariationContextAccessor, string culture = null)

Returns the Url encoded name of the page (slug) of the specified culture

@Model.UrlSegment(VariationContextAccessor)

.WriterId

Returns the id of the Umbraco backoffice user that performed the last update operation on the content item.

@Model.WriterId

.WriterName(IUserService)

Returns the name of the Umbraco backoffice user that initially created the content item.

@Model.WriterName(UserService)

.CreatorId

Returns the id of the Umbraco backoffice user that initially created the content item

@Model.CreatorId

.CreatorName(IUserService)

Returns the name of the Umbraco backoffice user that initially created the content item.

@Model.CreatorName(UserService)

.CreateDate

Returns the DateTime the page was created

@Model.CreateDate
@* gets the Creation date, and formats it to a short date *@
@Model.CreateDate.ToString("D")

.UpdateDate

Returns the DateTime the page was modified

@Model.UpdateDate
@* gets the Update/Modified date, and formats it to a short date *@
@Model.UpdateDate.ToString("D")

Custom properties

All content and media items contain a reference to all the data defined by their Document Type. Custom property access is achieved using variations of the method: Value

Model.Value(IPublishedValueFallback, string)

Returns the property value for the specified property alias

@*Get the property with alias: "siteName" from the current page  *@
@Model.Value(PublishedValueFallback, "siteName")

The type returned of this property value is object. This is fine in most cases since when using the above syntax, Razor will automatically execute a ToString() on the result value.

See Model.Value<T>(string) for how to return a strongly typed object for the property

Model.Value<T>(string)

Returns the property value for the specified property alias converted to 'T' - the requested output type of the property value.

For example, to return the string result of "siteName":

@(Model.Value<string>(PublishedValueFallback, "siteName"))

var mediaItems = Model.Value<IEnumerable<IPublishedContent>>(PublishedValueFallback, "mediaIds");

Fallbacks

If the current content item doesn't have the requested value, use an alternative 'fallback' value in its place.

Each of the examples below make use of an injected PublishedValueFallback. This is achieved by adding the following at the top of your Razor file:

@inject IPublishedValueFallback PublishedValueFallback

This parameter is optional, but can make unit testing easier.

Fallback to Default Value

@(Model.Value<string>(PublishedValueFallback, "title", fallback: Fallback.ToDefaultValue, defaultValue: Model.Name));

or to a specific value

@(Model.Value<string>(PublishedValueFallback, "author", fallback: Fallback.ToDefaultValue, defaultValue: "Team Reporter"));

Fallback to Ancestors

@(Model.Value(PublishedValueFallback, "propertyAlias", fallback: Fallback.ToAncestors))

Fallback to Language

If working with variants - fallback to a different language value - if perhaps the value hasn't been populated yet for the current language:

@(Model.Value(PublishedValueFallback, "pageTitle", "fr", fallback: Fallback.ToLanguage))

Combining the Fallback options

Use Fallback.To() to 'combine' Fallback options.

The following would first look for a 'title' property on all ancestors, before defaulting to the current page's name:

@Model.Value(PublishedValueFallback, "title", fallback: Fallback.To(Fallback.Ancestors, Fallback.DefaultValue), defaultValue: Model.Name)

Property Methods

There are a few helpful methods to help check if a property exists, has a value or is null.

.HasProperty(string propertyAlias)

Returns a boolean value representing if the IPublishedContent has a property with the specified alias.

.HasValue(string propertyAlias)

Returns a boolean value representing if the IPublishedContent property has had a value set.

It's possible to use 'Fallbacks' with HasValue:

bool hasPageTitleSetSomewhere = Model.HasValue(PublishedValueFallback, "pageTitle", fallback: Fallback.ToAncestors);

UmbracoHelper

Using the Umbraco Helper

UmbracoHelper is the unified way to work with published content/media on your website. You can use the UmbracoHelper to query/traverse Umbraco published data.

UmbracoHelper also has a variety of helper methods that are useful when working in your views and controllers.

How to reference UmbracoHelper

If you are using Views or Partial View Macros you can reference UmbracoHelper with the syntax: @Umbraco

If you need an UmbracoHelper in your own controllers, you need to inject an instance.

Example of getting UmbracoHelper in a controller:

UmbracoHelper is registered with a scoped lifetime (see for more information), as a service scope is created for each request you can resolve an instance directly in a controller.

If you need to use an UmbracoHelper in a service with a singleton lifetime you would instead need to make use of the IUmbracoHelperAccessor interface to obtain a temporary reference to an instance.

IPublishedContent

UmbracoHelper will expose all content in the form of IPublishedContent. To get a reference to the currently executing content item from the UmbracoHelper, use UmbracoHelper.AssignedContentItem.

Working with Content

.Content(Guid id)

Given a node ID, returns a IPublishedContent

@{
	var pageFromGui = Umbraco.Content(Guid.Parse("af22cb83-9bd4-454b-ab06-cc19ac8e983d"));
}

<h3>@pageFromGui.Value("propertyAlias")</h3>

@foreach (var child in pageFromGui.Children)
{
	<a href="@child.Url()">@child.Name</a>
}

.ContentAtRoot()

Returns a collection of IPublishedContent objects from the Content tree.

@* Get the children of the first content item found in the root *@
@foreach (var child in Umbraco.ContentAtRoot().First().Children)
{
	<a href="@child.Url()">@child.Name</a>
}

.ContentAtXPath(string xpath)

Queries the cache for content matching a given XPath query and returns a collection of IPublishedContent objects.

@{
    var newsArticles = Umbraco.ContentAtXPath("//newsArticle");
    var bodyText = newsArticles.First().Value("bodyText");
}

.ContentSingleAtXPath(string xpath)

Queries the cache for content matching a given XPath query and returns the first match as an IPublishedContent object.

@{
    var newsArticle = Umbraco.ContentSingleAtXPath("//newsArticle");
    var bodyText = newsArticle.Value("bodyText");
}

Working with Media

.Media(Guid id)

Given a node ID, returns an IPublishedContent Media entity

@{
    var media = Umbraco.Media(Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1"));
    var image = media.Url();
    var height = media.Value<int>("umbracoHeight");
}

.MediaAtRoot()

Returns a collection of IPublishedContent objects from the Media tree.

@foreach (var child in Umbraco.MediaAtRoot())
{
	<img src="@child.Url()"/>
}

Working with Tags

Previously the UmbracoHelper could be used to work with tags, this has been moved out of UmbracoHelper and is now available from ITagQuery which you can read more about in the .

Working with Members

Previously the UmbracoHelper could be used to work with members, this has ben moved out of UmbracoHelper and is now available from IMemberManager, see for more information

Searching

Previously the UmbracoHelper could be used to run queries on your content, this has been moved out of UmbracoHelper and is now available from IPublishedContentQuery, see for more information.

Fetching Dictionary Values

.GetDictionaryValue(string key)

Returns a dictionary value(string) for the key specified.

<p>@Umbraco.GetDictionaryValue("createdOn"): @Model.CreateDate</p>

Alternatively, you can also specify an altText which will be returned if the dictionary value is empty.

<p>@Umbraco.GetDictionaryValue("createdOn", "Date Created"): @Model.CreateDate</p>

Templating Helpers

.RenderMacro(string alias, object parameters)

Renders a macro in the current page content, given the macro's alias, and parameters required by the macro.

@await Umbraco.RenderMacroAsync("navigation", new {root="1083", header="Hello"})

.RenderTemplateAsync(int contentId, int? altTemplateId)

Renders a template asynchronously, as if a page with the given contentId was requested, optionally with an alternative template ID passed in.

@await Umbraco.RenderTemplate(1234)

Querying & Models

IMemberManager

How to reference IMemberManager

Views

Dependency Injection

Examples

Finding members

FindByIdAsync(string)

FindByEmailAsync(string)

FindByNameAsync(string)

AsPublishedMember(MemberIdentityUser)

GetCurrentMemberAsync()

GetUserIdAsync()

IsLoggedIn()

IsMemberAuthorizedAsync(IEnumerable memberTypes, IEnumerable memberGroups, IEnumerable memberIds)

IsProtectedAsync()

MemberHasAccessAsync(string)

ValidateCredentialsAsync(string username, string password)

IPublishedContentQuery

How to inject IPublishedContentQuery

Examples

.Search(string term)

.Search(string term, int skip, int take, out long totalRecords)

.Search(IQueryExecutor queryExecutor)

ITagQuery

How to reference ITagQuery

Examples

GetAllContentTags([string tagGroup])

GetAllMediaTags([string tagGroup])

GetAllMemberTags([string tagGroup])

GetAllTags([string tagGroup])

GetContentByTag(string tag, [string tagGroup])

GetContentByTagGroup(string tagGroup)

GetMediaByTag(string tag, [string tagGroup])

GetMediaByTagGroup(string tag, [string tagGroup])

GetTagsForEntity(int contentId, [string tagGroup])

GetTagsForProperty(int contentId, string propertyTypeAlias, [string tagGroup])

UDI Identifiers

Introduction

Format

Usage

GUID UDI

String UDI

UmbracoContext helper

How to reference UmbracoContext

UmbracoHelper

How to reference UmbracoHelper

IPublishedContent

Working with Content

.Content(Guid id)

.ContentAtRoot()

.ContentAtXPath(string xpath)

.ContentSingleAtXPath(string xpath)

Working with Media

.Media(Guid id)

.MediaAtRoot()

Working with Tags

Working with Members

Searching

Fetching Dictionary Values

.GetDictionaryValue(string key)

Templating Helpers

.RenderMacro(string alias, object parameters)

.RenderTemplateAsync(int contentId, int? altTemplateId)

IPublishedContent

Get started

IPublishedContent Collections

Collections

.Children

.ChildrenForAllCultures

.Children(string culture = null)

.Ancestors()

.Ancestor()

.AncestorsOrSelf()

.Descendants()

.DescendantsOrSelf()

.OfTypes

Filtering, Ordering & Extensions

.Where

.OrderBy