Share via

Commerce Modules

  • Article

Commerce Modules are an extension of the ASP.NET runtime, and are based on the HTTP module architecture that the runtime provides. Commerce Modules encapsulate the automatic configuration of all Commerce Server Application Runtime components. The CommerceModule class is the base class from which all Commerce Modules derive. After an application is loaded into the Commerce Server Application Runtime, you can use the CommerceContext class to access all page and application scope components provided by Commerce Server from within the global.asax file, a Web form, or any custom component.

Using Commerce Modules decreases the amount of code you need to write in the global.asa file and on individual ASP pages to initialize components. The initialization code is encapsulated in Commerce Modules that read configuration data from the web.config file.

Some Commerce Modules are configurable and some are not. If the Commerce Module is configurable, the module will reference the associated IConfigurationSectionHandler interface. IConfigurationSectionHandler interface instances are defined in the <configSections><sectionGroup name="Commerce Server"> section of the web.config file, as shown in the preceding sample web.config file. Commerce Modules are defined and initialized in the <system.web><httpModules> section of the web.config file.

The following tables contain quick reference information for each of the Commerce Modules.

CommerceApplicationModule Description
Module description By definition, an application must use CommerceApplicationModule to be considered a Commerce Server .NET Application Framework application. All other CommerceModules depend on the CommerceApplicationModule.
Public properties 
public static string SiteName { 
get; }
public static
CommerceResourceCollection 
Resources { get; }
public static PipelineCollection
Pipelines { get; }
public static DebugContext 
DebugContext { get; set; }
Configuration section read 
<application>
CommerceContext properties set 
public string SiteName { get; }
public CommerceResourceCollection 
Resources { get; }
public PipelineCollection Pipelines 
{ get; }
public DebugContext DebugContext { 
get; }
Event handlers The OnBeginRequest event creates an instance of the CommerceContext class and stores it in the HttpContext.Current.Items collection for retrieval by the CommerceContext.Current static property.

The OnEndRequest event disposes of the current CommerceContext class instance and all of the disposables it is managing.
Resource dependencies None
Module dependencies None
CommerceAuthenticationModule Description
Module description Provides a framework for managing authentication of site visitors. Provides the means for client-side cookie detection and creates an instance of AuthManagerInfo at page scope.
Public properties None
Configuration section read 
<authentication>
CommerceContext properties set 
public AuthManagerInfo 
AuthManagerInfo { get; }
Event handlers The OnBeginRequest event creates an instance of the AuthManagerInfo class and sets CommerceContext.AuthManagerInfo.
Resource dependencies Authentication resource
Module dependencies CommerceApplicationModule
CommerceCacheModule Description
Module description Creates the collection of CacheManager caches used on the site.
Public properties 
public static 
CommerceCacheCollection 
CacheCollection { get; }
Configuration section read 
<caches>
CommerceContext properties set 
public CommerceCacheCollection 
Caches { get; }
Event handlers None
Resource dependencies The Campaigns resource is a dependency only if a cache of type advertising or discounts has been configured.

The Transactions Config resource is a dependency if a cache of type tax, shipping, or QCI has been configured.
Module dependencies CommerceApplicationModule
CommerceCatalogModule Description
Module description Creates a default CatalogContext object for the site.
Public properties 
public static CatalogContext 
CatalogContext { get; }
Configuration section read 
<catalog>
CommerceContext properties set 
public CatalogContext CatalogSystem 
{ get; set; }
Event handlers The OnBeginRequest event sets CommerceContext.CatalogSystem.
Resource dependencies Product Catalog System
Module dependencies CommerceApplicationModule
CommerceOrderModule Description
Module description Creates a default OrderContext object for the site.
Public properties 
public static OrderContext 
OrderContext { get; }
Configuration section read None
CommerceContext properties set 
public OrderContext OrderSystem { 
get; set; }
Event handlers The OnBeginRequest event sets CommerceContext.OrderSystem.
Resource dependencies Transactions resource
Module dependencies CommerceApplicationModule
CommerceProfileModule Description
Module description Creates a default ProfileContext object for the site.
Public properties 
public static ProfileContext 
ProfileContext { get; }
public static 
CommerceProviderContext 
ProviderContext { get; }
Configuration section read profiles
CommerceContext properties set 
Public ProfileContext ProfileSystem 
{ get; set; }
Public CommerceProviderContext 
ProviderContext { get; set; }
Event handlers The OnBeginRequest event sets CommerceContext.ProfileSystem.
Resource dependencies Profiles resource
Module dependencies CommerceApplicationModule
CommerceContentSelectionModule Description
Module description Creates the collection of ContentSelectionContext objects available for site usage.
Public properties 
public static 
ContentSelectionContextCollection 
ContentSelectionContexts { get; }
Configuration section read 
<contentSelection>
CommerceContext properties set 
public 
ContentSelectionContextCollection 
TargetingSystem.SelectionContexts { 
get; }
Event handlers None
Resource dependencies None
Module dependencies CommerceApplicationModule
CommerceCacheModule
CommerceExpressionModule
CommerceExpressionModule Description
Module description Creates an ExpressionEvaluator component for use on the site.
Public properties 
public static ExpressionEvaluator 
ExpressionEvaluator { get; }
Configuration section read None
CommerceContext properties set 
Public ExpressionEvaluator 
TargetingSystem.ExpressionEvaluator 
{ get; }
Event handlers None
Resource dependencies Profiles resource
Module dependencies CommerceApplicationModule

