Needs Improvement

Introducing Spencer

Colin Coller — Mon, 12 Oct 2009 17:02:39 GMT

I've started a new project called Spencer. The goal of the project is to demonstrate how e-commerce applications can be built from simple, composable services, with an emphasis on scalability, flexibility, "multibility" (multi-tenant, -brand, -channel, -store, etc), and platform independence. The project's code will be written in C# using WCF, WF, Enterprise Library, and Unity, with examples written to integrate with Commerce Server.

I've released the source for two services already:

Product Feedback Service for retrieving feedback about products, including ratings, recommendations, and reviews.
Product Image Service (no page yet, but the code's in TFS) for retrieving images of products.

In the next few weeks I'll be releasing additional services, and posting additional information about the project, the services, and techniques for combining the services into applications.

Cheers,

Colin

Defining Events and Writing Operations Guides

Colin Coller — Sun, 13 Sep 2009 20:37:57 GMT

Tess Ferrandez has written a great post describing the questions she asks when troubleshooting a problem. Her nine questions are not only a great way to create a problem description; they’re also a great way to define events that occur in your application, and to write an operations guide that describes the events and what to do when they do occur. For example:

"What is happening?”

What happened? The customer wish list feature was unable to retrieve the number of items in a customer’s wish list because of an unhandled exception: …
When did the event occur? September 12, 2009
What application did the event occur in? Web storefront
Who was using the application when the event occurred? colincatjtleigh

"What did you expect to happen?”

What was the application doing when the event occurred? Calling the Commerce Server 2007 orders API to retrieve the customer’s wish list basket.

"When is it happening?”

What was the user doing when the event occurred? Loading a page that displays the quick cart link in the top navigation menu.
…on what page? /Profile/MyAccount.aspx
…on what server? EXT-WEB-12
…in what environment? Production
…etc? SiteName = “SweetDeal”; BasketId = {…}; BasketName = “WishList”

"When did it start happening?”

"How does this problem affect you?”

How does the event affect the user or other users of the application? The user won’t see the number of items in their wish list in the quick cart link in the top navigation menu. The page will still load, however.
How severe is the event? This is an error.
What priority should be given to investigating and resolving the event relative to other events, and why? This should be medium priority. This may be a data issue affecting only this customer, but it may also be an issue with the orders subsystem that would affect other customers. This may prevent this customer from viewing, adding items to, or removing items from their wish list. This will not prevent this customer from using the core e-commerce functionality.

"What do you think the problem is? and what data are you basing this on?"

What are some of the causes for the event? Invalid wish list basket data. The orders database being unavailable.
What has historically caused the event? In most cases, this issue is caused by incorrect wish list basket data from old wish list baskets that were improperly migrated from R4.0 to R4.5.

"What have you tried so far?"

What are some of the steps that should be taken when investigating the event? Confirm that the orders subsystem is functional. Export the customer’s wish list basket using the BASEXPORT utility. Inspect the exported basket to ensure it contains the correct data for a wish list basket.
Where would information helpful or necessary to investigating the event be? The server event log. The customer’s wish list basket.
What are the standard processes for resolving the event? If this is a data issue affecting only this customer, flush the customer’s wish list basket using the BASFLUSH utility.

"What is the expected resolution?"

How can you determine whether the event has been resolved? The customer can add an item to their wish list, load a subsequent page, and see the number of items in their wish list in the quick cart link.

"Is there anything that would prohibit certain troubleshooting steps or solutions?"

It's easy to log events, but it's much more difficult to define events that are worth logging or that are useful. By asking these questions as you define events, and by documenting the answers in the events and in an operations guide, you can make it much easier for others to operate and understand your application.

Cheers,

Colin

5 Different .ca Wish Lists

Colin Coller — Wed, 09 Sep 2009 04:16:56 GMT

Did a quick comparison of the wish list functionality on 5 large .ca e-commerce websites.

	bestbuy.ca	futureshop.ca	sears.ca	costco.ca	chapters.indigo.ca

Ways to view wish list:	2 top nav + my account	1 my account	2 top nav + my account	1 top nav	1 top nav

Ways to add items to wish list:	2	1	1	1	1
Add from product details page?	Y	Y	Y	Y	Y
Add from category page?	Y	N	N	N	N
Add from search results page?	N	N	N	N	N
Add from product comparison page?	N	N	N/A (no comparison)	N/A (no comparison)	N/A (no comparison)

Data displayed on wish list:
Date added?	N	N	Y	N	N
Product name?	Y	Y	Y	Y	Y
Availability?	U (claims to)	U (claims to)	U	Y	Y
Price?	Y	Y	Y	Y	Y
Sales?	N	N	Y	U	Y
Breaks bundles out in details?	Y	Y	N	U	U

Editable data on wish list:
Priority?	N	N	Y (5 point scale, "don't buy this for me" to "must have")	N	N
Quantity desired?	N	N	Y	Y	Y
Comments?	N	N	Y	N	N
Other?	N	N	Y (name, birthday, about me)	N	N

Can be sorted?	N	N	Y (price, priority, date added, last updated)	N	N

Printable view?	N	N	N	N	Y

Can have multiple named baskets?	N	N	N	Y	N

Can be made public or visible to others?	N	N	Y	N	Y
Can be emailed to others?	Y	Y	Y	N	Y

When adding items, navigates to:	wish list page	wish list page	intermediate page (related products, other navigation paths)	remains on product page	wish list page

Can move item from wish list to cart?	Y	Y	Y	Y	Y
When moving item from wish list to cart, navigates to:	remains on wish list page	remains on wish list page	intermediate page (related products, other navigation paths)	remains on wish list page	cart page
After moving item from wish list to cart, item is removed from wish list?	Y	Y	N	N	N

Can move item from cart back to wish list?	Y	N	N ("save for later" not part of wish list)	N	N
When moving item from cart back to wish list, navigates to:	remains on cart page	N/A	N/A	N/A	N/A

Colin

Injecting Commerce Server 2007 Profile Context

Colin Coller — Fri, 04 Sep 2009 19:10:05 GMT

Injecting Commerce Server 2007 Catalog Context demonstrated a simple technique for injecting catalog context and for writing catalog code that can be used on both the web tier and the service tier. The same technique can be used to get a Commerce Server 2007 profile context.

First, we define the factory interface for creating a profile context:

    1 using Microsoft.CommerceServer.Runtime.Profiles;
    2 
    3 namespace MyCommerceApplication
    4 {
    5 
    6     /// <summary>
    7     /// Factory used to create catalog context objects for accessing the Commerce Server profile
    8     /// subsystem.
    9     /// </summary>
   10     public interface IProfileContextFactory
   11     {
   12         #region Methods
   13 
   14         /// <summary>
   15         /// Creates a profile context.
   16         /// </summary>
   17         /// <returns>A <see cref="ProfileContext"/> object.</returns>
   18         ProfileContext CreateProfileContext();
   19 
   20         #endregion // Methods
   21     }
   22 
   23 }

Second, we implement the factory interface using CommerceContext.Current.ProfileSystem for the web tier:

    1 using Microsoft.CommerceServer.Runtime;
    2 using Microsoft.CommerceServer.Runtime.Profiles;
    3 
    4 namespace MyCommerceApplication
    5 {
    6 
    7     /// <summary>
    8     /// A profile context factory that can be used on the web tier.
    9     /// </summary>
   10     public sealed class WebTierProfileContextFactory : IProfileContextFactory
   11     {
   12         #region IProfileContextFactory Members
   13 
   14         /// <summary>
   15         /// Gets the profile system for the current commerce context.
   16         /// </summary>
   17         /// <returns>The current commerce context's <see cref="ProfileContext"/> object.</returns>
   18         public ProfileContext CreateProfileContext()
   19         {
   20             return CommerceContext.Current.ProfileSystem;
   21         }
   22 
   23         #endregion // IProfileContextFactory Members
   24     }
   25 
   26 }

Third, we implement the factory interface for the service tier. This is a bit more involved than creating a catalog context on the service tier was, as there isn't a "ProfileSiteAgent" class or a "ProfileContext.Create" method that does the heavy lifting for us. We need to use CommerceResourceCollection to load the connection strings for the profile subsystem, create a DebugContext, and pass everything into the ProfileContext constructor:

    1 using Microsoft.CommerceServer.Runtime.Configuration;
    2 using Microsoft.CommerceServer.Runtime.Diagnostics;
    3 using Microsoft.CommerceServer.Runtime.Profiles;
    4 
    5 namespace MyCommerceApplication
    6 {
    7 
    8     /// <summary>
    9     /// A profile context factory that can be used on the service tier.
   10     /// </summary>
   11     public class ServiceTierProfileContextFactory : IProfileContextFactory
   12     {
   13         #region IProfileContextFactory Members
   14 
   15         /// <summary>
   16         /// Creates a new profile context.
   17         /// </summary>
   18         /// <returns>A new <see cref="ProfileContext"/> object.</returns>
   19         public ProfileContext CreateProfileContext()
   20         {
   21             CommerceResourceCollection resources;
   22             CommerceResource resource;
   23             string profileServiceConnectionString;
   24             string commerceProviderConnectionString;
   25             string bizDataStoreConnectionString;
   26             DebugContext debugContext;
   27             ProfileContext profileContext;
   28 
   29             // NOTE: This is a trivial implementation of IProfileContextFactory.  A more realistic
   30             // implementation would inject the resources, inject the debug context, have error
   31             // handling, caching, etc.
   32 
   33             resources = new CommerceResourceCollection("MySite"); // TODO: Read the site name from configuration.
   34             resource = resources["Biz Data Service"];
   35             profileServiceConnectionString = (string)resource["s_ProfileServiceConnectionString"];
   36             commerceProviderConnectionString = (string)resource["s_CommerceProviderConnectionString"];
   37             bizDataStoreConnectionString = (string)resource["s_BizDataStoreConnectionString"];
   38             debugContext = new NoOperationDebugContext(DebugMode.Production);
   39             profileContext = new ProfileContext(profileServiceConnectionString, commerceProviderConnectionString, bizDataStoreConnectionString, debugContext);
   40             return profileContext;
   41         }
   42 
   43         #endregion // IProfileContextFactory Members
   44     }
   45 
   46 }

(Note the disclaimer. This is a trivial implementation. If you get your service interfaces right and have a dependency injection strategy, though, you can go a long way with trivial implementations. :)

The rest of the steps are the same as in the original post. We

configure our application's dependency injection framework to map the factory interface to the factory implementation appropriate to the tier;
write code that depends on the factory to create profile contexts, advertising the dependency using DependencyAttribute;
creating a mock implementation of the factory for testing;

That's it. The code written against the factory interface can be used in both the web tier and the service tier without modification and without needing to know where it lives in the solution architecture.

Cheers,

Colin

Don't Put It In The Catalog (1 of ...)

Colin Coller — Thu, 03 Sep 2009 18:48:22 GMT

I don't like storing non-product data in the Commerce Server catalog system. I know some smart people feel differently, and I respect their experience and opinions, but I've seen some incredible abuse of the catalog system. Here's one of the abuses that helped push me into the "If it's not a saleable product, it doesn't go into the catalog." camp.

Background: I've been working on an extremely large e-commerce project for the past 16 months. We took over the project's architecture, design, and implementation from a Microsoft Commerce Server partner, one that had supposedly built large Commerce Server sites before, only to find their solution was very incomplete and had some very significant problems at scale.

My client has a large movie and music catalog, and licenses information about their products from Muze, a leading media information provider. In the original solution, all of this media information was being stored in a catalog. The catalog contained

special non-purchasable products representing artists, albums, discs, tracks, etc;
relationships between non-purchasable products, to associate artists with their albums, albums with their discs, discs with their tracks, and so on; and
relationships between purchasable and non-purchasable products, to associate music products with the artist and album products that contain the media information for the product.

I'm assuming the original team saw some advantages in doing this:

They could edit the media information in Catalog Manager. This would have been helpful during development, but the client wasn't going to do this, and it became increasingly difficult to use as the amount of data increased.
They could stage the media information between environments using CSS. This also would have been helpful, but the client wasn't going to edit or stage this information, so they could have just as easily inserted this information directly into all environments.
They could use the catalog API for all of their data access. They didn't, but they could have.
They didn't need a custom database. They still created custom databases for other components, but they wouldn't have needed one for this one.

However, our team had to deal with the disadvantages, which were much more significant:

The catalogs were huge. An average music product was composed of ~16 different products, plus relationships, including ~12 track products, 1 disc product, 1 album product, 1 artist product, and the actual music product itself. A good-sized music catalog with 100,000 purchasable music products would have translated into ~1.6 million products. The entire Muze catalog would have translated into more than 16 million products.
We needed to write custom code to maintain the data. We couldn't simply take the media information from Muze and bcp it into a database. We needed to write custom code to transform the media information into new products and relationships or updates to existing products and relationships.
We needed to write custom code to retrieve the data. We couldn't simply execute a sproc that would return the media information for a specific product. We needed to write custom code to get the product's related artist and album products, then get the album product's related disc products, then get the disc products' related track products, and so on.
The performance was terrible. Accessing the data for music products was expensive. In some extreme cases it took ~100 queries to retrieve the media information for a single product. Even with multiple layers of caching, the music product detail pages performed terribly, and there was no way to hit our performance targets for those pages.
We couldn't transition the component to non-CS developers. The only people who could work on the component were developers who were familiar with the catalog and the catalog API.

We wound up rewriting the media information component to use a custom database instead of the catalog. This negated the disadvantages above and greatly improved performance. Unfortunately, because the original component was "code complete", this was unplanned work. If the original team had given more thought to the question of where to store the data, or had a default position of "only products in the catalog", we probably wouldn't have had to spend time and money we did on rewriting this component.

Colin

Decrypting ConfigurationSection XML

Colin Coller — Thu, 27 Aug 2009 02:46:29 GMT

I'm working on a project whose configuration system manipulates and deserializes blocks of XML as ConfigurationSection objects. Today we had to make the system support encrypted configuration sections, and we were surprised to find that it wasn't immediately obvious how to do it. The most common answer to the question of "How do I programmatically decrypt a configuration section?" is "Use SectionInformation.UnprotectSection!" Unfortunately, this wouldn't work for us, because we were working with blocks of XML and not ConfigurationSection objects. We needed to decrypt before we could deserialize, but it seemed like we needed to deserialize before we could decrypt. Finally, after much trial and error, many searches, and some Reflector work, we came up with the following:

public static string DecryptConfigurationSectionXml(string xml)
{
    XmlDocument document;
    string providerName;
    ProtectedConfigurationProvider provider;
    XmlNode node;
 
    document = new XmlDocument();
    document.LoadXml(xml);
    providerName = document.DocumentElement.GetAttribute("configProtectionProvider");
    if (!String.IsNullOrEmpty(providerName))
    {
        provider = ProtectedConfiguration.Providers[providerName];
        node = provider.Decrypt(document.DocumentElement);
        xml = node.InnerXml;
    }
    return xml;
}

It's extremely simple, but it took a long time to get to this point, so I thought it worth sharing. :)

Cheers,

Colin

Writing Great Unit Tests

Colin Coller — Tue, 25 Aug 2009 13:06:31 GMT

Steve Sanderson has a great post on writing great unit tests: best and worst practices. The only things I'd add are:

Use a dynamic mock framework like NMock, Rhino Mocks, etc wherever possible to mock your interfaces.
- Don't create static mock implementations of your interfaces only to throw NotImplementedException or return specific values from its functions. Instead, use dynamic mocks.
- Do create static mock implementations of your interfaces where you need to set the same types of expectations over and over again on your mocks. For example, imagine you use an ILoggingService interface to log events, and you want to test several components to ensure they log the correct events in the correct order. Instead of setting up Mock<ILoggingService> in each test, create a reusable MockLoggingService that takes as input the list of events expected to be logged in the expected order, and use it across your tests.
Don't set a lower quality bar for your tests than for your other code.
- Extend your coding standards to your tests. Turn Treat Warnings As Errors on, enforce FxCop rules, enforce StyleCop rules, etc.
- Document your tests. Turn Generate XML Comments on. Require good, meaningful, descriptive comments describing what the code being tested should do, what the test does, and how it relates to other tests.
Train your team on how to write good unit tests.
Review your team's unit tests.

Colin

A Better Product Provider

Colin Coller — Tue, 25 Aug 2009 01:53:11 GMT

I wrote the code for Building Product Business Entities From Commerce Server 2007 Products on my flight this morning. I was sitting next to one of my teammates, we got to talking about the approach, and I wound up writing the ProductProvider class in the post to demonstrate how the mapping factory would work. It's a trivial implementation. Here's a better one.

First, we define the provider interface for getting a product from the catalog:

    1 using MyCommerceApplication.Entities;
    2 
    3 namespace MyCommerceApplication
    4 {
    5 
    6     /// <summary>
    7     /// Provider used to get products from the catalog.
    8     /// </summary>
    9     public interface IProductProvider
   10     {
   11         #region Methods
   12 
   13         /// <summary>
   14         /// Gets a single product from a Commerce Server catalog.
   15         /// </summary>
   16         /// <param name="catalogId">The catalog identifier <see cref="String"/> of the catalog that 
   17         /// the product is to be retrieved from.</param>
   18         /// <param name="productId">The product identifier <see cref="String"/> of the product that
   19         /// is to be retrieved.</param>
   20         /// <param name="cultureName">The name of the culture to use to retrieve culture-specific 
   21         /// resources.</param>
   22         /// <returns>A <see cref="ProductEntityBase"/> if the specified product exists and could be
   23         /// retrieved, or <see langword="null"/> if the product doesn't exist or couldn't be 
   24         /// retrieved.</returns>
   25         ProductEntityBase GetProduct(string catalogId, string productId, string cultureName);
   26 
   27         #endregion // Methods
   28     }
   29 
   30 }

Second, we implement the provider interface in terms of ICatalogContextFactory and IProductMappingFactory:

    1 using System;
    2 using System.Globalization;
    3 using Microsoft.CommerceServer;
    4 using Microsoft.CommerceServer.Catalog;
    5 using Microsoft.Practices.Unity;
    6 using MyCommerceApplication.Entities;
    7 using MyCommerceApplication.Mappings;
    8 
    9 namespace MyCommerceApplication
   10 {
   11 
   12     /// <summary>
   13     /// An <see cref="IProductProvider"/> implementation that gets products from the Commerce
   14     /// Server catalog.
   15     /// </summary>
   16     public class ProductProvider : IProductProvider
   17     {
   18         #region Properties
   19 
   20         /// <summary>
   21         /// Gets or sets the <see cref="ICatalogContextFactory"/> to use to create the catalog 
   22         /// context.
   23         /// </summary>
   24         [Dependency]
   25         public ICatalogContextFactory CatalogContextFactory { get; set; }
   26 
   27         /// <summary>
   28         /// Gets or sets the <see cref="ProductMappingFactory"/> to use to create product mappings.
   29         /// </summary>
   30         [Dependency]
   31         public IProductMappingFactory ProductMappingFactory { get; set; }
   32 
   33         #endregion // Properties
   34 
   35         #region Methods
   36 
   37         /// <summary>
   38         /// Gets the specified product from the specified catalog.
   39         /// </summary>
   40         /// <param name="catalogId">The catalog identifier.</param>
   41         /// <param name="productId">The product identifier.</param>
   42         /// <returns>A <see cref="ProductEntityBase"/> representing the product.</returns>
   43         #region IProductProvider Methods
   44 
   45         /// <summary>
   46         /// Gets a single product from a Commerce Server catalog.
   47         /// </summary>
   48         /// <param name="catalogId">The catalog identifier <see cref="String"/> of the catalog that 
   49         /// the product is to be retrieved from.</param>
   50         /// <param name="productId">The product identifier <see cref="String"/> of the product that
   51         /// is to be retrieved.</param>
   52         /// <param name="cultureName">The name of the culture to use to retrieve culture-specific 
   53         /// resources.</param>
   54         /// <returns>A <see cref="ProductEntityBase"/> if the specified product exists and could be
   55         /// retrieved, or <see langword="null"/> if the product doesn't exist or couldn't be 
   56         /// retrieved.</returns>
   57         public ProductEntityBase GetProduct(string catalogId, string productId, string cultureName)
   58         {
   59             CatalogContext catalogContext;
   60             Product product;
   61             IProductMapping mapping;
   62             ProductEntityBase entity;
   63 
   64             catalogContext = CatalogContextFactory.CreateCatalogContext();
   65             try
   66             {
   67                 product = catalogContext.GetProduct(catalogId, productId, cultureName);
   68             }
   69             catch (EntityDoesNotExistException)
   70             {
   71                 // If the catalog doesn't exist, throw an exception.
   72                 try
   73                 {
   74                     catalogContext.GetCatalog(catalogId, cultureName);
   75                 }
   76                 catch (EntityDoesNotExistException ex)
   77                 {
   78                     throw new InvalidOperationException(String.Format(CultureInfo.InvariantCulture, "Catalog '{0}' does not exist.", catalogId), ex);
   79                 }
   80                 // If the product doesn't exist, return null.
   81                 return null;
   82             }
   83             // If the product's active language isn't the requested culture, throw an exception.
   84             if (!product.ActiveLanguage.Equals(cultureName, StringComparison.OrdinalIgnoreCase))
   85             {
   86                 throw new InvalidOperationException(String.Format(CultureInfo.InvariantCulture, "Catalog '{0}' does not support culture '{1}', returning culture '{2}' instead.", catalogId, cultureName, product.ActiveLanguage));
   87             }
   88             try
   89             {
   90                 mapping = ProductMappingFactory.CreateProductMapping(product.DefinitionName);
   91                 entity = mapping.Map(product);
   92             }
   93             catch (Exception ex)
   94             {
   95                 // If the mapping fails, either because we couldn't get a mapping for the specified
   96                 // definition name or because the mapping threw an exception when trying to perform
   97                 // the map, throw an exception.
   98                 throw new InvalidOperationException(String.Format(CultureInfo.InvariantCulture, "Product '{0}' in catalog '{1}' is malformed.", productId, catalogId), ex);
   99             }
  100             return entity;
  101         }
  102 
  103         #endregion // IProductProvider Methods
  104 
  105         #endregion // Methods
  106     }
  107 
  108 }

This implementation has a few key improvements over the one in the original post:

1. It takes the culture name as a parameter.

2. It returns null if the product doesn't exist. (It could just as easily throw a different exception or return a special type of product entity indicating that the product doesn't exist.)

