Class EntityController

Namespace

Umbraco.Cms.Web.BackOffice.Controllers

Assembly

Umbraco.Web.BackOffice.dll

The API controller used for getting entity objects, basic name, icon, id representation of umbraco objects that are based on CMSNode

public class EntityController : UmbracoAuthorizedJsonController

Inheritance

object

UmbracoAuthorizedApiController

UmbracoAuthorizedJsonController

EntityController

Inherited Members

UmbracoAuthorizedApiController.ValidationProblem(IErrorModel, ModelStateDictionary, int)

UmbracoAuthorizedApiController.ValidationProblem(ModelStateDictionary)

UmbracoAuthorizedApiController.GetValidationProblemDetails(string, string, int?, string, string, ModelStateDictionary)

UmbracoAuthorizedApiController.ValidationProblem(string)

UmbracoAuthorizedApiController.ValidationProblem(object, int)

UmbracoAuthorizedApiController.ValidationProblem(INotificationModel, int)

Remarks

This controller allows resolving basic entity data for various entities without placing the hard restrictions on users that may not have access to the sections these entities entities exist in. This is to allow pickers, etc... of data to work for all users. In some cases such as accessing Members, more explicit security checks are done.

Some objects such as macros are not based on CMSNode

Constructors

EntityController(ITreeService, UmbracoTreeSearcher, SearchableTreeCollection, IPublishedContentQuery, IShortStringHelper, IEntityService, IBackOfficeSecurityAccessor, IPublishedUrlProvider, IContentService, IUmbracoMapper, IDataTypeService, ISqlContext, ILocalizedTextService, IFileService, IContentTypeService, IMediaTypeService, IMacroService, IUserService, ILocalizationService, AppCaches)

[Obsolete("Use non-obsolete ctor. This will be removed in Umbraco 14.")]
public EntityController(ITreeService treeService, UmbracoTreeSearcher treeSearcher, SearchableTreeCollection searchableTreeCollection, IPublishedContentQuery publishedContentQuery, IShortStringHelper shortStringHelper, IEntityService entityService, IBackOfficeSecurityAccessor backofficeSecurityAccessor, IPublishedUrlProvider publishedUrlProvider, IContentService contentService, IUmbracoMapper umbracoMapper, IDataTypeService dataTypeService, ISqlContext sqlContext, ILocalizedTextService localizedTextService, IFileService fileService, IContentTypeService contentTypeService, IMediaTypeService mediaTypeService, IMacroService macroService, IUserService userService, ILocalizationService localizationService, AppCaches appCaches)

Parameters

treeService ITreeService

treeSearcher UmbracoTreeSearcher

searchableTreeCollection SearchableTreeCollection

publishedContentQuery IPublishedContentQuery

shortStringHelper IShortStringHelper

entityService IEntityService

backofficeSecurityAccessor IBackOfficeSecurityAccessor

publishedUrlProvider IPublishedUrlProvider

contentService IContentService

umbracoMapper IUmbracoMapper

dataTypeService IDataTypeService

sqlContext ISqlContext

localizedTextService ILocalizedTextService

fileService IFileService

contentTypeService IContentTypeService

mediaTypeService IMediaTypeService

macroService IMacroService

userService IUserService

localizationService ILocalizationService

appCaches AppCaches

EntityController(ITreeService, UmbracoTreeSearcher, SearchableTreeCollection, IPublishedContentQuery, IShortStringHelper, IEntityService, IBackOfficeSecurityAccessor, IPublishedUrlProvider, IContentService, IUmbracoMapper, IDataTypeService, ISqlContext, ILocalizedTextService, IFileService, IContentTypeService, IMediaTypeService, IMacroService, IUserService, ILocalizationService, AppCaches, IDynamicRootService, IVariationContextAccessor)

[ActivatorUtilitiesConstructor]
public EntityController(ITreeService treeService, UmbracoTreeSearcher treeSearcher, SearchableTreeCollection searchableTreeCollection, IPublishedContentQuery publishedContentQuery, IShortStringHelper shortStringHelper, IEntityService entityService, IBackOfficeSecurityAccessor backofficeSecurityAccessor, IPublishedUrlProvider publishedUrlProvider, IContentService contentService, IUmbracoMapper umbracoMapper, IDataTypeService dataTypeService, ISqlContext sqlContext, ILocalizedTextService localizedTextService, IFileService fileService, IContentTypeService contentTypeService, IMediaTypeService mediaTypeService, IMacroService macroService, IUserService userService, ILocalizationService localizationService, AppCaches appCaches, IDynamicRootService dynamicRootService, IVariationContextAccessor variationContextAccessor)

