Class Api12

This is the base class for all custom API Controllers.
With this, your code receives the full context incl. the current App, DNN, Data, etc.

Inheritance

object

ApiController

DnnApiController

DnnApiControllerWithFixes

SxcApiControllerBase

DynamicApiController

Api12

Api12

Implements

IDynamicCode12

IDynamicCode

IHasLog

IDynamicWebApi

IHasCodeLog

Namespace: Custom.Hybrid

Assembly: ToSic.Sxc.Dnn.WebApi.dll

Syntax

[PublicApi("This is the official base class for v12+")]
public abstract class Api12 : DynamicApiController, IDynamicCode12, IDynamicCode, IHasLog, IDynamicWebApi, IHasCodeLog

Constructors

Api12()

Declaration

protected Api12()

Api12(string)

Declaration

protected Api12(string logSuffix)

Parameters

Type	Name	Description
string	logSuffix

Properties

App

A fully prepared IApp object letting you access all the data and queries in the current app.

Declaration

public IApp App { get; }

Property Value

Type	Description
IApp	The current app

CmsContext

This Context tells you about the environment, such as

• the current User
• the Page
• the View
• the Site

It's supposed to replace direct access to Dnn or Oqtane object in Razor and WebAPI code, allowing hybrid code that works everywhere.

Declaration

public ICmsContext CmsContext { get; }

Property Value

Type	Description
ICmsContext

Remarks

New in v11.11

Content

The content object of the current razor view - IF the current view has content. If the view is a list, it will return the first item. Will be null otherwise. To tell if it's the demo/default item, use IsDemoItem.

Declaration

public dynamic Content { get; }

Property Value

Type	Description
dynamic	A IDynamicEntity object with the current content - or null.

Convert

Conversion helper for common data conversions in Razor and WebAPIs

Declaration

public IConvertService Convert { get; }

Property Value

Type	Description
IConvertService

Remarks

Added in 2sxc 12.05

Data

The data prepared for the current Code. Usually user data which was manually added to the instance, but can also be a query.

Declaration

public IContextData Data { get; }

Property Value

Type	Description
IContextData	An IContextData which is as IDataSource.

Edit

Helper commands to enable in-page editing functionality Use it to check if edit is enabled, generate context-json infos and provide toolbar buttons

Declaration

public IEditService Edit { get; }

Property Value

Type	Description
IEditService	An IEditService object.

Header

The header object of the current razor view, if it's a list and has a header object. If it's a list and doesn't have a header (and no default), it will return null. To tell if it's the demo/default item, use IsDemoItem.

Declaration

public dynamic Header { get; }

Property Value

Type	Description
dynamic	A IDynamicEntity object with the current content.

Remarks

Introduced in 2sxc 10.10 - previously it was called ListContent, now deprecated.

Link

Link helper object to create the correct links

Declaration

public ILinkService Link { get; }

Property Value

Type	Description
ILinkService	A ILinkService object.

Log

The logger for the current Razor / WebApi which allows you to add logs to Insights.

Declaration

public ICodeLog Log { get; }

Property Value

Type	Description
ICodeLog

Resources

Resources for this Scenario. This is a dynamic object based on the IDynamicStack.

It will combine both the Resources of the View and the App. The View-Resources will have priority. In future it may also include some global Resources.

🪒 Use in Razor: @Resources.CtaButtonLabel

Declaration

public dynamic Resources { get; }

Property Value

Type	Description
dynamic

Remarks

New in 12.03

Settings

Settings for this Scenario. This is a dynamic object based on the IDynamicStack.

It will combine both the Settings of the View and the App. The View-Settings will have priority. In future it may also include some global Settings.

🪒 Use in Razor: @Settings.ItemsPerRow

Declaration

public dynamic Settings { get; }

Property Value

Type	Description
dynamic

Remarks

New in 12.03

Methods

Accepted()

Creates a .net-core like AcceptedResult object that produces an .net-core like StatusCodes.Status202Accepted response.

Typical use: return Accepted();

Declaration

[NonAction]
public dynamic Accepted()

Returns

Type	Description
dynamic	The created .net-core like AcceptedResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

