Retrieving

Behavior

This event is triggered on the server before the data fetching query is called.

It is triggered when you call the following methods :

• GetAsync(Object)
• FindAsync(Object)
• GetListAsync(Func<IQueryable<TEntityView>, IQueryable<TEntityView>>)
• GetPagedListAsync(Int32, Int32, Func<IQueryable<TEntityView>, IQueryable<TEntityView>>)
• CountAsync(Func<IQueryable<TEntityView>, IQueryable<TEntityView>>)

The rule is cancelable in order to be able to prevent entities from being fetched.

Warning

In the current version, the event is not triggered for the additional data fetched through navigation properties.

Arguments

You can find the details of the interface here

Name	Type	Description
Context	IBusinessRuleContext	Represents a key/value pair dictionary that is used to store custom data. You can find the details of the interface on this page
Skip	int?	The number of elements to skip.
Top	int?	The number of elements to return.
Key	object?	The key if it is the retrieving of a particular record.
Parameters	IReadOnlyEntityViewParameters	The query strings parameter collection. You can find the details of the interface on this page
Items	IReadOnlyList	Items that will still be sent to the client when the data fetching request is canceled.
WillTransform	boolean	A value indicating whether the data will be transformed (e.g. grouping).
Cancel	boolean	If set to true, the query will not be called. Items can still manually be returned using the SetItemSource or SetItems method.
IsCountQuery	boolean	A value indicating whether the query is a count query.

Note

The context is shared between the Retrieving and Retrieved events. Any value added in the context during the Retrieving event is available during the Retrieved event.

Manually setting the retrieved items

When you decide to cancel the data fetching query, you can still manually fill the args.Items property with a list of entities you want to return to the client.

Note

args.Items is read-only, you must call args.SetItems or args.SetItemsSource to initialize it.
args.Cancel does not need to be manually set to true when calling these methods as they automatically cancel the event.

A common use case is to return an already available list of items without reading the database.

Sometimes you may need to aggregate additional data with the data retrieved from the database. The args.RetrieveItemsAsync method allows you to get the data that would normally be retrieved from the database. You can then customize the retrieved items and call the args.SetItems or args.SetItemSource methods to set the items returned by the rule.

Warning

args.RetrieveItemsAsync loads every matching item in memory. If you only need the total number of items, or if you need both a page of items and the total, do not call it a second time without pagination just to read .Length : use args.RetrieveCountAsync or args.RetrievePagedItemsAsync instead (see below), they issue a COUNT query without materializing the items.

If you only need the total number of items, args.RetrieveCountAsync returns the count without loading the items.

If you need both a page of items and the total number of matching items, args.RetrievePagedItemsAsync returns both in a single call. It applies args.Skip/args.Top itself, so the query customization you pass must only contain filters and sorting, not paging — this lets the same customization be reused to compute the total. It throws InvalidOperationException if Skip or Top is not set.

Note

Unlike args.RetrieveItemsAsync, args.RetrieveCountAsync and args.RetrievePagedItemsAsync always require a CancellationToken argument — there is no overload without one, to avoid dropping it by mistake. Pass the cancellationToken received by OnRetrievingAsync.

When IsCountQuery is true, you can set the count value by calling the args.SetCount method otherwise the count will be the number of items returned.

Filtering retrieved items

It is possible to add filters to the query that will be executed to retrieve items from the database :

• args.AppendFilter adds a filter based on the entity view properties
• args.AppendEntityFilter adds a filter based on the entity properties

Filters are boolean conditions that are appended using an AND operator. They need to be translatable in SQL by Entity Framework (see this article).

Note

You can call these methods multiple times to add as many filters as needed.

Using the Key property

The Key property is of type object and is not directly usable. To obtain the values ​​of the properties composing the key, you must use the GetKeyValues method of the repository. A code example is available here.