Parameters

treeService ITreeService

treeSearcher UmbracoTreeSearcher

searchableTreeCollection SearchableTreeCollection

publishedContentQuery IPublishedContentQuery

shortStringHelper IShortStringHelper

entityService IEntityService

backofficeSecurityAccessor IBackOfficeSecurityAccessor

publishedUrlProvider IPublishedUrlProvider

contentService IContentService

umbracoMapper IUmbracoMapper

dataTypeService IDataTypeService

sqlContext ISqlContext

localizedTextService ILocalizedTextService

fileService IFileService

contentTypeService IContentTypeService

mediaTypeService IMediaTypeService

macroService IMacroService

userService IUserService

localizationService ILocalizationService

appCaches AppCaches

dynamicRootService IDynamicRootService

variationContextAccessor IVariationContextAccessor

Methods

GetAll(UmbracoEntityTypes, string)

public IEnumerable<EntityBasic>? GetAll(UmbracoEntityTypes type, string postFilter)

Parameters

type UmbracoEntityTypes

The type of entity.

postFilter string

Optional filter - Format like: "BoolVariable==true&IntVariable>=6". Invalid filters are ignored.

Returns

IEnumerable<EntityBasic>

GetAncestors(Guid, UmbracoEntityTypes, FormCollection)

public ActionResult<IEnumerable<EntityBasic>> GetAncestors(Guid id, UmbracoEntityTypes type, FormCollection queryStrings)

Parameters

id Guid

type UmbracoEntityTypes

queryStrings FormCollection

Returns

ActionResult<IEnumerable<EntityBasic>>

GetAncestors(int, UmbracoEntityTypes, FormCollection)

public IEnumerable<EntityBasic> GetAncestors(int id, UmbracoEntityTypes type, FormCollection queryStrings)

Parameters

id int

type UmbracoEntityTypes

queryStrings FormCollection

Returns

IEnumerable<EntityBasic>

GetAnchors(AnchorsModel)

[HttpGet]
[HttpPost]
public IEnumerable<string> GetAnchors(AnchorsModel model)

Parameters

model AnchorsModel

Returns

IEnumerable<string>

GetById(Guid, UmbracoEntityTypes)

Gets an entity by it's key

public ActionResult<EntityBasic?> GetById(Guid id, UmbracoEntityTypes type)

Parameters

id Guid

type UmbracoEntityTypes

Returns

ActionResult<EntityBasic>

GetById(int, UmbracoEntityTypes)

Gets an entity by it's id

public ActionResult<EntityBasic?> GetById(int id, UmbracoEntityTypes type)

Parameters

id int

type UmbracoEntityTypes

Returns

ActionResult<EntityBasic>

GetById(Udi, UmbracoEntityTypes)

Gets an entity by it's UDI

public ActionResult<EntityBasic?> GetById(Udi id, UmbracoEntityTypes type)

Parameters

id Udi

type UmbracoEntityTypes

Returns

ActionResult<EntityBasic>

GetByIds(Guid[], UmbracoEntityTypes)

Get entities by GUID ids

[HttpGet]
[HttpPost]
public ActionResult<IEnumerable<EntityBasic>> GetByIds(Guid[] ids, UmbracoEntityTypes type)

Parameters

ids Guid[]

type UmbracoEntityTypes

Returns

ActionResult<IEnumerable<EntityBasic>>

Remarks

We allow for POST because there could be quite a lot of Ids

GetByIds(int[], UmbracoEntityTypes)

Get entities by integer ids

[HttpGet]
[HttpPost]
public ActionResult<IEnumerable<EntityBasic>> GetByIds(int[] ids, UmbracoEntityTypes type)

Parameters

ids int[]

type UmbracoEntityTypes

Returns

ActionResult<IEnumerable<EntityBasic>>

Remarks

We allow for POST because there could be quite a lot of Ids

GetByIds(Udi[], UmbracoEntityTypes)

Get entities by UDIs

[HttpGet]
[HttpPost]
public ActionResult<IEnumerable<EntityBasic>> GetByIds(Udi[] ids, UmbracoEntityTypes type)

Parameters

ids Udi[]

