Generating typed Business Foundation classes

This topic describes how to generate a typed Business Foundation (BF) class. It also describes code generation and templates to make access and modification of business foundation data easier. BF is an Object Relation Modeling tool built into Episerver Commerce that lets you store custom data that does not fit into the Episerver Commerce data model. You will discover that you almost always need to store custom data, such as data related to customer pricing, gift cards, and authentication SSO tickets.

Background

A short summary of BF entities:

• BF entities are not typed, with string names for fields everywhere in the code, which is then quite error-prone. Use string constants to make sure they are defined only once.
• Caching is not built into BF, unlike the catalog, customer, and order subsystems.
• The interface to retrieve BF entities is generic, which causes low code readability.
BF provides most of what is needed for paging but is missing a returned record count. When paging is setup, you need to know the following:
• what the first record is needed on a page
• the number of records to be returned
• the total number of records available to paging control (so the number of pages can be calculated)

BF lets you input only the first two parameters and does not give you a count of the total number of records matching the query.

The following example shows entities using the existing BF objects:

Sample templates and McCodeGen

McCodeGen.exe is a free tool for BF code generation. See the examples below to create a set of typed business foundation classes, based on example templates and the McCodeGen.exe (provided as a download below).

One example of a template is a simple typed BF class that generates a class file for an existing BF class. It inherits from EntityObject and simply exposes the fields for an EntityObject as typed fields. You can also create templates to create context classes that provide an API to retrieve, update, create, and delete these typed BF objects.

One of the context class templates provides access to the Business Manager methods used to retrieve EntityObject but returns the typed objects instead. The other context class template has this functionality plus caching and full paging support. The latter context class lets you configure the cache timeout.

The typed Business Foundation class template is called EntityObjectSimple.aspx. The non-cached typed BF context class template is EntityObjectAccessTemplateNoCaching.aspx. The cached typed BF context class template is EntityObjectAccessTemplate.aspx.

The following example shows the previous example's code using generated classes:

Exploring the classes created

When you explore the classes created in this example, consider:

• Classes generated by the class template have an ExtendedProperties property to provide access to any fields that are added to the business foundation entity definition but not defined in the class (for example, because the class was not updated after a field was added).
• Classes generated by the cached context class provide overloads to use a member Boolean property value to determine whether to use the cache,  or override the member Boolean indicator with your own specific caching indicator. You can set a default value for whether records are cached or retrieved from the cache AND override it when needed.
• The cached context class template explicitly defines cache timeout period. You can change the template to your desired timeout or use config settings to set them. 
• Both context classes are singletons.
• The record count takes the FilterElements to build a dynamic SQL query and returns a count of the number of records matching the List(/Search) conditions.

Implementing the example code

1. Unzip the download with code and templates.
2. Add the following .dlls to the bin directory.
   • Mediachase.BusinessFoundation.Data.dll
   • Mediachase.BusinessFoundation.Data.XmlSerializers.dll
   • Mediachase.BusinessFoundation.ObjectModel.dll
   • Mediachase.CodeGen.dll
   • Mediachase.CodeGen.VisualStudio.dll
   • Mediachase.Ibn.Core.dll
   • Mediachase.Ibn.Core.XmlSerializers.dll
   • Mediachase.Ibn.Data.dll
   • Mediachase.Ibn.Data.Services.dll
   • Mediachase.Ibn.Data.XmlSerializers.dll
   • Mediachase.Ibn.ObjectModel.dll
3. Copy one of the .mcgen files (it does not matter which one) to the root folder. Rename the .mcgen file so that its clear what BF class it is associated with and the class' purpose.
4. Open the newly-copied version of the .mcgen file in the root folder.
   1. Set the connectionString element value to the connection string for the Episerver Commerce database containing the BF class definition.
   2. Set the MetaClass element value to the name of the BF class you are typing.
   3. In the mcgen element, set the template for the class you want to use, such as Templates\EntityObjectAccessTemplate.aspx; see the descriptions of the templates above.
   4. In the params definition, set the namespace param value to the namespace you would like the class to contain, such as EPiServer.Training.BusinessObjects.
5. Open a commandline to the root folder. Run the following command : mccodegen -mcgen:: -out:
   For example: mccodegen -mcgen:GiftCard.mcgen -out:GiftCardAccess.cs
   A new class is created based on the template you specified. Use the typed class template to generate the typed BF class. Use one of the context class templates to generate the context class to access the typed BF class.
6. For each typed class or context class you want to create, iterate through steps 2-5.

Related topic

• Working with Entity Objects describes how to build the McCodeGen tool into your Visual Studio environment.