Interface IEntityRetriever

This is the core context class used for querying all data in the LemonEdge platform, regardless if the context is executing directly connected to the database, or across a web service

This context is always provided within UI and Context APIs, ensuring you can always access data wherever it is needed from a view, command, server running task or elsewhere

All queries can refer to the interface for a type, or the class that implements it

Inherited Members
Namespace: LemonEdge.API.Core.Data
Assembly: LemonEdge.API.dll
Syntax
public interface IEntityRetriever : IDisposable

Properties

CanvasID

The Canvas this context is running in. Do not change the canvas, it is handled by the system given the canvas the User is currently running in, and will be ignored by the web service anyway

Declaration
Guid? CanvasID { get; set; }
Property Value
Type Description
Guid?

GetUseAsOfDate

The as of date all queries in the context are running in. You should not change this for a system provided IENtityRetriever, however you can get a new IEntityRetriever and run that with any As Of Date you wish

Declaration
DateTimeOffset? GetUseAsOfDate { get; }
Property Value
Type Description
DateTimeOffset?

GetUseLabels

If this context is running within a server, or for non UI displayed reasons, you don't need queries returning labels. This significantly imprives the speed of queries that have a lot of relationships.

This indicates if queries will populate _Label fields for relationships by default or not

Declaration
bool GetUseLabels { get; }
Property Value
Type Description
bool

IsDirectDBConnection

Indicates if this context is directly connected to the database server or not

Used by certain validation that you only want to run when connected to the db as could be expensive.

If not connected it wont be run, but will be run by the service when it processes the changes and performs its own validation
Declaration
bool IsDirectDBConnection { get; }
Property Value
Type Description
bool

IsDisposed

Declaration
bool IsDisposed { get; }
Property Value
Type Description
bool

IsODataQuery

Indicates if this underlying query is being executed through a web service or direct db connection

If this is a direct db connection some queries are changed to make sure the results are consistent across service or direct db connection.

For instance string comparisons are case insensitive against the database so we change comparisons to use ToLower to make sure in memory queries provide the same results. We can't do this on an OData query as ToLower isn't translatable from Linq to OData, and the odata web service implementation is performing a case insensitive comparison anyway

Declaration
bool IsODataQuery { get; }
Property Value
Type Description
bool

UniqueContextID

Unique id for each instance of a context

Declaration
Guid UniqueContextID { get; }
Property Value
Type Description
Guid

Methods

AddItemByIDToCache(IBaseEntity)

Returns true if added, false if already in cache

Declaration
bool AddItemByIDToCache(IBaseEntity item)
Parameters
Type Name Description
IBaseEntity item
Returns
Type Description
bool

ExecuteCustomQuery<T>(string, params object[])

Executes the specified CustomServiceQueryExtender<T> which enables LINQ style queries to join across all entities in the system in one query

Declaration
Task<IEnumerable<T>> ExecuteCustomQuery<T>(string customQueryName, params object[] parameters) where T : IBaseEntity
Parameters
Type Name Description
string customQueryName

The name of the method in the class that inherits the CustomServiceQueryExtender that you want to execute
object[] parameters

A param array of parameters to be passed to this method
Returns
Type Description
Task<IEnumerable<T>>

A task holding the results of executing the custom LINQ query
Type Parameters
Name Description
T

The type of item returned by the CustomServiceQueryExtender
Remarks

The QueryableExecuter works for retrieveing and querying results easily through this interface that abstracts if its running through the web service or directly to the database. However it only allows queries against one type of entity.

Using a CustomServiceQueryExtender<T> enables you to create a normal IQueryable query that joins across multiple entity types, and is dynamically translated into sql for you. Again this works across the web service or directly connected to the database.

See CustomServiceQueryExtender<T> for more information, but the intention is that these are used only for queries across multiple entity types for performance. All other queries can be resolved using QueryableExecuter which are faster and more efficient for querying individual entity types that do not require joins.

