View Source

Class EntityController

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

Inheritance

System.Object

Microsoft.AspNetCore.Mvc.ControllerBase

UmbracoApiControllerBase

UmbracoApiController

UmbracoAuthorizedApiController

UmbracoAuthorizedJsonController

Namespace: Umbraco.Cms.Web.BackOffice.Controllers

Assembly: Umbraco.Web.BackOffice.dll

Syntax

public class EntityController : UmbracoAuthorizedJsonController

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

View Source

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

Declaration

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

Type	Name	Description
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

Methods

View Source

GetAll(UmbracoEntityTypes, String)

Declaration

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

Parameters

Type	Name	Description
UmbracoEntityTypes	type	The type of entity.
System.String	postFilter	Optional filter - Format like: "BoolVariable==true&IntVariable>=6". Invalid filters are ignored.

Returns

Type	Description
System.Nullable<IEnumerable<EntityBasic>>

View Source

GetAncestors(Guid, UmbracoEntityTypes, FormCollection)

Declaration

public ActionResult<IEnumerable<EntityBasic>> GetAncestors(Guid id, UmbracoEntityTypes type, [ModelBinder(typeof(HttpQueryStringModelBinder))] FormCollection queryStrings)

Parameters

Type	Name	Description
Guid	id
UmbracoEntityTypes	type
Microsoft.AspNetCore.Http.FormCollection	queryStrings

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<IEnumerable<EntityBasic>>

View Source

GetAncestors(Int32, UmbracoEntityTypes, FormCollection)

Declaration

public IEnumerable<EntityBasic> GetAncestors(int id, UmbracoEntityTypes type, [ModelBinder(typeof(HttpQueryStringModelBinder))] FormCollection queryStrings)

Parameters

Type	Name	Description
System.Int32	id
UmbracoEntityTypes	type
Microsoft.AspNetCore.Http.FormCollection	queryStrings

Returns

Type	Description
IEnumerable<EntityBasic>

View Source

GetAnchors(AnchorsModel)

Declaration

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

Parameters

Type	Name	Description
AnchorsModel	model

Returns

Type	Description
IEnumerable<System.String>

View Source

GetById(Guid, UmbracoEntityTypes)

Gets an entity by it's key

Declaration

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

Parameters

Type	Name	Description
Guid	id
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<System.Nullable<EntityBasic>>

View Source

GetById(Int32, UmbracoEntityTypes)

Gets an entity by it's id

Declaration

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

Parameters

Type	Name	Description
System.Int32	id
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<System.Nullable<EntityBasic>>

View Source

GetById(Udi, UmbracoEntityTypes)

Gets an entity by it's UDI

Declaration

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

Parameters

Type	Name	Description
Udi	id
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<System.Nullable<EntityBasic>>

View Source

GetByIds(Guid[], UmbracoEntityTypes)

Get entities by GUID ids

Declaration

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

Parameters

Type	Name	Description
Guid[]	ids
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<IEnumerable<EntityBasic>>

Remarks

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

View Source

GetByIds(Int32[], UmbracoEntityTypes)

Get entities by integer ids

Declaration

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

Parameters

Type	Name	Description
System.Int32[]	ids
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<IEnumerable<EntityBasic>>

Remarks

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

View Source

GetByIds(Udi[], UmbracoEntityTypes)

Get entities by UDIs

Declaration

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

Parameters

Type	Name	Description
Udi[]	ids	A list of UDIs to lookup items by, all UDIs must be of the same UDI type!
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<IEnumerable<EntityBasic>>

Remarks

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

View Source

GetByQuery(String, Int32, UmbracoEntityTypes)

Gets an entity by a xpath query - OBSOLETE

Declaration

public ActionResult<EntityBasic?> GetByQuery(string query, int nodeContextId, UmbracoEntityTypes type)

Parameters

Type	Name	Description
System.String	query
System.Int32	nodeContextId
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<System.Nullable<EntityBasic>>

View Source

GetByXPath(String, Int32, Nullable<Int32>, UmbracoEntityTypes)

Gets an entity by a xpath query

Declaration

public ActionResult<EntityBasic?> GetByXPath(string query, int nodeContextId, int? parentId, UmbracoEntityTypes type)

Parameters

Type	Name	Description
System.String	query
System.Int32	nodeContextId
System.Nullable<System.Int32>	parentId
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<System.Nullable<EntityBasic>>

View Source

GetChildren(Int32, UmbracoEntityTypes, Nullable<Guid>)

Declaration

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

Parameters

Type	Name	Description
System.Int32	id
UmbracoEntityTypes	type
System.Nullable<Guid>	dataTypeKey

Returns

Type	Description
IEnumerable<EntityBasic>

View Source

GetPagedChildren(Int32, UmbracoEntityTypes, Int32, Int32, String, Direction, String, Nullable<Guid>)

Get paged child entities by id

Declaration

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

Parameters

Type	Name	Description
System.Int32	id
UmbracoEntityTypes	type
System.Int32	pageNumber
System.Int32	pageSize
System.String	orderBy
Direction	orderDirection
System.String	filter
System.Nullable<Guid>	dataTypeKey

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<PagedResult<EntityBasic>>

View Source

GetPagedChildren(String, UmbracoEntityTypes, Int32, Int32, String, Direction, String, Nullable<Guid>)