AsAdam(ICanBeEntity, string)

Provides an Adam instance for this item and field

Declaration

public IFolder AsAdam(ICanBeEntity item, string fieldName)

Parameters

Type	Name	Description
ICanBeEntity	item	The item - an IEntity, IDynamicEntity, ITypedItem etc. often Content or similar
string	fieldName	The field name, like "Gallery" or "Pics"

Returns

Type	Description
IFolder	An Adam object for navigating the assets

AsDynamic(object)

Convert a dynamic entity and return itself again. This is so coders don't have to worry if the original object was an IEntity or a IDynamicEntity in the first place.

Declaration

public dynamic AsDynamic(object dynamicEntity)

Parameters

Type	Name	Description
object	dynamicEntity	the original object

Returns

Type	Description
dynamic	a dynamic object for easier coding

AsDynamic(params object[])

Convert one or many Entities and Dynamic entities into an IDynamicStack

Declaration

public dynamic AsDynamic(params object[] entities)

Parameters

Type	Name	Description
object[]	entities	one or more source object

Returns

Type	Description
dynamic	a dynamic object for easier coding

Remarks

New in 12.05

AsDynamic(string, string)

Take a json and provide it as a dynamic object to the code

Declaration

public dynamic AsDynamic(string json, string fallback = null)

Parameters

Type	Name	Description
string	json	the original json string
string	fallback	Alternate string to use, if the original json can't parse. Can also be null or the word "error" if you would prefer an error to be thrown.

Returns

Type	Description
dynamic	A dynamic object representing the original json. If it can't be parsed, it will parse the fallback, which by default is an empty empty dynamic object. If you provide null for the fallback, then you will get null back.

Remarks

Added in 2sxc 10.22.00

AsDynamic(IEntity)

Wraps an entity into a IDynamicEntity

Declaration

public dynamic AsDynamic(IEntity entity)

Parameters

Type	Name	Description
IEntity	entity	the original object

Returns

Type	Description
dynamic	a dynamic object for easier coding

AsEntity(object)

Unwraps a dynamic entity or ITypedItem back into the underlying IEntity

Declaration

public IEntity AsEntity(object dynamicEntity)

Parameters

Type	Name	Description
object	dynamicEntity	the wrapped IEntity

Returns

Type	Description
IEntity	A normal IEntity

AsList(object)

Converts a list of IEntity objects into a list of IDynamicEntity objects.

Declaration

public IEnumerable<dynamic> AsList(object list)

Parameters

Type	Name	Description
object	list	typically a List/IEnumerable of Entities or DynamicEntities. Can also be a IDataSource in which case it uses the default stream.

Returns

Type	Description
IEnumerable<dynamic>	a list of IDynamicEntity objects

Remarks

Added in 2sxc 10.21.00

BadRequest()

Creates an .net-core like BadRequestResult that produces a .net-core like StatusCodes.Status400BadRequest response.

Typical use: return BadRequest();

Declaration

[NonAction]
public dynamic BadRequest()

Returns

Type	Description
dynamic	The created .net-core like BadRequestResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Conflict()

Creates an .net-core like ConflictResult that produces a .net-core like StatusCodes.Status409Conflict response.

Typical use: return Conflict();

Declaration

[NonAction]
public dynamic Conflict()

Returns

Type	Description
dynamic	The created .net-core like ConflictResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Conflict(object)

Creates an .net-core like ConflictObjectResult that produces a .net-core like StatusCodes.Status409Conflict response.

Typical use: return Conflict("the stored file is newer");

Declaration

[NonAction]
public dynamic Conflict(object error)

Parameters

Type	Name	Description
object	error	Contains errors to be returned to the client.

Returns

Type	Description
dynamic	The created .net-core like ConflictObjectResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

CreateInstance(string, string, string, string, bool)

Create an instance of code lying in a file near this

Declaration

public dynamic CreateInstance(string virtualPath, string noParamOrder = "Params must be named (https://go.2sxc.org/named-params)", string name = null, string relativePath = null, bool throwOnError = true)

Parameters

