Generating typed business foundation classes

Introduction

This document describes how to generate a typed business foundation class. Here we will describe code generation and templates to make access and modification of business foundation data easier. Business Foundation is an Object Relation Modeling tool built into EPiserver Commerce that allows you to store custom data that does not fit into the EPiServer Commerce data model. You will discover that there is almost always custom data that needs to be stored, for instance related to customer pricing, gift cards, and authentication SSO tickets.

Background

A short summary of Business Foundation entities:

• Business Foundation entities are not typed, with string names for fields everywhere in the code, which is then quite error prone. This can be addressed using string constants to make sure they are only defined once.
• Caching is not built into Business Foundation, unlike the catalog, customer, and order subsystems.
• The interface to retrieve Business Foundation entities is generic which causes low code readability.
• It provides most of what is needed for paging but its missing a returned record count. When paging is setup, you need to know a) what the first record is needed on a page, b) the number of records to be returned, and c) the total number of records available to paging control (so the number of pages can be calculated). Business Foundation only allows you to input the first two parameters and doesn not give you a count of the total number of records matching the query.

Example of what it looks like using the existing Business Foundation objects:

Sample templates and McCodeGen

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

One example of a template is a simple typed Business Foundation class that will generate a class file for an existing Business Foundation class. It inherits from EntityObject and simply exposes the fields for an EntityObject as typed fields. You can also create templates which can be used to create context classes which provide an API to retrieve, update, create, and delete these typed Business Foundation 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 allows you to configure the cache timeout.

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

Example of what the above code would look like using generated classes:

Exploring the classes created

Notice the following when exploring the classes created in this example:

• Classes generated by the class template will have a property called ExtendedProperties to provide access to any fields that have been 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 provides overloads to either a) use a member Boolean property value to determine whether to use the cache or not or b) override the member Boolean indicator with your own specific caching indicator. You can set a default value for whether records will be cached or retrieved from the cache AND you can override it when needed.
• The cached context class template explicitly defines the cache timeout period. It is easy to change the template to your desired timeout or use config settings to set them. There are lots of possible enhancements/changes you may need to make here depending on your implementation.
• 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 into the root folder (it does not matter which one). Rename the .mcgen file so that its clear what Business Foundation class its associated with and the purpose of the class.
4. Open the newly-copied version of the .mcgen file in the root folder. Set the connectionString element value to the connection string for the EPiServer Commerce database containing the business foundation class definition. Set the MetaClass element value to the name of the Business Foundation class you are typing. In the mcgen element, set the template for the class you want to use, for example "Templates\EntityObjectAccessTemplate.aspx"; see the descriptions of the templates above. In the params definition, set the namespace param value to the namespace you would like the class to contain, for example "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 will be created based on the template you specified. You will need to use the typed class template to generate the typed Business Foundation class; use one of the context class templates to generate the context class to access the typed Business Foundation class.
6. For each typed class or context class you want to create, iterate through steps 2-5.

See also

• Working with Entity Objects for more information on how to build the McCodeGen tool into your Visual Studio environment.