See Also

ExecuteQuery(QueryableExecuter)

Takes a QueryableExecuter and executes the query against the database (possibly via a web service) and returns the results

If this context contains any changes of the query entity type then those changes won't be overwritten by the results, they will be included if they match the QueryableExecuter filter

Declaration
Task<IEnumerable<IBaseEntity>> ExecuteQuery(QueryableExecuter items)
Parameters
Type Name Description
QueryableExecuter items

The queryable executer containing the definition of the query to execute. Can be created from GetItems(Type)
Returns
Type Description
Task<IEnumerable<IBaseEntity>>

A task holding the result set of the query as an enumeration

ExecuteQueryAsCSV(DateTimeOffset?, Guid?, string, string, string)

Executes the specified query and returns the results as a CSV file in bytes

Declaration
Task<byte[]> ExecuteQueryAsCSV(DateTimeOffset? asOfDate, Guid? canvasID, string typeKey, string base64SerializedQueryExecuter, string base64SerializedColumnsToReturn)
Parameters
Type Name Description
DateTimeOffset? asOfDate

Runs the query using the specified As Of Date. Null indicates no as of date, and to just use the current data.
Guid? canvasID

Runs the query using the specified Canvas. Null indicates no canvas, and to just use the current main system.
string typeKey

The key (UniqueKey) of the entity type we want to run a query against.
string base64SerializedQueryExecuter

The serialization string of a QueryableExecuter containing the query to execute against this type typeKey of entities
string base64SerializedColumnsToReturn

A serialized string of an array of ColumnDescriptor indicating the properties for the type to return. Null indicates all properties for this entity type.
Returns
Type Description
Task<byte[]>

A Task holding the result of running the specified query, converting the results to a formatted csv file and then to a byte array

ExecuteQuery<T>(QueryableExecuter<T>)

Takes a QueryableExecuter<T> and executes the query against the database (possibly via a web service) and returns the results

If this context contains any changes of type T then those changes won't be overwritten by the results, they will be included if they match the QueryableExecuter filter

Declaration
Task<IEnumerable<T>> ExecuteQuery<T>(QueryableExecuter<T> items) where T : IBaseEntity
Parameters
Type Name Description
QueryableExecuter<T> items

The queryable executer containing the definition of the query to execute. Can be created from GetItems<T>()
Returns
Type Description
Task<IEnumerable<T>>

A task holding the result set of the query as an enumeration
Type Parameters
Name Description
T

The type of items we are executing a query against

ExecuteSQLResultsAsCSV(Guid, string, string, string)

Executes the specified ISQLWrapper and returns the results as a byte array of a csv fotmatted file of the results

Declaration
Task<byte[]> ExecuteSQLResultsAsCSV(Guid sqlWrapperID, string base64SerializedParameters, string base64SerializedQueryExecuter, string base64SerializedColumnsToReturn)
Parameters
Type Name Description
Guid sqlWrapperID

The ID of the SQL Wrapper to execute
string base64SerializedParameters

A serialized Dictionary<TKey, TValue> of String, String, holding the parameters for this query. The key the ParameterName for the paramater, and the value the value
string base64SerializedQueryExecuter

The serialization string of a QueryableExecuter<T> (of type ISQLWrapperResult or the custom Complex or Entity type that can also hold the results) containing the query to execute against this result set
string base64SerializedColumnsToReturn

A serialized string of an array of ColumnDescriptor indicating the columns for the SQLWrapper query to return. Null indicates all columns defined in this SQLWrapper.
Returns
Type Description
Task<byte[]>

A Task holding the result of running the specified query, converting the results to a formatted csv file and then to a byte array

GetItemByID(Type, Guid)

Returns the item of type type specified by the id

Declaration
Task<IBaseEntity> GetItemByID(Type type, Guid id)
Parameters
Type Name Description
Type type

The type of entity to return
Guid id

The ID of the entity to return
Returns
Type Description
Task<IBaseEntity>