3. It throws a meaningful exception if the catalog doesn't exist. (This is nice to have, but it could hurt performance depending on your caching strategy and on how many requests you get for products that don't exist.)

4. It throws a meaningful exception if the product isn't returned with the requested culture.

5. It throws a meaningful exception if the product can't be mapped to a business entity.

It's still a very simple implementation (e.g. we normally put caching here, we normally throw specific exceptions for each error condition, etc), but it's better than the original.

Cheers,

Colin

Unity And Singletons

Colin Coller — Mon, 24 Aug 2009 20:07:59 GMT

Brian Button has a great post on using Unity to make Singleton-ness an implementation detail. I couldn't agree more.

Building Product Business Entities From Commerce Server 2007 Products

Colin Coller — Sun, 23 Aug 2009 23:39:30 GMT

Many developers write catalog code against the Commerce Server 2007 Product class, or against a single business entity class that represents all types of products in the catalog, and then use the product's DefinitionName to define behavior like so:

private static void DoSomething(ProductBusinessEntity product)
{
    if ((product.DefinitionName == "WhiteGood") || (product.DefinitionName == "BrownGood"))
    {
        // Do something for appliances, consumer electronics, etc.
    }
    else if (product.DefinitionName == "SoftGood")
    {
        // Do something else for software.
    }
    else if (product.DefinitionName == "Bundle")
    {
        // Do something else for bundles of products.
    }
    else
    {
        // Do something else for all other types of products.
    }
}