Enabling CommerceModules in the web.config File

Module Design Patterns

Exposing Resources Created by a Commerce Module

Building Commerce Modules

Enabling CommerceModules in the web.config File

The set of Commerce Modules available for use in the site must be configured in the <httpModules> section of the web.config file. The order in which the modules appear in the web.config file is significant. Any module dependent upon another module must be listed after the module on which it is dependent.

The CommerceApplicationModule class is a requirement for an application to be considered part of a .NET-based Commerce Server application, and it must be listed before all other CommerceModules classes in the <httpModules> section in the web.config file.

The following code sample shows what the <httpModules> section would look like for an application that used only the CommerceApplicationModule, CommerceOrderModule, and CommerceCatalogModule classes:

<httpModules>
            <add name="CommerceApplication" type="Microsoft.CommerceServer.Runtime.CommerceApplicationModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceOrder" type="Microsoft.CommerceServer.Runtime.Orders.CommerceOrderModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceCatalog" type="Microsoft.CommerceServer.Runtime.Catalog.CommerceCatalogModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
</httpModules>

See Also

.NET Class Reference

CommerceModule Class

CommerceApplicationModule Class

CommerceCatalogModule Class

CommerceOrderModule

Module Design Patterns

A Commerce Module is responsible for creating a resource that will be used on site pages. The module can either create a single instance of the resource, or it can create a different instance of the resource for each instance of the HttpApplication class that is created in the ASP.NET application. This topic describes the issues that should be considered when making this design decision.

The multiple-instance pattern is simplest to implement. The Init method of the module simply creates the resource and stores it in an instance field.

The singleton pattern is a little more complex to implement. The first time the Init method is called for any instance, the module creates the resource and stores it in a static field. This must be done in a way that uses locking to avoid a race condition that might cause multiple instances of the resource to be created. The following code sample demonstrates the singleton pattern:

public sealed class SampleModule : CommerceModule
{
   // The resource the module is responsible for creating
   private static SampleResource sampleResource;
   
// The key name used to store the resource in the HttpContext Items 
// collection
   private const string sampleResourceKey = "SampleCommerceResource";

   // Flag: has this instance been disposed
   private int disposed = false;

   // CommerceModule.Init implementation
   public override void Init(HttpApplication appInstance)
   {
      // First declare module and resource dependencies using the
      // CommerceModule protected helper methods.  These will throw
      // CommerceResourceDependencyExceptions or
      // CommerceModuleDependencyExceptions if the dependencies don't exist
      
      // "SampleResourceName" is some custom Commerce Server site resource
      DeclareResourceDependency("SampleResourceName");
      
      // This module depends on the CatalogModule having been initialized
      // in the pipeline before this module.
      DeclareModuleDependency("CommerceCatalogModule");
   
      // Create the singleton instance of the resource
      if (sampleResource == null)
      {
         // Lock to prevent race conditions and ensure that exactly one
         // instance of the resource is created
         lock (typeof(SampleModule))
         {
            if (sampleResource == null)
               sampleResource = CreateResource();
         }
      }      
   
      // subscribe to BeginRequest events
      appInstance.BeginRequest += new EventHandler(OnBeginRequest);   
   }

   // BeginRequest event handler
   public void OnBeginRequest(Object sender, EventArgs e)
   {
      HttpContext ctx = HttpContext.Current;
      if (ctx != null)
         ctx.Items[sampleResourceKey] = sampleResource;
   }

   // If there are any resources that need to be disposed of, override
   // the Dispose(bool) method from the base class.  This will be called
   // when the module instance is disposed.

   protected override void Dispose(bool disposing)
   {
      // Check to see if Dispose has already been called.
      if(!this.disposed)
      {
         this.disposed = true;         
            // If disposing equals true, dispose all managed 
         // and unmanaged resources.
         if(disposing)
         {
            // Dispose managed resources.
         }
         // Release unmanaged resources. If disposing is false, 
         // only the following code is executed.
         // ...

         // Now call the base class's dispose:
         base.Dispose(disposing);
      }
   }

}

Exposing Resources Created by a Commerce Module

It is recommended that Commerce Modules subscribe to the BeginRequest event of the HttpApplication class. When the event is handled, it copies a reference to the resources that it created in the Init method into the HttpContext.Current.Items collection using a well known, unique, and documented key. The Web form then only needs to retrieve the reference of the resource from the Items collection and assign the appropriate type to it.

For modules supplied with the core Commerce Server .NET Application Framework, the references are copied into a strongly typed property in the CommerceContext class. This is more convenient for you to access and it avoids the cost of a hash table lookup and a run-time type cast.

Building Commerce Modules

While Commerce Modules are an extension to the HTTP module architecture in ASP.NET, it is recommended that you implement or build Commerce Modules instead of implementing the IHttpModule interface. This is because inheriting from the CommerceModule class allows Commerce Server to manage the dependencies between modules in the application.

A third party providing extensions or plug-ins for the Commerce Server platform should build a Commerce Module if any of the following are true:

  • The extension depends on a resource or resources in the Commerce Server Administration database.
  • The extension depends on other Commerce Server modules.
  • The extension requires global configuration before its functionality is used on site pages.
  • The extension needs to subscribe to request processing events raised by the HttpApplication class.
  • Other Commerce Modules might depend on this module being configured.

See Also

Commerce Server Application Runtime

CommerceModule Class (BCL)

Copyright © 2005 Microsoft Corporation.
All rights reserved.