A task holding the result of the request

GetItemByID<T>(Guid)

Returns the item of type T specified by the id

Declaration
Task<T> GetItemByID<T>(Guid id) where T : IBaseEntity
Parameters
Type Name Description
Guid id

The ID of the entity to return
Returns
Type Description
Task<T>

A task holding the result of the request
Type Parameters
Name Description
T

The type of entity to return

GetItems(Type)

Returns a new QueryableExecuter for the specified type of item. This can be used to create a query for retrieveing certain items of type type, which can be executed using ExecuteQuery(QueryableExecuter)

Declaration
QueryableExecuter GetItems(Type type)
Parameters
Type Name Description
Type type

The type of items that the QueryableExecuter can query
Returns
Type Description
QueryableExecuter

The new QueryableExecuter for this specified type

GetItems<T>()

Returns a new QueryableExecuter<T> for the specified type of item. This can be used to create a query for retrieveing certain items of type T, which can be executed using ExecuteQuery<T>(QueryableExecuter<T>)

Declaration
QueryableExecuter<T> GetItems<T>() where T : IBaseEntity
Returns
Type Description
QueryableExecuter<T>

The new QueryableExecuter for this specified type
Type Parameters
Name Description
T

The type of items that the QueryableExecuter can query

GetQueryCount(DateTimeOffset?, Guid?, string, string, string)

Executes the specified query and returns the count of the matching results

Declaration
Task<int> GetQueryCount(DateTimeOffset? asOfDate, Guid? canvasID, string typeKey, string base64SerializedQueryExecuter, string base64SerializedColumnsToReturn)
Parameters
Type Name Description
DateTimeOffset? asOfDate

Runs the query using the specified As Of Date. Null indicates no as of date, and to just use the current data.
Guid? canvasID

Runs the query using the specified Canvas. Null indicates no canvas, and to just use the current main system.
string typeKey

The key (UniqueKey) of the entity type we want to run a query against.
string base64SerializedQueryExecuter

The serialization string of a QueryableExecuter containing the query to execute against this type typeKey of entities
string base64SerializedColumnsToReturn

A serialized string of an array of ColumnDescriptor indicating the properties for the type to return. Null indicates all properties for this entity type.
Returns
Type Description
Task<int>

A task holding the count of the row results from running the specified query

GetSQLResults(Guid, string, string, string, CancellationToken)

Executes the specified ISQLWrapper and returns the results set of ISQLWrapperResults. SQLWrapperInterpretor can be used to interrogate the values of each result item.

Declaration
Task<IEnumerable<ISQLWrapperResult>> GetSQLResults(Guid sqlWrapperID, string base64SerializedParameters, string base64SerializedQueryExecuter, string base64SerializedColumnsToReturn, CancellationToken token = default)
Parameters
Type Name Description
Guid sqlWrapperID

The ID of the SQL Wrapper to execute
string base64SerializedParameters

A serialized Dictionary<TKey, TValue> of String, String, holding the parameters for this query. The key the ParameterName for the paramater, and the value the value
string base64SerializedQueryExecuter

The serialization string of a QueryableExecuter<T> of type ISQLWrapperResult containing the query to execute against this result set
string base64SerializedColumnsToReturn
CancellationToken token
Returns
Type Description
Task<IEnumerable<ISQLWrapperResult>>

A task holding the results of your query. SQLWrapperInterpretor can be used to interrogate the values of each result item.
Remarks

This function is extremely powerful as it allows you to execute any custm created SQLWrapper to get high performant results from a context anywhere within your application code

See Also

GetSQLResultsCount(Guid, string, string)

Executes the specified sqlWrapperID and returns the count of the results

Declaration
Task<int> GetSQLResultsCount(Guid sqlWrapperID, string base64SerializedParameters, string base64SerializedQueryExecuter)
Parameters
Type Name Description
Guid sqlWrapperID