A list of UDIs to lookup items by, all UDIs must be of the same UDI type!

type UmbracoEntityTypes

Returns

ActionResult<IEnumerable<EntityBasic>>

Remarks

We allow for POST because there could be quite a lot of Ids.

GetByQuery(string, int, UmbracoEntityTypes)

Gets an entity by a xpath query - OBSOLETE

[Obsolete("This will be removed in Umbraco 13. Use GetByXPath instead")]
public ActionResult<EntityBasic?>? GetByQuery(string query, int nodeContextId, UmbracoEntityTypes type)

Parameters

query string

nodeContextId int

type UmbracoEntityTypes

Returns

ActionResult<EntityBasic>

GetByXPath(string, int, int?, UmbracoEntityTypes)

Gets an entity by a xpath query

[Obsolete("The current implementation of this method is suboptimal and will be removed entirely in a future version. Scheduled for removal in v14")]
public ActionResult<EntityBasic?>? GetByXPath(string query, int nodeContextId, int? parentId, UmbracoEntityTypes type)

Parameters

query string

nodeContextId int

parentId int?

type UmbracoEntityTypes

Returns

ActionResult<EntityBasic>

GetChildren(int, UmbracoEntityTypes, Guid?)

public IEnumerable<EntityBasic> GetChildren(int id, UmbracoEntityTypes type, Guid? dataTypeKey = null)

Parameters

id int

type UmbracoEntityTypes

dataTypeKey Guid?

Returns

IEnumerable<EntityBasic>

GetDynamicRootAsync(DynamicRootViewModel)

[HttpPost]
public Task<ActionResult<EntityBasic?>> GetDynamicRootAsync(EntityController.DynamicRootViewModel model)

Parameters

model EntityController.DynamicRootViewModel

Returns

Task<ActionResult<EntityBasic>>

GetPagedChildren(int, UmbracoEntityTypes, int, int, string, Direction, string, Guid?)

Get paged child entities by id

public ActionResult<PagedResult<EntityBasic>> GetPagedChildren(int id, UmbracoEntityTypes type, int pageNumber, int pageSize, string orderBy = "SortOrder", Direction orderDirection = 0, string filter = "", Guid? dataTypeKey = null)

Parameters

id int

type UmbracoEntityTypes

pageNumber int

pageSize int

orderBy string

orderDirection Direction

filter string

dataTypeKey Guid?

Returns

ActionResult<PagedResult<EntityBasic>>

GetPagedChildren(string, UmbracoEntityTypes, int, int, string, Direction, string, Guid?)

Get paged child entities by id

public ActionResult<PagedResult<EntityBasic>> GetPagedChildren(string id, UmbracoEntityTypes type, int pageNumber, int pageSize, string orderBy = "SortOrder", Direction orderDirection = 0, string filter = "", Guid? dataTypeKey = null)

Parameters

id string

type UmbracoEntityTypes

pageNumber int

pageSize int

orderBy string

orderDirection Direction

filter string

dataTypeKey Guid?

Returns

ActionResult<PagedResult<EntityBasic>>

GetPagedDescendants(int, UmbracoEntityTypes, int, int, string, Direction, string, Guid?)

public ActionResult<PagedResult<EntityBasic>> GetPagedDescendants(int id, UmbracoEntityTypes type, int pageNumber, int pageSize, string orderBy = "SortOrder", Direction orderDirection = 0, string filter = "", Guid? dataTypeKey = null)

Parameters

id int

type UmbracoEntityTypes

pageNumber int

pageSize int

orderBy string

orderDirection Direction

filter string

dataTypeKey Guid?

Returns

ActionResult<PagedResult<EntityBasic>>

GetPath(Guid, UmbracoEntityTypes)

Gets the path for a given node ID

public IConvertToActionResult GetPath(Guid id, UmbracoEntityTypes type)

Parameters

id Guid

type UmbracoEntityTypes

Returns

IConvertToActionResult

GetPath(int, UmbracoEntityTypes)

Gets the path for a given node ID

public IConvertToActionResult GetPath(int id, UmbracoEntityTypes type)

Parameters

id int

type UmbracoEntityTypes

Returns

IConvertToActionResult

GetPath(Udi, UmbracoEntityTypes)

Gets the path for a given node ID

public IActionResult GetPath(Udi id, UmbracoEntityTypes type)

Parameters

id Udi

type UmbracoEntityTypes

