Generated code - Excluding / Including fields for fetches
Preface
Sometimes entities have fields which can be big in size, for example an Employee entity which has a Photo field which can contain an image, or an Order entity
which can contain the Proposal Word document. In other situations, it can be that you only want to fetch a subset of the fields of an entity. It then would be
great if you could
exclude one or more fields for the fetch of the entity or collection of entities. LLBLGen Pro allows you to do that: in single entity fetches, entity collection fetches
and prefetch path nodes.
To specify which fields to exclude, you have two options:
- Specify the fields to exclude
- Specify the fields to fetch (i.e. include) which means the rest is excluded.
To do this, you use the
ExcludeIncludeFieldsList class and use its
ExcludeContainedFields to specify what LLBLGen Pro should do with the fields contained in the list. By default,
ExcludeContainedFields is set to true, which means that all fields added to the instance of
ExcludeIncludeFieldsList should be seen as the fields to exclude (thus option 1. in the list above). When
ExcludeContainedFields is set to false, the fields added to the instance of
ExcludeIncludeFieldsList should be seen as the fields to
fetch (so the rest is excluded, option 2. in the list above). This gives great flexibility to specify the excluded fields. Sometimes the list of fields to exclude is larger than the list of fields to fetch, so in that case use option 2. If the list of fields is smaller than the list of fields to fetch, use option 1.
To fetch an entity or collection of entities with an ExcludeIncludeFieldsList, use one of the overloads for the various fetch methods which accept an ExcludeIncludeFieldsList object.
After you've fetched the entities, for example a set of employees without their Photo or Notes field, it can be you want to fetch that excluded data
into the
entity object you have in memory. For example you have a grid of Employee entities and when a given Employee entity in that grid is selected, the detail view of the entity requires the
Photo and the Notes fields, which weren't fetched for the grid. LLBLGen Pro offers you to fetch these excluded fields into an entity which was fetched without these fields.
The examples below show you how to specify the fields to exclude and also how to fetch the
data back into the entities.
In the .NET 2.0+ build of the ORMSupportClasses runtime library, two utility classes are present:
ExcludeFieldsList and
IncludeFieldsList. Both classes derive from ExcludeIncludeFieldsList, and set the excludeContainedFields flag through the constructor. They don't contain any logic, though make it easier for people reading the code if the ExcludeIncludeFieldsList instance contains fields to exclude or fields to include.
 Note: |
| For selfservicing, the fetch of the field which was excluded isn't transparent. This is done because if you want to fetch multiple
excluded fields of the same entity, it would result in multiple queries for the same entity. Also, the information which fields were excluded isn't
stored inside the entity after it's fetched. |
Fetching excluded fields in batches
The following examples first fetch the entities without some excluded fields, and then show how to fetch the data back into the existing entities. LLBLGen Pro will do this in
batches. So if you have 10,000 entities in memory and you want the data you excluded when fetching these entities fetched into these entities, LLBLGen Pro will break the set of 10,000 up into smaller sets and fetch the
excluded fields per batch. The batch size is controlled using the
DaoBase.ParameterizedPrefetchPathThreshold which is also used for parameterized prefetch paths. This same constant is used as the logic to fetch the excluded fields follows the same pattern. The initial batch size is
5 * the value of that threshold,
where
the number of primary fields * the number of entities to process is used to determine the number of batches to fetch, as the batch size set controls the number of parameters emitted in the query. Example:
if the entity has a primary key of two fields, and you specify that ParameterizedPrefetchPathThreshold is 10, the initial batch size is 50, and because the number of primary fields is 2,
25 entities per batch are processed, resulting in 2 batches if you have 50 entities to process.
To fetch excluded fields into existing entities, use the method
entity.
FetchExcludedFields or
entitycollection.
FetchExcludedFields. Please see the LLBLGen Pro reference manual for overloads on the various fetch methods for entities (single entities and collections) to see which ones accept an ExcludeIncludeFieldsList.
Entity fetch example
The following example uses the default constructor of ExcludeIncludeFieldsList, which sets the ExcludeContainedFields property to true. This means that the fields added to it are meant to be excluded. It will fetch all Northwind customers but with some fields excluded, which are after the fetch loaded into the entities again.
// C#
ExcludeIncludeFieldsList excludedFields = new ExcludeIncludeFieldsList();
excludedFields.Add(CustomerFields.ContactName);
excludedFields.Add(CustomerFields.Country);
// fetch a collection of customers.
CustomerCollection customers = new CustomerCollection();
SortExpression sorter =
new SortExpression(CustomerFields.CustomerId | SortOperator.Descending);
customers.GetMulti(null, 0, sorter, null, null, excludedFields, 0, 0);
// fetch a single customer
CustomerEntity c = new CustomerEntity();
c.FetchUsingPK("CHOPS", null, null, excludedFields);
// ...
// load the excluded fields into the entities already loaded:
c.FetchExcludedFields(excludedFields);
customers.FetchExcludedFields(excludedFields);
' VB.NET
Dim excludedFields As New ExcludeIncludeFieldsList()
excludedFields.Add(CustomerFields.ContactName)
excludedFields.Add(CustomerFields.Country)
' fetch a collection of customers.
Dim customers As New CustomerCollection()
Dim sorter As New SortExpression(CustomerFields.CustomerId Or SortOperator.Descending)
customers.GetMulti(Nothing, 0, sorter, Nothing, Nothing, excludedFields, 0, 0)
' fetch a single customer
Dim c As New CustomerEntity()
c.FetchUsingPK("CHOPS", Nothing, Nothing, excludedFields)
' ...
' load the excluded fields into the entities already loaded:
c.FetchExcludedFields(excludedFields)
customers.FetchExcludedFields(excludedFields)
Prefetch path example
Excluding fields for fetches also works with prefetch paths. The following example illustrates that.
// C#
ExcludeIncludeFieldsList excludedFields = new ExcludeIncludeFieldsList();
excludedFields.Add(OrderFields.OrderDate);
// Fetch the first 25 customers with their orders which have the OrderDate excluded.
PrefetchPath path = new PrefetchPath(EntityType.CustomerEntity);
path.Add(CustomerEntity.PrefetchPathOrders, excludedFields);
CustomerCollection customers = new CustomerCollection();
customers.GetMulti(null, 25, null, null, path, excludedFields, 0, 0);
' VB.NET
Dim excludedFields As New ExcludeIncludeFieldsList()
excludedFields.Add(OrderFields.OrderDate)
' Fetch the first 25 customers with their orders which have the OrderDate excluded.
Dim path As New PrefetchPath(EntityType.CustomerEntity)
path.Add(CustomerEntity.PrefetchPathOrders, excludedFields)
Dim customers As New CustomerCollection()
customers.GetMulti(Nothing, 25, Nothing, Nothing, path, excludedFields, 0, 0)