Get paged child entities by id

Declaration

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

Parameters

Type	Name	Description
System.String	id
UmbracoEntityTypes	type
System.Int32	pageNumber
System.Int32	pageSize
System.String	orderBy
Direction	orderDirection
System.String	filter
System.Nullable<Guid>	dataTypeKey

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<PagedResult<EntityBasic>>

View Source

GetPagedDescendants(Int32, UmbracoEntityTypes, Int32, Int32, String, Direction, String, Nullable<Guid>)

Declaration

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

Parameters

Type	Name	Description
System.Int32	id
UmbracoEntityTypes	type
System.Int32	pageNumber
System.Int32	pageSize
System.String	orderBy
Direction	orderDirection
System.String	filter
System.Nullable<Guid>	dataTypeKey

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<PagedResult<EntityBasic>>

View Source

GetPath(Guid, UmbracoEntityTypes)

Gets the path for a given node ID

Declaration

public IConvertToActionResult GetPath(Guid id, UmbracoEntityTypes type)

Parameters

Type	Name	Description
Guid	id
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.Infrastructure.IConvertToActionResult

View Source

GetPath(Int32, UmbracoEntityTypes)

Gets the path for a given node ID

Declaration

public IConvertToActionResult GetPath(int id, UmbracoEntityTypes type)

Parameters

Type	Name	Description
System.Int32	id
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.Infrastructure.IConvertToActionResult

View Source

GetPath(Udi, UmbracoEntityTypes)

Gets the path for a given node ID

Declaration

public IActionResult GetPath(Udi id, UmbracoEntityTypes type)

Parameters

Type	Name	Description
Udi	id
UmbracoEntityTypes	type

Returns

Type	Description
Microsoft.AspNetCore.Mvc.IActionResult

View Source

GetSafeAlias(String, Boolean)

Returns an Umbraco alias given a string

Declaration

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

Parameters

Type	Name	Description
System.String	value
System.Boolean	camelCase

Returns

Type	Description
System.Object

View Source

GetUrl(Int32, UmbracoEntityTypes, String)

Gets the URL of an entity

Declaration

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

Parameters

Type	Name	Description
System.Int32	id	Int id of the entity to fetch URL for
UmbracoEntityTypes	type	The type of entity such as Document, Media, Member
System.String	culture	The culture to fetch the URL for

Returns

Type	Description
Microsoft.AspNetCore.Mvc.IActionResult	The URL or path to the item

Remarks

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

View Source

GetUrl(Udi, String)

Gets the URL of an entity

Declaration

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

Parameters

Type	Name	Description
Udi	id	UDI of the entity to fetch URL for
System.String	culture	The culture to fetch the URL for

Returns

Type	Description
Microsoft.AspNetCore.Mvc.IActionResult	The URL or path to the item

View Source

GetUrlAndAnchors(Int32, String)

Declaration

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

Parameters

Type	Name	Description
System.Int32	id
System.String	culture

Returns

Type	Description
UrlAndAnchors

View Source

GetUrlAndAnchors(Udi, String)

Declaration

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

Parameters

Type	Name	Description
Udi	id
System.String	culture

Returns

Type	Description
Microsoft.AspNetCore.Mvc.ActionResult<UrlAndAnchors>

View Source

GetUrlsByIds(Guid[], UmbracoEntityTypes, String)

Get entity URLs by IDs

Declaration

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

Parameters

Type	Name	Description
Guid[]	ids	A list of IDs to lookup items by
UmbracoEntityTypes	type	The entity type to look for.
System.String	culture	The culture to fetch the URL for.

Returns

Type	Description
IDictionary<Guid, System.String>	Dictionary mapping Udi -> Url

Remarks

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

View Source

GetUrlsByIds(Int32[], UmbracoEntityTypes, String)

Get entity URLs by IDs

Declaration

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

Parameters

Type	Name	Description
System.Int32[]	ids	A list of IDs to lookup items by
UmbracoEntityTypes	type	The entity type to look for.
System.String	culture	The culture to fetch the URL for.

Returns

Type	Description
IDictionary<System.Int32, System.String>	Dictionary mapping Udi -> Url

Remarks

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

View Source

GetUrlsByIds(Udi[], UmbracoEntityTypes, String)

Get entity URLs by IDs

Declaration

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

Parameters

Type	Name	Description
Udi[]	ids	A list of IDs to lookup items by
UmbracoEntityTypes	type	The entity type to look for.
System.String	culture	The culture to fetch the URL for.

Returns

Type	Description
IDictionary<Udi, System.String>	Dictionary mapping Udi -> Url

Remarks

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

View Source

Search(String, UmbracoEntityTypes, String, Nullable<Guid>)

Searches for results based on the entity type

Declaration

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

Parameters

Type	Name	Description
System.String	query
UmbracoEntityTypes	type
System.String	searchFrom	A starting point for the search, generally a node id, but for members this is a member type alias
System.Nullable<Guid>	dataTypeKey	If set used to look up whether user and group start node permissions will be ignored.

Returns

Type	Description
IEnumerable<EntityBasic>

View Source

SearchAll(String)

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

Declaration

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

Parameters

Type	Name	Description
System.String	query

Returns

Type	Description
Task<IDictionary<System.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.