This makes their code fragile and harder to understand, test, or extend. Fortunately, it's easy to define a business entity class for each type of product, place type-specific logic into these classes, and to build them up from products using abstract factory and dependency injection. Here's an extremely simple example of how we do it.

(I've already described how we use dependency injection to get catalog context in Injecting Commerce Server 2007 Catalog Context. I've also described how we extend the Product class to get property values in Extension Methods For Commerce Server 2007 Products. This post builds on the concepts and code from these two posts.)

We start with our catalog schema. For this example, I've defined WhiteGood, BrownGood, SoftGood, and Bundle products in the catalog schema.

We then define our business entity class hierarchy, creating a base class for all product types, one class for each product type, and additional base classes as needed where products have properties or methods in common. For this example, I've defined ProductEntityBase (base for all products), HardGoodEntityBase (base for physical products), WhiteGoodEntity, BrownGoodEntity, SoftGoodEntity, and BundleEntity classes:

    1 using System;
    2 
    3 namespace MyCommerceApplication.Entities
    4 {
    5 
    6     /// <summary>
    7     /// <see langword="abstract"/> base class for product entities.
    8     /// </summary>
    9     public abstract class ProductEntityBase
   10     {
   11         #region Properties
   12 
   13         /// <summary>
   14         /// Gets or sets the catalog identifier <see cref="String"/> of the catalog that the 
   15         /// product is from.
   16         /// </summary>
   17         public string CatalogId { get; set; }
   18 
   19         /// <summary>
   20         /// Gets or sets the product identifier.
   21         /// </summary>
   22         public string ProductId { get; set; }
   23 
   24         /// <summary>
   25         /// Gets or sets the product's web identifier.
   26         /// </summary>
   27         public string WebId { get; set; }
   28 
   29         /// <summary>
   30         /// Gets or sets the product's SKU.
   31         /// </summary>
   32         public string Sku { get; set; }
   33 
   34         /// <summary>
   35         /// Gets or sets the product's localized short name.
   36         /// </summary>
   37         public string ShortName { get; set; }
   38 
   39         /// <summary>
   40         /// Gets or sets the product's localized long name.
   41         /// </summary>
   42         public string LongName { get; set; }
   43 
   44         /// <summary>
   45         /// Gets or sets the product's localized short description.
   46         /// </summary>
   47         public string ShortDescription { get; set; }
   48 
   49         /// <summary>
   50         /// Gets or sets the product's localized long description.
   51         /// </summary>
   52         public string LongDescription { get; set; }
   53 
   54         /// <summary>
   55         /// Gets or sets whether the product is enabled.
   56         /// </summary>
   57         public bool IsEnabled { get; set; }
   58 
   59         #endregion // Properties
   60     }
   61 
   62 }

