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:
  1. Specify the fields to exclude
  2. 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 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)

LLBLGen Pro v2.6 documentation. ©2002-2008 Solutions Design