Commerce Modules

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.

public static string SiteName { 
get; }
public static
CommerceResourceCollection 
Resources { get; }
public static PipelineCollection
Pipelines { get; }
public static DebugContext 
DebugContext { get; set; }

<application>

public string SiteName { get; }
public CommerceResourceCollection 
Resources { get; }
public PipelineCollection Pipelines 
{ get; }
public DebugContext DebugContext { 
get; }

<authentication>

public AuthManagerInfo 
AuthManagerInfo { get; }

public static 
CommerceCacheCollection 
CacheCollection { get; }

<caches>

public CommerceCacheCollection 
Caches { get; }

public static CatalogContext 
CatalogContext { get; }

<catalog>

public CatalogContext CatalogSystem 
{ get; set; }

public static OrderContext 
OrderContext { get; }

public OrderContext OrderSystem { 
get; set; }

public static ProfileContext 
ProfileContext { get; }
public static 
CommerceProviderContext 
ProviderContext { get; }

Public ProfileContext ProfileSystem 
{ get; set; }
Public CommerceProviderContext 
ProviderContext { get; set; }

public static 
ContentSelectionContextCollection 
ContentSelectionContexts { get; }

<contentSelection>

public 
ContentSelectionContextCollection 
TargetingSystem.SelectionContexts { 
get; }

public static ExpressionEvaluator 
ExpressionEvaluator { get; }

Public ExpressionEvaluator 
TargetingSystem.ExpressionEvaluator 
{ get; }

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.