Type	Name	Description
string	virtualPath	path to the other code file to compile
string	noParamOrder	see Convention: Named Parameters
string	name	Override the class name to compile - usually not required as it should match the file name
string	relativePath	optional relative path, will usually use the CreateInstancePath
bool	throwOnError	throw errors if compiling fails, recommended

Returns

Type	Description
dynamic	An object of the class in the file

Remarks

Note that the C# code which we are creating inherits from a standard base class such as Code12 or DynamicCode then it will automatically be initialized to support App, AsDynamic etc.

CreateSource<T>(IDataSource, ILookUpEngine)

Create a IDataSource which will process data from the given stream.

Declaration

public T CreateSource<T>(IDataSource inSource = null, ILookUpEngine configurationProvider = null) where T : IDataSource

Parameters

Type	Name	Description
IDataSource	inSource	The data source which will be the default In of the new data-source.
ILookUpEngine	configurationProvider	An alternate configuration provider for the DataSource

Returns

Type	Description
T	A typed DataSource object

Type Parameters

Name	Description
T	A data-source type - must be inherited from IDataSource

CreateSource<T>(IDataStream)

Create a IDataSource which will process data from the given stream.

Declaration

public T CreateSource<T>(IDataStream source) where T : IDataSource

Parameters

Type	Name	Description
IDataStream	source	The stream which will be the default In of the new data-source.

Returns

Type	Description
T	A typed DataSource object

Type Parameters

Name	Description
T	A data-source type - must be inherited from IDataSource

File(string, bool?, string, string, string, object)

Create a File-result to stream to the client

Typical use: return File(download: true, contentType: "text/xml", contents: ...);

Declaration

public dynamic File(string noParamOrder = "Params must be named (https://go.2sxc.org/named-params)", bool? download = null, string virtualPath = null, string contentType = null, string fileDownloadName = null, object contents = null)

Parameters

Type	Name	Description
string	noParamOrder	see Convention: Named Parameters
bool?	download	If a download should be enforced (otherwise the file may just be displayed - like an image)
string	virtualPath	Path in the website to get the file from. Provide either virtualPath or contents
string	contentType	Mime Content-type. Will try to auto-detect from virtualPath or fileDownloadName if not provided.
string	fileDownloadName	Download name. If provided, it will try to force download/save on the browser.
object	contents	Content of the result - a string, byte[] or stream to include.

Returns

Type	Description
dynamic

Remarks

Added in 2sxc 12.05

Forbid()

Creates a .net-core like ForbidResult (.net-core like StatusCodes.Status403Forbidden by default).

Typical use: return Forbid();

Declaration

[NonAction]
public dynamic Forbid()

Returns

Type	Description
dynamic	The created .net-core like ForbidResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Some authentication schemes, such as cookies, will convert .net-core like StatusCodes.Status403Forbidden to a redirect to show a login page.

GetService<TService>()

Get a service from the Dependency Injection. The service can come from 2sxc, EAV or the underlying platform (Dnn, Oqtane).

Declaration

public TService GetService<TService>() where TService : class

Returns

Type	Description
TService	An object of the type or interface requested, or null if not found in the DI.

Type Parameters

Name	Description
TService	Interface (preferred) or Class which is needed

NoContent()

Creates a .net-core like NoContentResult object that produces an empty .net-core like StatusCodes.Status204NoContent response.

Typical use: return NoContent();

Declaration

[NonAction]
public dynamic NoContent()

Returns

Type	Description
dynamic	The created .net-core like NoContentResult object for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

NotFound()

Creates an .net-core like NotFoundResult that produces a .net-core like StatusCodes.Status404NotFound response.

Typical use: return NotFound();

Declaration

[NonAction]
public dynamic NotFound()

Returns

Type	Description
dynamic	The created .net-core like NotFoundResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

NotFound(object)

Creates an .net-core like NotFoundObjectResult that produces a .net-core like StatusCodes.Status404NotFound response.

Typical use: return Unauthorized("try another ID");

Declaration

[NonAction]
public dynamic NotFound(object value)

Parameters

Type	Name	Description
object	value

Returns

Type	Description
dynamic	The created .net-core like NotFoundObjectResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Ok()