(I've trimmed these to make things easier to follow.)

public abstract class HardGoodEntityBase : ProductEntityBase
{
    public double? LengthInBox { get; set; }
    public double? WidthInBox { get; set; }
    public double? HeightInBox { get; set; }
    public double? LengthOutOfBox { get; set; }
    public double? WidthOutOfBox { get; set; }
    public double? HeightOutOfBox { get; set; }
    public double? WeightInBox { get; set; }
    public double? WeightOutOfBox { get; set; }
}
 
public class WhiteGoodEntity : HardGoodEntityBase { /*...*/ }
public class BrownGoodEntity : HardGoodEntityBase { /*...*/ }
public class SoftGoodEntity : ProductEntityBase { /*...*/ }
public class BundleEntity : ProductEntityBase { /*...*/ }

We then define our mapping interface to map from a Product to a business entity class:

    1 using Microsoft.CommerceServer.Catalog;
    2 using MyCommerceApplication.Entities;
    3 
    4 namespace MyCommerceApplication.Mappings
    5 {
    6 
    7     /// <summary>
    8     /// Mapping used to map Commerce Server products to product business entities.
    9     /// </summary>
   10     public interface IProductMapping
   11     {
   12         #region Methods
   13 
   14         /// <summary>
   15         /// Maps a Commerce Server product to a product business entity.
   16         /// </summary>
   17         /// <param name="product">The <see cref="Product"/> to map from.</param>
   18         /// <returns>The resulting <see cref="ProductEntityBase"/>.</returns>
   19         ProductEntityBase Map(Product product);
   20 
   21         #endregion // Methods
   22     }
   23 
   24 }

We then implement the mapping interface, creating a base class for all mappings and one class for each non-abstract business entity class. We override the MapProperties method in the subclasses to map the properties specific to that type of product onto the corresponding business entity class:

    1 using Microsoft.CommerceServer.Catalog;
    2 using MyCommerceApplication.Entities;
    3 
    4 namespace MyCommerceApplication.Mappings
    5 {
    6 
    7     /// <summary>
    8     /// <see langword="abstract"/> base class for mappings used to map Commerce Server products to 
    9     /// product business entities.
   10     /// </summary>
   11     /// <typeparam name="TProductEntity">The type of <see cref="ProductEntityBase"/> to map the 
   12     /// Commerce Server product to.  <typeparamref name="TProductEntity"/> must have a 
   13     /// <see langword="public"/> parameterless constructor.</typeparam>
   14     public abstract class ProductMappingBase<TProductEntity> : IProductMapping
   15         where TProductEntity : ProductEntityBase, new()
   16     {
   17         #region IProductMapping Members
   18 
   19         /// <summary>
   20         /// Maps the specified Commerce Server product to a product entity.
   21         /// </summary>
   22         /// <param name="product">The <see cref="Product"/> to map from.</param>
   23         /// <returns>The resulting <typeparamref name="ProductEntityBase"/>.</returns>
   24         public ProductEntityBase Map(Product product)
   25         {
   26             TProductEntity entity;
   27 
   28             entity = new TProductEntity();
   29             MapBaseProperties(product, entity);
   30             return entity;
   31         }
   32 
   33         #endregion // IProductMapping Members
   34 
   35         #region Methods
   36 
   37         /// <summary>
   38         /// Maps the base properties of a Commerce Server product to a product entity.
   39         /// </summary>
   40         /// <param name="product">The <see cref="Product"/> to map from.</param>
   41         /// <param name="entity">The <typeparamref name="TProductEntity"/> to map to.</param>
   42         protected virtual void MapBaseProperties(Product product, TProductEntity entity)
   43         {
   44             // Map built-in properties.
   45             entity.ProductId = product.ProductId;
   46             entity.CatalogId = product.CatalogName;
   47             entity.ShortName = product.DisplayName;
   48 
   49             // Map required custom properties.
   50             entity.ShortDescription = product.GetRequiredPropertyValue<string>("ShortDescription");
   51             entity.IsEnabled = product.GetRequiredPropertyValue<bool>("IsEnabled");
   52 
   53             // Map optional custom properties.
   54             entity.WebId = product.GetOptionalPropertyValue<string>("WebId");
   55             entity.LongName = product.GetOptionalPropertyValue<string>("LongName");
   56             entity.LongDescription = product.GetOptionalPropertyValue<string>("LongDescription");
   57 
   58             // ...
   59         }
   60 
   61         #endregion // Methods
   62     }
   63 
   64 }

(Trimmed again.)

public abstract class HardGoodMappingBase<TProductEntity> : ProductMappingBase<TProductEntity>
    where TProductEntity : HardGoodEntityBase, new()
{
    protected override void MapBaseProperties(Product product, TProductEntity entity)
    {
        base.MapBaseProperties(product, entity);
 
        // Map custom properties specific to hard goods.
        entity.LengthInBox = product.GetOptionalPropertyValue<double?>("LengthInBox");
        entity.WidthInBox = product.GetOptionalPropertyValue<double?>("WidthInBox");
        entity.HeightInBox = product.GetOptionalPropertyValue<double?>("HeightInBox");
        entity.LengthOutOfBox = product.GetOptionalPropertyValue<double?>("LengthOutOfBox");
        entity.WidthOutOfBox = product.GetOptionalPropertyValue<double?>("WidthOutOfBox");
        entity.HeightOutOfBox = product.GetOptionalPropertyValue<double?>("HeightOutOfBox");
        entity.WeightInBox = product.GetOptionalPropertyValue<double?>("WeightInBox");
        entity.WeightOutOfBox = product.GetOptionalPropertyValue<double?>("WeightOutOfBox");
    }
}
 
public class WhiteGoodMapping : HardGoodMappingBase<WhiteGoodEntity>
{
    protected override void MapBaseProperties(Product product, WhiteGoodEntity entity)
    {
        base.MapBaseProperties(product, entity);
        // Map custom properties specific to white goods...
    }
}
 
public class BrownGoodMapping : HardGoodMappingBase<BrownGoodEntity> { /*...*/ }
public class SoftGoodMapping : ProductMappingBase<SoftGoodEntity> { /*...*/ }
public class BundleMapping : ProductMappingBase<BundleEntity> { /*...*/ }

At this point in the example, we've got everything we need to map products to business entities. However, we still need to use the product's DefinitionName to figure out which mapping to use to map the product to its business entity, and we still need to create an instance of that mapping. To do this, we define the factory interface for creating a mapping:

    1 using MyCommerceApplication.Mappings;
    2 
    3 namespace MyCommerceApplication
    4 {
    5 
    6     /// <summary>
    7     /// Factory used to create Commerce Server product mappings.
    8     /// </summary>
    9     public interface IProductMappingFactory
   10     {
   11         #region Methods
   12 
   13         /// <summary>
   14         /// Gets the product mapping for the specified definition name.
   15         /// </summary>
   16         /// <param name="definitionName">The definition name of the product mapping that is to be
   17         /// created.</param>
   18         /// <returns>An <see cref="IProductMapping"/> object.</returns>
   19         IProductMapping CreateProductMapping(string definitionName);
   20 
   21         #endregion // Methods
   22     }
   23 
   24 }

We then implement the factory interface using dependency injection, using the supplied definition name to retrieve the correct implementation of IProductMapping from our dependency container:

    1 using System;
    2 using System.Globalization;
    3 using Microsoft.Practices.Unity;
    4 using MyCommerceApplication.Mappings;
    5 
    6 namespace MyCommerceApplication
    7 {
    8 
    9     /// <summary>
   10     /// An <see cref="IProductMappingFactory"/> implementation that resolves mappings using a
   11     /// dependency injection container.
   12     /// </summary>
   13     public class ProductMappingFactory : IProductMappingFactory
   14     {
   15         #region Properties
   16 
   17         /// <summary>
   18         /// Gets or sets the dependency injection container to use to resolve dependencies.
   19         /// </summary>
   20         /// <remarks>
   21         /// <para>
   22         /// <see cref="ProductMappingFactory"/> uses the <see cref="IUnityContainer"/> to resolve 
   23         /// mappings by name.
   24         /// </para>
   25         /// </remarks>
   26         [Dependency]
   27         public IUnityContainer Container { get; set; }
   28 
   29         #endregion // Properties
   30 
   31         #region IProductMappingFactory Members
   32 
   33         /// <summary>
   34         /// Gets the product mapping for the specified definition name.
   35         /// </summary>
   36         /// <param name="definitionName">The definition name of the product mapping that is to be
   37         /// created.</param>
   38         /// <returns>An <see cref="IProductMapping"/> object.</returns>
   39         /// <exception cref="InvalidOperationException">Throw if <see cref="IProductMapping"/> 
   40         /// is not registered with the specified definition name in the dependency injection
   41         /// container.</exception>
   42         public IProductMapping CreateProductMapping(string definitionName)
   43         {
   44             try
   45             {
   46                 return Container.Resolve<IProductMapping>(definitionName);
   47             }
   48             catch (ResolutionFailedException ex)
   49             {
   50                 throw new InvalidOperationException(String.Format(CultureInfo.InvariantCulture, "Product definition name '{0}' is unknown.", definitionName), ex);
   51             }
   52         }
   53 
   54         #endregion // IProductMappingFactory Members
   55     }
   56 
   57 }

(Note that the factory implementation advertises that it needs an IUnityContainer. In order for the factory to do its work, the UnityContainer that builds up the factory must be registered as the instance of IUnityContainer:

container = new UnityContainer();
container.RegisterInstance<IUnityContainer>(container);

We usually register a container with itself as soon as it's created so we can do this sort of thing. However, we generally only use this technique in factories. It's easy to abuse.)

We then configure our application's dependency injection framework to map the factory interface to the factory implementation, and to map the mapping interface to the various named mapping implementations:

    1 <?xml version="1.0" encoding="utf-8" ?>
    2 <configuration>
    3 
    4   <configSections>
    5     <section name="dependencyInjectionConfiguration" type="Microsoft.Practices.Unity.Configuration.UnityConfigurationSection, Microsoft.Practices.Unity.Configuration, Version=1.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    6     <!-- ... -->
    7   </configSections>
    8 
    9   <dependencyInjectionConfiguration>
   10     <typeAliases>
   11       <typeAlias alias="singleton" type="Microsoft.Practices.Unity.ContainerControlledLifetimeManager, Microsoft.Practices.Unity" />
   12     </typeAliases>
   13     <containers>
   14       <container>
   15         <types>
   16 
   17           <!-- CatalogContextFactory, from my earlier post. -->
   18           <type type="MyCommerceApplication.ICatalogContextFactory, MyCommerceApplication" mapTo="MyCommerceApplication.WebTierCatalogContextFactory, MyCommerceApplication">
   19             <lifetime type="singleton" />
   20           </type>
   21 
   22           <!-- Map IProductMappingFactory to ProductMappingFactory. -->
   23           <type type="MyCommerceApplication.IProductMappingFactory, MyCommerceApplication" mapTo="MyCommerceApplication.ProductMappingFactory, MyCommerceApplication">
   24             <lifetime type="singleton" />
   25           </type>
   26 
   27           <!-- Map IProductMapping to the different mapping classes by definition name. -->
   28           <type type="MyCommerceApplication.Mappings.IProductMapping, MyCommerceApplication" mapTo="MyCommerceApplication.Mappings.WhiteGoodMapping, MyCommerceApplication" name="WhiteGood">
   29             <lifetime type="singleton" />
   30           </type>
   31           <type type="MyCommerceApplication.Mappings.IProductMapping, MyCommerceApplication" mapTo="MyCommerceApplication.Mappings.BrownGoodMapping, MyCommerceApplication" name="BrownGood">
   32             <lifetime type="singleton" />
   33           </type>
   34           <type type="MyCommerceApplication.Mappings.IProductMapping, MyCommerceApplication" mapTo="MyCommerceApplication.Mappings.SoftGoodMapping, MyCommerceApplication" name="SoftGood">
   35             <lifetime type="singleton" />
   36           </type>
   37           <type type="MyCommerceApplication.Mappings.IProductMapping, MyCommerceApplication" mapTo="MyCommerceApplication.Mappings.BundleMapping, MyCommerceApplication" name="Bundle">
   38             <lifetime type="singleton" />
   39           </type>
   40           <!-- ... -->
   41 
   42         </types>
   43       </container>
   44     </containers>
   45   </dependencyInjectionConfiguration>
   46 
   47   <!-- ... -->
   48 
   49 </configuration>

(Our factory and our mappings are stateless and thread-safe, so we use the ContainerControlledLifetimeManager to make them singletons, and inject the same instance over and over again.)

Finally, we with all this in place, we can write code that depends on the factory to get a mapping, and on the mapping to convert the Product to the corresponding business entity. Here's an example of a product provider that uses the factories we've defined to get products from the catalog:

    1 using Microsoft.CommerceServer.Catalog;
    2 using Microsoft.Practices.Unity;
    3 using MyCommerceApplication.Entities;
    4 using MyCommerceApplication.Mappings;
    5 
    6 namespace MyCommerceApplication
    7 {
    8 
    9     /// <summary>
   10     /// An <see cref="IProductProvider"/> implementation that gets products from the Commerce
   11     /// Server catalog.
   12     /// </summary>
   13     public class ProductProvider : IProductProvider
   14     {
   15         #region Properties
   16 
   17         /// <summary>
   18         /// Gets or sets the <see cref="ICatalogContextFactory"/> to use to create the catalog 
   19         /// context.
   20         /// </summary>
   21         [Dependency]
   22         public ICatalogContextFactory CatalogContextFactory { get; set; }
   23 
   24         /// <summary>
   25         /// Gets or sets the <see cref="ProductMappingFactory"/> to use to create product mappings.
   26         /// </summary>
   27         [Dependency]
   28         public IProductMappingFactory ProductMappingFactory { get; set; }
   29 
   30         #endregion // Properties
   31 
   32         #region Methods
   33 
   34         /// <summary>
   35         /// Gets the specified product from the specified catalog.
   36         /// </summary>
   37         /// <param name="catalogId">The catalog identifier.</param>
   38         /// <param name="productId">The product identifier.</param>
   39         /// <returns>A <see cref="ProductEntityBase"/> representing the product.</returns>
   40         public ProductEntityBase GetProduct(string catalogId, string productId)
   41         {
   42             CatalogContext context;
   43             Product product;
   44             IProductMapping mapping;
   45             ProductEntityBase entity;
   46 
   47             context = CatalogContextFactory.CreateCatalogContext(); // Defined in an earlier post.
   48             product = context.GetProduct(catalogId, productId);
   49             mapping = ProductMappingFactory.CreateProductMapping(product.DefinitionName);
   50             entity = mapping.Map(product);
   51             return entity;
   52         }
   53 
   54         #endregion // Methods
   55     }
   56 
   57 }

(In production you'd want error handling, caching, etc here.)

This might seem like a lot of code, but it's relatively simple, easy to understand, and easy to test. It also has two key benefits:

1. The business logic in the original example can be placed in the appropriate business entity classes, inherited, overridden, etc.

public abstract class ProductEntityBase
{
    #region Methods
 
    /// <summary>
    /// Does something.
    /// </summary>
    public virtual void DoSomething()
    {
        // ...
    }
 
    #endregion // Methods
 
    // ...
 
}
 
public abstract class HardGoodEntityBase : ProductEntityBase
{
    public override void DoSomething()
    {
        // Do something different when the product is a hardgood.
    }
}

2. The code can be easily extended to support new product types. Adding a new product type is as simple as adding a new business entity class, a new mapping class, and the necessary configuration to map the definition name to the mapping:

public class GiftCardEntity : HardGoodEntityBase { /*...*/ }
 
public class GiftCardMapping : ProductMappingBase<GiftCardEntity> { /*...*/ }
 
<type type="MyCommerceApplication.Mappings.IProductMapping, MyCommerceApplication" mapTo="MyCommerceApplication.Mappings.GiftCardMapping, MyCommerceApplication" name="GiftCard">
  <lifetime type="singleton" />
</type>

There's no need to crack open the existing code and change banks of hard-coded if/else or switch statements, as in the original example.

Again, this is an extremely simple technique, but it's one I haven't seen many developers use.

Cheers,

Colin