Returns

IActionResult

GetSafeAlias(string, bool)

Returns an Umbraco alias given a string

public dynamic GetSafeAlias(string value, bool camelCase = true)

Parameters

value string

camelCase bool

Returns

dynamic

GetUrl(int, UmbracoEntityTypes, string?)

Gets the URL of an entity

public IActionResult GetUrl(int id, UmbracoEntityTypes type, string? culture = null)

Parameters

id int

Int id of the entity to fetch URL for

type UmbracoEntityTypes

The type of entity such as Document, Media, Member

culture string

The culture to fetch the URL for

Returns

IActionResult

The URL or path to the item

Remarks

We are not restricting this with security because there is no sensitive data

GetUrl(Udi, string)

Gets the URL of an entity

public IActionResult GetUrl(Udi id, string culture = "*")

Parameters

id Udi

UDI of the entity to fetch URL for

culture string

The culture to fetch the URL for

Returns

IActionResult

The URL or path to the item

GetUrlAndAnchors(int, string?)

[HttpGet]
public UrlAndAnchors GetUrlAndAnchors(int id, string? culture = "*")

Parameters

id int

culture string

Returns

UrlAndAnchors

GetUrlAndAnchors(Udi, string)

[HttpGet]
public ActionResult<UrlAndAnchors> GetUrlAndAnchors(Udi id, string culture = "*")

Parameters

id Udi

culture string

Returns

ActionResult<UrlAndAnchors>

GetUrlsByIds(Guid[], UmbracoEntityTypes, string?)

Get entity URLs by IDs

[HttpGet]
[HttpPost]
public IDictionary<Guid, string?> GetUrlsByIds(Guid[] ids, UmbracoEntityTypes type, string? culture = null)

Parameters

ids Guid[]

A list of IDs to lookup items by

type UmbracoEntityTypes

The entity type to look for.

culture string

The culture to fetch the URL for.

Returns

IDictionary<Guid, string>

Dictionary mapping Udi -> Url

Remarks

We allow for POST because there could be quite a lot of Ids.

GetUrlsByIds(int[], UmbracoEntityTypes, string?)

Get entity URLs by IDs

[HttpGet]
[HttpPost]
public IDictionary<int, string?> GetUrlsByIds(int[] ids, UmbracoEntityTypes type, string? culture = null)

Parameters

ids int[]

A list of IDs to lookup items by

type UmbracoEntityTypes

The entity type to look for.

culture string

The culture to fetch the URL for.

Returns

IDictionary<int, string>

Dictionary mapping Udi -> Url

Remarks

We allow for POST because there could be quite a lot of Ids.

GetUrlsByIds(Udi[], UmbracoEntityTypes, string?)

Get entity URLs by IDs

[HttpGet]
[HttpPost]
public IDictionary<Udi, string?> GetUrlsByIds(Udi[] ids, UmbracoEntityTypes type, string? culture = null)

Parameters

ids Udi[]

A list of IDs to lookup items by

type UmbracoEntityTypes

The entity type to look for.

culture string

The culture to fetch the URL for.

Returns

IDictionary<Udi, string>

Dictionary mapping Udi -> Url

Remarks

We allow for POST because there could be quite a lot of Ids.

Search(string, UmbracoEntityTypes, string?, Guid?)

Searches for results based on the entity type

[HttpGet]
public IEnumerable<EntityBasic> Search(string query, UmbracoEntityTypes type, string? searchFrom = null, Guid? dataTypeKey = null)

Parameters

query string

type UmbracoEntityTypes

searchFrom string

A starting point for the search, generally a node id, but for members this is a member type alias

dataTypeKey Guid?

If set used to look up whether user and group start node permissions will be ignored.

Returns

IEnumerable<EntityBasic>

SearchAll(string)

Searches for all content that the user is allowed to see (based on their allowed sections)

[HttpGet]
public Task<IDictionary<string, TreeSearchResult>> SearchAll(string query)

Parameters

query string

Returns

Task<IDictionary<string, TreeSearchResult>>

Remarks

Even though a normal entity search will allow any user to search on a entity type that they may not have access to edit, we need to filter these results to the sections they are allowed to edit since this search function is explicitly for the global search so if we showed entities that they weren't allowed to edit they would get errors when clicking on the result. The reason a user is allowed to search individual entity types that they are not allowed to edit is because those search methods might be used in things like pickers in the content editor.