Generating Typed Business Foundation Classes In EPiCommerce

Introduction

Business Foundation is a pretty powerful tool... and you'll probably like it more if you make use of what I provide here. We'll be covering code generation and templates to make access and modification of business foundation data much cleaner and clearer.

Business Foundation is an Object Relation Modeling tool built right into EPiCommerce that allows you to very easily store custom data that doesn't fit into the EPiCommerce data model. I've found Business Foundation useful in most implementations because there's almost always custom data that needs to be stored about customer pricing, gift cards, authentication SSO tickets, and a myriad of other things.

For more introduction to using Business Foundation, take a look at this blog from Cecilia von Wachenfelt:
http://world.episerver.com/Blogs/Cecilia-von-Wachenfeldt/Dates/2011/7/An-example-using-Business-Foundation-in-EPiServer-Commerce/

For a more in-depth look at the Business Foundation architecture and API, look here:
http://sdk.episerver.com/commerce/1.1/Content/Developers%20Guide/Architecture/BusinessFoundation/Business%20Foundation.htm

The Problem

There are only a few problems I have with using Business Foundation. They're problems that are solvable but the solutions were always manual. Here are the problems I've had with it:

* Business Foundation entities are not typed. This means there were string names for fields everywhere in the code, which is quite error prone and messy. This can be addressed using string constants to make sure they're 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 too generic. Its powerful by being generic but the code readability is low because of it.
* It provides most of what's 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). Right now, Business Foundation only allows you to input the first two parameters but doesn't give you a count of the total number of records matching the query.

Here is an example snapshot that shows you what it looks like using the existing Business Foundation objects:

A Solution

McCodeGen.exe is a free tool (I didn't write it) for business foundation code generation that will help solve this (see download link below). I've also provided some templates that can be used by McCodeGen.exe to specifically address these shortcomings. By following the directions below, you can create several typed business foundation classes.

One 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. The next two templates 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". All of these files are located in the Templates folder of the files in the download link below.

Here's an example of what the above code would look like using generated classes:

Much better right?

There are a few caveats/points to be made about the classes created using these templates:
* 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 wasn't 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. So 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. Its very 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 return a count of the number of records matching the List(/Search) conditions. I'm sure there are more elegant solutions and I'm happy to repost (and give credit) if someone wants to improve that... or for that matter, any part of these templates.

Directions For Implementing

1. Unzip download from here: Download Link. 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

2. Copy one of the .mcgen files into the root folder (doesn't matter which one). Rename the .mcgen file so that its clear what Business Foundation class its associated with and the purpose of the class.
3. Open the newly-copied version of the .mcgen file in the root folder. Set the connectionString element value to the connection string for the EPiCommerce 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'd like the class to contain, for example "EPiServer.Training.BusinessObjects".
4. Open a commandline to the root folder. Run the following command :
mccodegen -mcgen:<name of .mcgen file created in the root folder in step 2. Include the .mcgen extension> -out:<name of class file to be generated with .cs at the end>

For example: mccodegen -mcgen:GiftCard.mcgen -out:GiftCardAccess.cs

A new class will be created based on the template you specified. You'll 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.

5. For each typed class or context class you want to create, iterate through steps 2-4.

For further study, there are ways to build the McCodeGen tool into your Visual Studio environment so that you can easily update you typed Business Foundation classes as described here:
http://sdk.episerver.com/commerce/1.1/Content/Developers%20Guide/Architecture/BusinessFoundation/Working%20with%20Entity%20Objects.htm
I've included files necessary for this in the Visual Studio folder.