Generate typed Business Foundation classes

Business Foundation (BF) is an Object Relation Modeling tool built into Optimizely Commerce Connect that lets you store custom data that does not fit into the commerce data model. You almost always need to store custom data, such as data related to customer pricing, gift cards, and authentication SSO tickets.

Background

Here is a summary of BF entities:

• BF entities are not typed, with string names for fields everywhere in the code. This is 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 the paging needed but lacks a returned record count. When paging is setup, you need to know the following:
  • what first record is needed on a page
  • the number of records to be returned
  • the total number of records available to the 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:

Explore 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 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.

Implement 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 a .mcgen file (it does not matter which one) to the root folder. Rename the .mcgen file so that it is clear which BF class it is associated with and the class' purpose.
4. Open the newly-copied version of the .mcgen file in the root folder.
   a. Set the connectionString element value to the connection string for the Optimizely Commerce Connect database containing the BF class definition.
   b. Set the MetaClass element value to the name of the BF class you are typing.
   c. 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.
   d. 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 specified template. 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.