The ID of the SQL Wrapper to execute
string base64SerializedParameters

A serialized Dictionary<TKey, TValue> of String, String, holding the parameters for this query. The key the ParameterName for the paramater, and the value the value
string base64SerializedQueryExecuter

The serialization string of a QueryableExecuter<T> of type ISQLWrapperResult containing the query to execute against this result set
Returns
Type Description
Task<int>

A task holding the count of the number of items that would be returned from executing this query

GetSQLResultsCount<T>(Guid, string, string)

Executes the specified sqlWrapperID and returns the count of the specified custom types (either or complex or entity types) that have properties matching the Name of the columns returned by the SQLWrapper

Declaration
Task<int> GetSQLResultsCount<T>(Guid sqlWrapperID, string base64SerializedParameters, string base64SerializedQueryExecuter)
Parameters
Type Name Description
Guid sqlWrapperID

The ID of the SQL Wrapper to execute
string base64SerializedParameters

A serialized Dictionary<TKey, TValue> of String, String, holding the parameters for this query. The key the ParameterName for the paramater, and the value the value
string base64SerializedQueryExecuter

The serialization string of a QueryableExecuter<T> of type T containing the query to execute against this result set
Returns
Type Description
Task<int>

A task holding the count of the number of results that would be returned from executing this query
Type Parameters
Name Description
T

The type (eith a complex or entity type) that has properties matching the columns returned by the query

GetSQLResults<T>(Guid, string, string)

Executes the specified sqlWrapperID and returns the results set as a collection of specified custom types (either or complex or entity types) that have properties matching the Name of the columns returned by the SQLWrapper

Declaration
Task<IEnumerable<T>> GetSQLResults<T>(Guid sqlWrapperID, string base64SerializedParameters, string base64SerializedQueryExecuter)
Parameters
Type Name Description
Guid sqlWrapperID

The ID of the SQL Wrapper to execute
string base64SerializedParameters

A serialized Dictionary<TKey, TValue> of String, String, holding the parameters for this query. The key the ParameterName for the paramater, and the value the value
string base64SerializedQueryExecuter

The serialization string of a QueryableExecuter<T> of type T containing the query to execute against this result set
Returns
Type Description
Task<IEnumerable<T>>

A task holding the results of the query
Type Parameters
Name Description
T

The type (eith a complex or entity type) that has properties matching the columns returned by the query

SetCancellationToken(CancellationToken)

Declaration
void SetCancellationToken(CancellationToken token)
Parameters
Type Name Description
CancellationToken token

UseAsOfDate(DateTimeOffset)

Specifies the as of date all queries in the context are running in. You should not change this for a system provided IENtityRetriever, however you can get a new IEntityRetriever and run that with any As Of Date you wish

If you are returning items as of a prior point in time you should not attempt to modify them - it will fail

Declaration
IEntityRetriever UseAsOfDate(DateTimeOffset asOfDate)
Parameters
Type Name Description
DateTimeOffset asOfDate

The as of date to use for running queries from this context with.
Returns
Type Description
IEntityRetriever

The current context so commands can be chained

UseCanvas(Guid)

Specifies the context should run in the specified Canvas. Do not change the canvas, it is handled by the system given the canvas the User is currently running in, and will be ignored by the web service anyway

Declaration
IEntityRetriever UseCanvas(Guid canvasID)
Parameters
Type Name Description
Guid canvasID

Th ID of the canvas this context should run in
Returns
Type Description
IEntityRetriever

The current context so commands can be chained

UseLabels(bool)

Indicates if items returned will have relationship fields with _Label properties automatically populated or not.

This is only required for items that are displayed in the UI, all other items don't need this and can benefit from performance improvements

Declaration
IEntityRetriever UseLabels(bool useLabels)
Parameters
Type Name Description
bool useLabels

Indicates if queries should use labels or not
Returns
Type Description
IEntityRetriever

The current context so commands can be chained

Extension Methods

See Also