Creates a .net-core like OkResult object that produces an empty .net-core like StatusCodes.Status200OK response.

Typical use: return Ok();

Declaration

[NonAction]
public dynamic Ok()

Returns

Type	Description
dynamic	The created .net-core like OkResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Ok(object)

Creates an .net-core like OkObjectResult object that produces an .net-core like StatusCodes.Status200OK response.

Typical use: return Ok(objectToInclude);

Declaration

[NonAction]
public dynamic Ok(object value)

Parameters

Type	Name	Description
object	value	The content value to format in the entity body.

Returns

Type	Description
dynamic	The created .net-core like OkObjectResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Redirect(string)

Creates a .net-core like RedirectResult object that redirects (.net-core like StatusCodes.Status302Found) to the specified url.

Typical use: return Redirect("https://2sxc.org");

Declaration

[NonAction]
public dynamic Redirect(string url)

Parameters

Type	Name	Description
string	url	The URL to redirect to.

Returns

Type	Description
dynamic	The created .net-core like RedirectResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

RedirectPermanent(string)

Creates a .net-core like RedirectResult object with .net-core like RedirectResult.Permanent set to true (.net-core like StatusCodes.Status301MovedPermanently) using the specified url.

Typical use: return RedirectPermanent("https://2sxc.org");

Declaration

[NonAction]
public dynamic RedirectPermanent(string url)

Parameters

Type	Name	Description
string	url	The URL to redirect to.

Returns

Type	Description
dynamic	The created .net-core like RedirectResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

SaveInAdam(string, Stream, string, string, Guid?, string, string)

Save a file from a stream (usually an upload from the browser) into an adam-field of an item. Read more about this in the the WebAPI docs for SaveInAdam

Declaration

public IFile SaveInAdam(string noParamOrder = "Params must be named (https://go.2sxc.org/named-params)", Stream stream = null, string fileName = null, string contentType = null, Guid? guid = null, string field = null, string subFolder = "")

Parameters

Type	Name	Description
string	noParamOrder	see Convention: Named Parameters
Stream	stream	the stream
string	fileName	file name to save to
string	contentType	content-type of the target item (important for security checks)
Guid?	guid
string	field
string	subFolder

Returns

Type	Description
IFile

StatusCode(int)

Creates a .net-core like StatusCodeResult object by specifying a statusCode.

Typical use: return StatusCode(403);

Declaration

[NonAction]
public dynamic StatusCode(int statusCode)

Parameters

Type	Name	Description
int	statusCode	The status code to set on the response.

Returns

Type	Description
dynamic	The created .net-core like StatusCodeResult object for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

StatusCode(int, object)

Creates a .net-core like ObjectResult object by specifying a statusCode and value

Typical use: return StatusCode(304, "not modified");

Declaration

[NonAction]
public dynamic StatusCode(int statusCode, object value)

Parameters

Type	Name	Description
int	statusCode	The status code to set on the response.
object	value	The value to set on the .net-core like `ObjectResult"/>.

Returns

Type	Description
dynamic	The created .net-core like ObjectResult object for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Unauthorized()

Creates an .net-core like UnauthorizedResult that produces an .net-core like StatusCodes.Status401Unauthorized response.

Typical use: return Unauthorized();

Declaration

[NonAction]
public dynamic Unauthorized()

Returns

Type	Description
dynamic	The created .net-core like UnauthorizedResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Unauthorized(object)

Creates an .net-core like UnauthorizedObjectResult that produces a .net-core like StatusCodes.Status401Unauthorized response.

Typical use: return Unauthorized("we don't like this");

Declaration

[NonAction]
public dynamic Unauthorized(object value)

Parameters

Type	Name	Description
object	value

Returns

Type	Description
dynamic	The created .net-core like UnauthorizedObjectResult for the response.

Remarks

This is a shim to ensure that .net Framework code can be written the same way as .net core WebApis. It returns a dynamic to make it easy to use, but the real .net core implementation returns a typed object.

Implements

IDynamicCode12

IDynamicCode

IHasLog

IDynamicWebApi

IHasCodeLog